instar 1.3.6 → 1.3.7

package/dist/feedback-factory/processor/fingerprint.d.ts

@@ -0,0 +1,45 @@
+/**
+ * fingerprint.ts — TypeScript port of the feedback-factory dedup fingerprinter.
+ *
+ * Scar (b) of docs/specs/feedback-factory-migration.md. Byte-exact port of
+ * `compute_fingerprint` + its `extract_component` dependency from the reference
+ * `the-portal/.claude/scripts/feedback-processor.py` (verified against Dawn's
+ * line refs 2026-05-26: compute_fingerprint :227, extract_component :191,
+ * SEVERITY sets :182/:186). This decides whether two reports are the SAME bug —
+ * the single most correctness-critical port in the migration.
+ *
+ * Equivalence to the Python is proven EMPIRICALLY by the parity harness
+ * (scripts/feedback-factory/fingerprint-parity.mjs), not by reasoning alone:
+ * Python and JS differ on regex character classes (`\d`/`\w`/`\b` are Unicode
+ * in Python without re.ASCII, ASCII in JS), `.lower()` vs `.toLowerCase()`, and
+ * whitespace stripping. The port below mirrors Python's Unicode semantics where
+ * JS can (`u` flag + Unicode property escapes); the harness's adversarial corpus
+ * (non-ASCII digits, em-dash, NBSP, NFC/NFD, Turkish-İ/ß) is the gate that
+ * catches any residual divergence. Do NOT "simplify" a regex without re-running
+ * the harness — that is exactly how the silent history-fork ships.
+ */
+/**
+ * Port of Python `extract_component(title)` (:191). Strips a leading [TAG] and a
+ * whitelisted severity prefix, then returns the first dotted identifier
+ * (e.g. "gitsync.pull") or the first word, lowercased; "" if none.
+ *
+ * Python `\w` is Unicode (no re.ASCII); JS `\w` is ASCII. We use `\p{L}\p{N}_`
+ * under the `u` flag to mirror Python's Unicode word-char semantics. `re.match`
+ * is start-anchored — the `^` anchors below make `.match()` equivalent.
+ */
+export declare function extractComponent(title: string): string;
+/**
+ * Port of Python `compute_fingerprint(type, title, component="")` (:227).
+ * Normalizes the title (lowercase; collapse versions / hashes / bare ints /
+ * whitespace) and returns the first 32 hex chars of SHA-256 over
+ * `type|component|normalized_title`. `v1.1.0` and `v1.1.1` collapse to the same
+ * fingerprint → same bug.
+ *
+ * Python `re.sub` is global → JS needs the `g` flag. Python `\d`/`\w`/`\b` are
+ * Unicode (no re.ASCII): `\d`→`\p{Nd}`, `\w`→`[\p{L}\p{N}_]` under `u`. JS has no
+ * native Unicode `\b`; the hash/int strips below keep ASCII-hex/`\p{Nd}` content
+ * with `\b` — the parity harness verifies the boundary behavior against the
+ * Python on the adversarial corpus.
+ */
+export declare function computeFingerprint(type: string, title: string, component?: string): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/feedback-factory/processor/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/processor/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAaH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAwBtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,MAAM,CAuBtF"}

package/dist/feedback-factory/processor/fingerprint.js

@@ -0,0 +1,97 @@
+/**
+ * fingerprint.ts — TypeScript port of the feedback-factory dedup fingerprinter.
+ *
+ * Scar (b) of docs/specs/feedback-factory-migration.md. Byte-exact port of
+ * `compute_fingerprint` + its `extract_component` dependency from the reference
+ * `the-portal/.claude/scripts/feedback-processor.py` (verified against Dawn's
+ * line refs 2026-05-26: compute_fingerprint :227, extract_component :191,
+ * SEVERITY sets :182/:186). This decides whether two reports are the SAME bug —
+ * the single most correctness-critical port in the migration.
+ *
+ * Equivalence to the Python is proven EMPIRICALLY by the parity harness
+ * (scripts/feedback-factory/fingerprint-parity.mjs), not by reasoning alone:
+ * Python and JS differ on regex character classes (`\d`/`\w`/`\b` are Unicode
+ * in Python without re.ASCII, ASCII in JS), `.lower()` vs `.toLowerCase()`, and
+ * whitespace stripping. The port below mirrors Python's Unicode semantics where
+ * JS can (`u` flag + Unicode property escapes); the harness's adversarial corpus
+ * (non-ASCII digits, em-dash, NBSP, NFC/NFD, Turkish-İ/ß) is the gate that
+ * catches any residual divergence. Do NOT "simplify" a regex without re-running
+ * the harness — that is exactly how the silent history-fork ships.
+ */
+import { createHash } from 'node:crypto';
+// Python: SEVERITY_PREFIXES (:182) / SEVERITY_PHRASES (:186) — byte-for-byte.
+const SEVERITY_PREFIXES = new Set([
+    'DEGRADATION', 'ALERT', 'VERIFIED', 'CRITICAL', 'RECURRING',
+    'PATTERN', 'WARNING', 'BUG', 'FEATURE', 'WONTFIX',
+]);
+const SEVERITY_PHRASES = new Set([
+    'VERIFIED FIX', 'WONTFIX', 'BUG REPORT',
+]);
+/**
+ * Port of Python `extract_component(title)` (:191). Strips a leading [TAG] and a
+ * whitelisted severity prefix, then returns the first dotted identifier
+ * (e.g. "gitsync.pull") or the first word, lowercased; "" if none.
+ *
+ * Python `\w` is Unicode (no re.ASCII); JS `\w` is ASCII. We use `\p{L}\p{N}_`
+ * under the `u` flag to mirror Python's Unicode word-char semantics. `re.match`
+ * is start-anchored — the `^` anchors below make `.match()` equivalent.
+ */
+export function extractComponent(title) {
+    if (!title)
+        return '';
+    let t = title;
+    // Python :208 — strip [TAG] prefix: re.sub(r'^\[([A-Z_]+)\]\s*', '', t)
+    t = t.replace(/^\[([A-Z_]+)\]\s*/u, '');
+    // Python :211 — strip a whitelisted severity prefix only (never arbitrary
+    // uppercase-colon): re.match(r'^([A-Z][A-Z\s]*?):\s*', t)
+    const sev = t.match(/^([A-Z][A-Z\s]*?):\s*/u);
+    if (sev) {
+        const candidate = sev[1].trim();
+        if (SEVERITY_PHRASES.has(candidate) || SEVERITY_PREFIXES.has(candidate)) {
+            t = t.slice(sev[0].length);
+        }
+    }
+    // Python :218 — dotted identifier first: ^([A-Za-z][\w]*(?:\.[A-Za-z][\w]*)+)
+    const dotted = t.match(/^([A-Za-z][\p{L}\p{N}_]*(?:\.[A-Za-z][\p{L}\p{N}_]*)+)/u);
+    if (dotted)
+        return dotted[1].toLowerCase();
+    // Python :223 — fallback to first word: ^([A-Za-z][\w]+)
+    const word = t.match(/^([A-Za-z][\p{L}\p{N}_]+)/u);
+    return word ? word[1].toLowerCase() : '';
+}
+/**
+ * Port of Python `compute_fingerprint(type, title, component="")` (:227).
+ * Normalizes the title (lowercase; collapse versions / hashes / bare ints /
+ * whitespace) and returns the first 32 hex chars of SHA-256 over
+ * `type|component|normalized_title`. `v1.1.0` and `v1.1.1` collapse to the same
+ * fingerprint → same bug.
+ *
+ * Python `re.sub` is global → JS needs the `g` flag. Python `\d`/`\w`/`\b` are
+ * Unicode (no re.ASCII): `\d`→`\p{Nd}`, `\w`→`[\p{L}\p{N}_]` under `u`. JS has no
+ * native Unicode `\b`; the hash/int strips below keep ASCII-hex/`\p{Nd}` content
+ * with `\b` — the parity harness verifies the boundary behavior against the
+ * Python on the adversarial corpus.
+ */
+export function computeFingerprint(type, title, component = '') {
+    if (!component) {
+        component = extractComponent(title);
+    }
+    let normalized = title.toLowerCase();
+    // :237 — re.sub(r'v?\d+\.\d+\.\d+(-[\w.]+)?', 'vN', s). Python `\d`/`\w` are
+    // Unicode → `\p{Nd}` / `[\p{L}\p{N}_.]`. No `\b` here, so no boundary concern.
+    normalized = normalized.replace(/v?\p{Nd}+\.\p{Nd}+\.\p{Nd}+(-[\p{L}\p{N}_.]+)?/gu, 'vN');
+    // :238 — re.sub(r'\b[0-9a-f]{8,}\b', 'HASH', s). Python `\b` is a UNICODE word
+    // boundary; JS `\b` is ASCII-only. Emulate with lookarounds over the Unicode
+    // word-char set `[\p{L}\p{N}_]` (≈ Python `\w`) so adjacency to a non-ASCII
+    // letter/digit behaves like the reference.
+    normalized = normalized.replace(/(?<![\p{L}\p{N}_])[0-9a-f]{8,}(?![\p{L}\p{N}_])/gu, 'HASH');
+    // :239 — re.sub(r'\b\d+\b', 'N', s). Same Unicode-boundary emulation; `\d` →
+    // `\p{Nd}` (Python Unicode digits, e.g. arabic-indic ٥, which ASCII `\b` misses).
+    normalized = normalized.replace(/(?<![\p{L}\p{N}_])\p{Nd}+(?![\p{L}\p{N}_])/gu, 'N');
+    // :240 — re.sub(r'\s+', ' ', s).strip()
+    normalized = normalized.replace(/\s+/gu, ' ').trim();
+    // :242-243 — sha256 over UTF-8 bytes of "type|component|normalized", 32 hex chars
+    const raw = `${type.toLowerCase()}|${component.toLowerCase()}|${normalized}`;
+    return createHash('sha256').update(raw, 'utf8').digest('hex').slice(0, 32);
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/feedback-factory/processor/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../../src/feedback-factory/processor/fingerprint.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.6",
+  "version": "1.3.7",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/feedback-factory/_py_fingerprint_ref.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Parity reference: compute fingerprints using the REAL feedback-processor.py.
+
+Imports the reference processor (the-portal/.claude/scripts/feedback-processor.py)
+WITHOUT running its CLI main (it has an `if __name__ == '__main__'` guard; loading
+under a different module name keeps that dormant), then calls its actual
+compute_fingerprint over the shared corpus. Emits JSON to stdout so the Node
+harness can diff the TS port against this ground truth.
+
+Usage: python3 _py_fingerprint_ref.py <processor_path> <corpus_path>
+"""
+import sys
+import json
+import importlib.util
+
+
+def load_processor(path):
+    spec = importlib.util.spec_from_file_location("_feedback_processor_ref", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)  # safe: top-level is imports + constants + defs; DB work is inside cmd_* only
+    return mod
+
+
+def main():
+    if len(sys.argv) != 3:
+        print("usage: _py_fingerprint_ref.py <processor_path> <corpus_path>", file=sys.stderr)
+        sys.exit(2)
+    processor_path, corpus_path = sys.argv[1], sys.argv[2]
+    proc = load_processor(processor_path)
+    with open(corpus_path, encoding="utf-8") as f:
+        corpus = json.load(f)
+    out = []
+    for case in corpus["cases"]:
+        t = case["type"]
+        title = case["title"]
+        component = case.get("component", "")
+        fp = proc.compute_fingerprint(t, title, component)
+        out.append({"type": t, "title": title, "component": component, "fp": fp})
+    sys.stdout.write(json.dumps(out, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/feedback-factory/fingerprint-corpus.json

@@ -0,0 +1,38 @@
+{
+  "_comment": "Parity corpus for the feedback fingerprint port. Real cases + the adversarial Unicode/encoding/whitespace cases the convergence flagged. Each entry: {type, title, component?}. The parity harness asserts the TS port produces byte-identical fingerprints to the reference Python (the-portal/.claude/scripts/feedback-processor.py) for every entry. Tricky code points are written as \\u escapes so both json.load (Python) and JSON.parse (Node) decode identical bytes.",
+  "cases": [
+    { "type": "bug", "title": "GitSync.pull fails intermittently" },
+    { "type": "bug", "title": "StateManager.listSessions returns stale data" },
+    { "type": "bug", "title": "auth token refresh broken in v1.1.0" },
+    { "type": "bug", "title": "auth token refresh broken in v1.1.1" },
+    { "type": "bug", "title": "auth token refresh broken in v2.13.4-beta.2" },
+    { "type": "feature", "title": "[DEGRADATION] StateManager.listSessions timeout" },
+    { "type": "bug", "title": "[ALERT] GitSync.pull deadlock" },
+    { "type": "bug", "title": "CRITICAL: auth refresh broken" },
+    { "type": "bug", "title": "VERIFIED FIX: GitSync.pull race" },
+    { "type": "bug", "title": "BUG REPORT: session reaper kills active session" },
+    { "type": "bug", "title": "WONTFIX: legacy thing" },
+    { "type": "bug", "title": "NOTASEVERITY: should not be stripped" },
+    { "type": "bug", "title": "commit abc123def4567890 broke the build" },
+    { "type": "bug", "title": "deadbeefcafe1234 hash in title" },
+    { "type": "bug", "title": "retry 5 times then 12 failures at 300 seconds" },
+    { "type": "bug", "title": "lowercase already and simple" },
+    { "type": "bug", "title": "Title   With    Irregular     Spacing" },
+    { "type": "bug", "title": "   leading and trailing whitespace   " },
+    { "type": "bug", "title": "" },
+    { "type": "bug", "title": "[TAG] only a tag then word" },
+    { "type": "bug", "title": "Component.sub.deep.path.identifier works" },
+    { "type": "BUG", "title": "Type Case BUG vs bug", "component": "Explicit.Component" },
+    { "type": "bug", "title": "version ٣.١.٠ with arabic-indic digits" },
+    { "type": "bug", "title": "bare arabic-indic ٥ digit here" },
+    { "type": "bug", "title": "em dash — separates words" },
+    { "type": "bug", "title": "non breaking space title" },
+    { "type": "bug", "title": "café composed NFC" },
+    { "type": "bug", "title": "café decomposed NFD" },
+    { "type": "bug", "title": "İstanbul Turkish dotted I" },
+    { "type": "bug", "title": "ınternal Turkish dotless i" },
+    { "type": "bug", "title": "Straße German eszett" },
+    { "type": "bug", "title": "tab\tand\nnewline whitespace" },
+    { "type": "bug", "title": "MixedCASE GitSync.Pull AND v3.4.5 plus abcdef1234567 hash" }
+  ]
+}

package/scripts/feedback-factory/fingerprint-parity.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * fingerprint-parity.mjs — LOCAL parity gate for the feedback fingerprint port.
+ *
+ * Runs the REAL reference Python (the-portal/.claude/scripts/feedback-processor.py
+ * compute_fingerprint) and the TS port over the shared corpus and asserts every
+ * fingerprint is byte-identical. This is the empirical equivalence gate the spec
+ * requires — it is intentionally NOT a CI test (CI doesn't have the reference
+ * checkout); it is run locally and its output recorded as evidence, and re-run
+ * whenever the port's regexes/normalization change.
+ *
+ * Reference path is configurable: PORTAL_PROCESSOR env var, else the default
+ * the-portal checkout. The TS port is imported from the built dist (run
+ * `npm run build` first).
+ *
+ * Exit 0 = 100% parity; exit 1 = at least one mismatch (printed).
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..', '..');
+
+const PROCESSOR = process.env.PORTAL_PROCESSOR
+  || '/Users/justin/Documents/Projects/the-portal/.claude/scripts/feedback-processor.py';
+const CORPUS = path.join(__dirname, 'fingerprint-corpus.json');
+const PY_REF = path.join(__dirname, '_py_fingerprint_ref.py');
+
+if (!fs.existsSync(PROCESSOR)) {
+  console.error(`[parity] reference processor not found: ${PROCESSOR}`);
+  console.error('[parity] set PORTAL_PROCESSOR to the reference feedback-processor.py');
+  process.exit(2);
+}
+
+// Reference fingerprints from the real Python.
+const py = spawnSync('python3', [PY_REF, PROCESSOR, CORPUS], { encoding: 'utf8' });
+if (py.status !== 0) {
+  console.error('[parity] python reference failed:\n', py.stderr || py.stdout);
+  process.exit(2);
+}
+const reference = JSON.parse(py.stdout);
+
+// TS port from the built dist.
+const distUrl = new URL('file://' + path.join(ROOT, 'dist', 'feedback-factory', 'processor', 'fingerprint.js'));
+const { computeFingerprint } = await import(distUrl.href);
+
+let mismatches = 0;
+for (const ref of reference) {
+  const got = computeFingerprint(ref.type, ref.title, ref.component);
+  const ok = got === ref.fp;
+  if (!ok) {
+    mismatches++;
+    console.error(`[MISMATCH] type=${JSON.stringify(ref.type)} title=${JSON.stringify(ref.title)} component=${JSON.stringify(ref.component)}`);
+    console.error(`           python=${ref.fp}`);
+    console.error(`           ts    =${got}`);
+  }
+}
+
+const total = reference.length;
+if (mismatches === 0) {
+  console.error(`[parity] ✓ ${total}/${total} fingerprints byte-identical to the reference Python.`);
+  process.exit(0);
+} else {
+  console.error(`[parity] ✗ ${mismatches}/${total} mismatches — the TS port diverges from the reference.`);
+  process.exit(1);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-27T03:42:33.009Z",
-  "instarVersion": "1.3.6",
+  "generatedAt": "2026-05-27T04:08:37.598Z",
+  "instarVersion": "1.3.7",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.7.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+First increment of the **Feedback Factory Migration** (Dawn → Echo; spec `docs/specs/feedback-factory-migration.md`, approved). Ports the dedup **fingerprinter** — scar (b), the single most correctness-critical piece of the "sorting brain" that decides whether two reports describe the same bug — from the reference Python (`the-portal/.claude/scripts/feedback-processor.py`) to TypeScript at `src/feedback-factory/processor/fingerprint.ts`.
+
+This is an internal building block: it is **not wired into any route, job, or runtime path yet**, so there is no behavioral change for any agent or user. It establishes the new `src/feedback-factory/` module and — importantly — the **parity-harness methodology** (`scripts/feedback-factory/fingerprint-parity.mjs`) that runs the real reference Python and asserts the TS port is byte-identical. Every subsequent scar port reuses this harness.
+
+## What to Tell Your User
+
+- This is groundwork, not a feature you'll notice yet — the first verified piece of moving the feedback system to where it's built.
+- The interesting part: I proved my rewrite produces exactly the same results as the original, character-for-character, including the tricky non-English-text cases — so nothing in the bug history can quietly drift as the move proceeds.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Feedback fingerprinter (TS port) | Internal module `src/feedback-factory/processor/fingerprint.ts` — not yet wired; foundation for the processor job |
+| Parity harness | `node scripts/feedback-factory/fingerprint-parity.mjs` (local; set `PORTAL_PROCESSOR` to the reference) |
+
+## Evidence
+
+The byte-exact port is the whole risk, so it was verified empirically, not by reasoning:
+
+- **Parity vs the real reference Python:** ran `compute_fingerprint` from `the-portal/.claude/scripts/feedback-processor.py` and the TS port over a 33-entry corpus (real titles + adversarial Unicode/encoding/whitespace cases). Result: **33/33 byte-identical**.
+- **The harness caught a real divergence before it could ship:** the first cut diverged on a bare arabic-indic digit, because Python's `\b\d+\b` is a *Unicode* word boundary while JavaScript's `\b` is ASCII-only — so the digit wasn't collapsed. Fixed by emulating the Unicode boundary with lookarounds; re-ran → 33/33. This is exactly the silent-history-fork hazard the spec's convergence flagged, caught at the foundation.
+- **CI regression anchors:** three golden fingerprint values captured from the reference are asserted in the unit test, so a future regex/encoding regression fails in CI even where the reference checkout isn't present.

package/upgrades/side-effects/feedback-factory-fingerprint.md

@@ -0,0 +1,36 @@
+# Side-Effects Review — feedback-factory fingerprint port (Phase 1, increment 1)
+
+**Slug:** `feedback-factory-fingerprint`
+**Date:** `2026-05-26`
+**Author:** Echo
+**Spec:** `docs/specs/feedback-factory-migration.md` (converged v2, approved by Justin 2026-05-26)
+**Scope:** Scar (b) only — the dedup fingerprinter. The first, foundational increment of the Phase-1 processor port. Other scars ((a) evidence gate, (c) false-merge/reopen/cycling, (d) lifecycle partitioning) and the processor-job wiring are subsequent increments.
+
+## Summary of the change
+
+Ports `compute_fingerprint` + its `extract_component` dependency (and the `SEVERITY_PREFIXES`/`SEVERITY_PHRASES` sets) from the reference `the-portal/.claude/scripts/feedback-processor.py` to TypeScript at `src/feedback-factory/processor/fingerprint.ts`. This is the single most correctness-critical port in the migration — it decides whether two reports are the SAME bug. Adds:
+- `src/feedback-factory/processor/fingerprint.ts` — the port (pure functions, no I/O).
+- `tests/unit/feedback-factory/fingerprint.test.ts` — Tier-1 behavioral + both-sides-of-boundary tests + golden-value CI anchors.
+- `scripts/feedback-factory/fingerprint-parity.mjs` + `_py_fingerprint_ref.py` + `fingerprint-corpus.json` — the LOCAL parity gate that runs the REAL reference Python and asserts byte-identical output.
+
+The module is **not wired into anything yet** — it is a standalone, importable building block. No route, no job, no behavior change for any agent or user.
+
+## The byte-exact-port hazard and how it's handled
+
+Per the spec, Python↔JS diverge on regex character classes, `\b`, `.lower()`, and encoding. The parity harness proved this empirically: a first cut diverged on a bare arabic-indic digit because Python's `\b\d+\b` is a Unicode word boundary while JS `\b` is ASCII-only. Fixed by emulating the Unicode boundary with lookarounds (`(?<![\p{L}\p{N}_])\p{Nd}+(?![\p{L}\p{N}_])`). After the fix: **33/33 corpus entries byte-identical to the reference Python**, including non-ASCII digits, em-dash, NBSP, Turkish İ/ı, German ß, hex hashes, and multi-version titles. Dawn's line-by-line review of the port remains a Phase-1 gate before any production cutover.
+
+## Seven-dimension review
+
+1. **Over/under-reach** — Pure functions, deterministic, no I/O, no global state. Not imported by any runtime path, so it cannot affect existing behavior. Risk is purely *equivalence to the reference*, addressed below.
+2. **Level-of-abstraction fit** — Lives at the processor-logic layer (`src/feedback-factory/processor/`), the correct home for the ported scar logic per the spec's open/operated architecture.
+3. **Signal vs Authority** — N/A; pure computation, no decision authority.
+4. **Interactions** — None. New isolated module; nothing imports it yet. The parity scripts shell out to an external reference path (configurable via `PORTAL_PROCESSOR`) and are LOCAL-only (not CI), so they add no CI dependency on the reference checkout.
+5. **Rollback cost** — Trivial: delete the module + tests + scripts. No data, no migration, no wiring to unwind.
+6. **Migration parity** — N/A. New internal library code shipped in the package; touches no agent-installed file (`.claude/settings.json` / config / CLAUDE.md template / hooks / skills).
+7. **Failure modes** — (a) Port diverges from the reference Python → caught by the parity harness (33/33 now) AND golden-value CI anchors in the unit test (so a future regex/encoding regression fails in CI even without the reference checkout). (b) Reference path absent → parity harness exits 2 with a clear message (it's a local gate, not CI). (c) An adversarial input not in the corpus diverges in production → mitigated by seeding the corpus with the known divergence classes; the corpus is extended as new classes are discovered, and Dawn's review is the human backstop.
+
+## Tests
+
+- Tier-1 unit (CI): `tests/unit/feedback-factory/fingerprint.test.ts` — `extractComponent` (dotted id, first-word fallback, [TAG] strip, whitelisted-vs-not severity prefix, empty); `computeFingerprint` (32-hex shape, version/int/hash collapse, internal-whitespace collapse, leading-whitespace component divergence, case-insensitivity, type+component incorporation, 3 golden anchors). 14 tests.
+- Parity (local gate, evidence): `scripts/feedback-factory/fingerprint-parity.mjs` → **33/33 byte-identical** to the reference Python.
+- No integration/E2E tier this increment: the module is not yet wired to a route or job; those tiers attach when the processor job + receiver land (subsequent increments). Documented here so the omission is a reasoned decision, not an oversight.