instar 1.3.8 → 1.3.9

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

@@ -0,0 +1,24 @@
+/**
+ * similarity.ts — TS port of the feedback-factory title-similarity primitives.
+ *
+ * Part of scar (c) of docs/specs/feedback-factory-migration.md. Byte-exact port
+ * of `_tokenize` (:1389) and `_jaccard_similarity` (:1394) from the reference
+ * `the-portal/.claude/scripts/feedback-processor.py`. These are the FUZZY match
+ * layer that sits on top of the exact-match fingerprint (fingerprint.ts): two
+ * reports whose titles overlap enough (Jaccard ≥ threshold) are candidates for
+ * the same cluster. The threshold-application logic (0.35 vs the 0.55 fixed-
+ * cluster false-merge guard) lives in the clustering driver and is a later
+ * increment; this module is the pure, parity-testable similarity primitive.
+ *
+ * Divergence surface (per spec / convergence): the TOKENIZER. Python
+ * `re.findall(r'[a-z0-9]+', text.lower())` is ASCII-only — non-ASCII letters and
+ * Unicode digits are token separators, NOT token content. JS `/[a-z0-9]+/g`
+ * (no `u`, no `i`) matches the identical ASCII class, so the only residual risk
+ * is `.lower()` vs `.toLowerCase()` on characters that then survive the ASCII
+ * filter. The parity harness verifies equivalence over the adversarial corpus.
+ */
+/** Port of Python `_tokenize` (:1391): ASCII word tokens of the lowercased text, deduped. */
+export declare function tokenize(text: string): Set<string>;
+/** Port of Python `_jaccard_similarity` (:1394): |A∩B| / |A∪B|, 0 when either side is empty. */
+export declare function jaccardSimilarity(text1: string, text2: string): number;
+//# sourceMappingURL=similarity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/processor/similarity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,6FAA6F;AAC7F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAMlD;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYtE"}

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

@@ -0,0 +1,44 @@
+/**
+ * similarity.ts — TS port of the feedback-factory title-similarity primitives.
+ *
+ * Part of scar (c) of docs/specs/feedback-factory-migration.md. Byte-exact port
+ * of `_tokenize` (:1389) and `_jaccard_similarity` (:1394) from the reference
+ * `the-portal/.claude/scripts/feedback-processor.py`. These are the FUZZY match
+ * layer that sits on top of the exact-match fingerprint (fingerprint.ts): two
+ * reports whose titles overlap enough (Jaccard ≥ threshold) are candidates for
+ * the same cluster. The threshold-application logic (0.35 vs the 0.55 fixed-
+ * cluster false-merge guard) lives in the clustering driver and is a later
+ * increment; this module is the pure, parity-testable similarity primitive.
+ *
+ * Divergence surface (per spec / convergence): the TOKENIZER. Python
+ * `re.findall(r'[a-z0-9]+', text.lower())` is ASCII-only — non-ASCII letters and
+ * Unicode digits are token separators, NOT token content. JS `/[a-z0-9]+/g`
+ * (no `u`, no `i`) matches the identical ASCII class, so the only residual risk
+ * is `.lower()` vs `.toLowerCase()` on characters that then survive the ASCII
+ * filter. The parity harness verifies equivalence over the adversarial corpus.
+ */
+/** Port of Python `_tokenize` (:1391): ASCII word tokens of the lowercased text, deduped. */
+export function tokenize(text) {
+    // Python: set(re.findall(r'[a-z0-9]+', text.lower())). re.findall returns
+    // non-overlapping matches; String.match(//g) is the JS equivalent (null when
+    // none → treat as empty). The class is ASCII (no `u` flag), matching Python.
+    const matches = text.toLowerCase().match(/[a-z0-9]+/g);
+    return new Set(matches ?? []);
+}
+/** Port of Python `_jaccard_similarity` (:1394): |A∩B| / |A∪B|, 0 when either side is empty. */
+export function jaccardSimilarity(text1, text2) {
+    const t1 = tokenize(text1);
+    const t2 = tokenize(text2);
+    if (t1.size === 0 || t2.size === 0)
+        return 0.0;
+    let intersection = 0;
+    for (const tok of t1) {
+        if (t2.has(tok))
+            intersection++;
+    }
+    // |A∪B| = |A| + |B| − |A∩B|. Integer division as float — IEEE-754 doubles in
+    // both Python and JS, so boundary comparisons (≥0.35, ≥0.55) agree.
+    const union = t1.size + t2.size - intersection;
+    return intersection / union;
+}
+//# sourceMappingURL=similarity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.js","sourceRoot":"","sources":["../../../src/feedback-factory/processor/similarity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,6FAA6F;AAC7F,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACvD,OAAO,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,KAAa;IAC5D,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAC/C,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,GAAG,IAAI,EAAE,EAAE,CAAC;QACrB,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,YAAY,EAAE,CAAC;IAClC,CAAC;IACD,6EAA6E;IAC7E,oEAAoE;IACpE,MAAM,KAAK,GAAG,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,IAAI,GAAG,YAAY,CAAC;IAC/C,OAAO,YAAY,GAAG,KAAK,CAAC;AAC9B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.8",
+  "version": "1.3.9",
   "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_similarity_ref.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Parity reference: Jaccard title similarity from the REAL feedback-processor.py.
+
+Imports the reference processor without running its CLI main (same approach as
+_py_fingerprint_ref.py) and calls its actual `_jaccard_similarity` over a corpus
+of title PAIRS. Emits JSON {a, b, sim} so the Node harness can diff the TS port.
+
+Usage: python3 _py_similarity_ref.py <processor_path> <pairs_corpus_path>
+"""
+import sys
+import json
+import importlib.util
+
+
+def load_processor(path):
+    spec = importlib.util.spec_from_file_location("_feedback_processor_ref_sim", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def main():
+    if len(sys.argv) != 3:
+        print("usage: _py_similarity_ref.py <processor_path> <pairs_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 pair in corpus["pairs"]:
+        a, b = pair["a"], pair["b"]
+        sim = proc._jaccard_similarity(a, b)
+        out.append({"a": a, "b": b, "sim": repr(sim)})  # repr() = full-precision float string
+    sys.stdout.write(json.dumps(out, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,25 @@
+{
+  "_comment": "Parity corpus of title PAIRS for the Jaccard similarity port. Covers identical / disjoint / partial-overlap / boundary (≈0.35, ≈0.55) / empty / punctuation-only / non-ASCII-dropped cases. Both Python json.load and Node JSON.parse decode identical bytes, so the input is shared.",
+  "pairs": [
+    { "a": "GitSync.pull fails intermittently", "b": "GitSync.pull fails intermittently" },
+    { "a": "auth token refresh broken", "b": "completely unrelated database migration" },
+    { "a": "session reaper kills active session", "b": "session reaper kills idle session" },
+    { "a": "the quick brown fox", "b": "the quick red fox" },
+    { "a": "alpha beta gamma delta", "b": "alpha beta epsilon zeta" },
+    { "a": "one two three four five", "b": "one two three six seven" },
+    { "a": "a b c d e f g", "b": "a b c d h i j" },
+    { "a": "tunnel retry exhaustion notify", "b": "tunnel retry backoff" },
+    { "a": "", "b": "non empty title" },
+    { "a": "non empty title", "b": "" },
+    { "a": "", "b": "" },
+    { "a": "!!! ??? ...", "b": "more punctuation: ;;; ///" },
+    { "a": "café résumé naïve", "b": "cafe resume naive" },
+    { "a": "İstanbul ören", "b": "istanbul oren" },
+    { "a": "Straße über", "b": "strasse uber" },
+    { "a": "arabic ٣٤٥ digits", "b": "arabic digits" },
+    { "a": "MixedCASE Tokens HERE", "b": "mixedcase tokens here" },
+    { "a": "duplicate duplicate duplicate word", "b": "duplicate word" },
+    { "a": "v1.2.3 release notes", "b": "v9.9.9 release notes" },
+    { "a": "GitSync.pull deadlock under load", "b": "GitSync push deadlock under heavy load now" }
+  ]
+}

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * similarity-parity.mjs — LOCAL parity gate for the Jaccard title-similarity port.
+ *
+ * Runs the REAL reference Python (`_jaccard_similarity` from
+ * the-portal/.claude/scripts/feedback-processor.py) and the TS port over the
+ * shared pairs corpus and asserts the similarity values match. Like the
+ * fingerprint harness this is a LOCAL evidence gate, not a CI test (CI lacks the
+ * reference checkout). Values should be bit-identical (same IEEE-754 division);
+ * we allow a 1e-12 tolerance only to absorb float-string serialization, and we
+ * ALSO assert the threshold decisions (≥0.35, ≥0.55) agree exactly — those are
+ * what actually drive clustering.
+ *
+ * Reference path: PORTAL_PROCESSOR env, else the default the-portal checkout.
+ * TS port is imported from the built dist (`npm run build` first).
+ *
+ * Exit 0 = parity; exit 1 = mismatch.
+ */
+
+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, 'similarity-corpus.json');
+const PY_REF = path.join(__dirname, '_py_similarity_ref.py');
+const EPS = 1e-12;
+
+if (!fs.existsSync(PROCESSOR)) {
+  console.error(`[sim-parity] reference processor not found: ${PROCESSOR}`);
+  console.error('[sim-parity] set PORTAL_PROCESSOR to the reference feedback-processor.py');
+  process.exit(2);
+}
+
+const py = spawnSync('python3', [PY_REF, PROCESSOR, CORPUS], { encoding: 'utf8' });
+if (py.status !== 0) {
+  console.error('[sim-parity] python reference failed:\n', py.stderr || py.stdout);
+  process.exit(2);
+}
+const reference = JSON.parse(py.stdout);
+
+const distUrl = new URL('file://' + path.join(ROOT, 'dist', 'feedback-factory', 'processor', 'similarity.js'));
+const { jaccardSimilarity } = await import(distUrl.href);
+
+const decide = (v) => (v >= 0.55 ? 'fixed-merge' : v >= 0.35 ? 'merge' : 'no-merge');
+
+let mismatches = 0;
+for (const ref of reference) {
+  const pySim = Number(ref.sim);
+  const tsSim = jaccardSimilarity(ref.a, ref.b);
+  const valueOk = Math.abs(tsSim - pySim) < EPS;
+  const decisionOk = decide(tsSim) === decide(pySim);
+  if (!valueOk || !decisionOk) {
+    mismatches++;
+    console.error(`[MISMATCH] a=${JSON.stringify(ref.a)} b=${JSON.stringify(ref.b)}`);
+    console.error(`           python=${pySim} (${decide(pySim)})  ts=${tsSim} (${decide(tsSim)})`);
+  }
+}
+
+const total = reference.length;
+if (mismatches === 0) {
+  console.error(`[sim-parity] ✓ ${total}/${total} similarity values + threshold decisions match the reference Python.`);
+  process.exit(0);
+} else {
+  console.error(`[sim-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-27T04:23:30.515Z",
-  "instarVersion": "1.3.8",
+  "generatedAt": "2026-05-27T04:57:52.877Z",
+  "instarVersion": "1.3.9",
   "entryCount": 192,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.9.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Second increment of the **Feedback Factory Migration** (Dawn → Echo; spec `docs/specs/feedback-factory-migration.md`, approved). Ports the **fuzzy title-similarity primitives** — `_tokenize` + `_jaccard_similarity` — from the reference Python (`the-portal/.claude/scripts/feedback-processor.py`) to TypeScript at `src/feedback-factory/processor/similarity.ts`.
+
+These sit on top of the exact-match fingerprinter shipped in the previous increment: the fingerprint groups identically-normalized reports, and Jaccard similarity is the fuzzy layer that decides whether two *differently-worded* titles overlap enough to be the same bug (the input to the clustering merge thresholds). Still an internal building block — **not wired into any route or job yet**, so no behavioral change.
+
+## What to Tell Your User
+
+- More groundwork for moving the feedback system in-house — the piece that recognizes two differently-worded reports as the same underlying issue.
+- Same discipline as before: I proved my rewrite produces the same similarity scores AND the same group/don't-group decisions as Dawn's original, across 20 title pairs including the tricky non-English-text ones.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Title-similarity primitives (TS port) | Internal module `src/feedback-factory/processor/similarity.ts` — not yet wired |
+| Similarity parity harness | `node scripts/feedback-factory/similarity-parity.mjs` (local; set `PORTAL_PROCESSOR`) |
+
+## Evidence
+
+- **Parity vs the real reference Python:** ran `_jaccard_similarity` from the reference processor and the TS port over 20 title pairs (identical / disjoint / partial-overlap / near the 0.35 and 0.55 merge thresholds / empty / punctuation-only / non-ASCII). Result: **20/20 match** — both the raw similarity value and the merge-threshold decision (the math is bit-identical IEEE-754 division; the harness asserts the *decision* too, since that is what actually drives clustering).
+- **ASCII-tokenizer fidelity:** the reference tokenizer is ASCII-only (`[a-z0-9]+` after lowercasing), so the port uses the identical ASCII class — non-English letters and non-ASCII digits are separators in both, verified by the corpus.
+- **CI anchors:** unit tests assert exact ratios (0.6, 0.4) and the threshold ordering, so a tokenizer/division regression fails in CI even without the reference checkout.

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

@@ -0,0 +1,32 @@
+# Side-Effects Review — feedback-factory similarity primitives (Phase 1, increment 2)
+
+**Slug:** `feedback-factory-similarity`
+**Date:** `2026-05-26`
+**Author:** Echo
+**Spec:** `docs/specs/feedback-factory-migration.md` (converged v2, approved by Justin 2026-05-26)
+**Scope:** The fuzzy title-similarity primitives — `_tokenize` (:1389) and `_jaccard_similarity` (:1394) of the reference processor — which sit on top of the exact-match fingerprint (increment 1) and underpin scar (c)'s false-merge guard. The threshold-application/clustering driver and the other scars are subsequent increments.
+
+## Summary of the change
+
+Ports `_tokenize` + `_jaccard_similarity` from `the-portal/.claude/scripts/feedback-processor.py` to `src/feedback-factory/processor/similarity.ts`. Pure functions, no I/O. **Not wired into any route/job yet** — no behavioral change. Adds the similarity parity harness (`scripts/feedback-factory/similarity-parity.mjs` + `_py_similarity_ref.py` + `similarity-corpus.json`) and Tier-1 unit tests.
+
+## Equivalence verification
+
+- **20/20 title pairs match the reference Python** — both the raw similarity value (1e-12 tolerance for float-string serialization only; the math is bit-identical IEEE-754 division) AND the threshold decisions (`≥0.55` fixed-merge, `≥0.35` merge, else no-merge), which are what actually drive clustering.
+- The tokenizer is ASCII-only in the reference (`re.findall(r'[a-z0-9]+', text.lower())`), so the JS port uses the identical ASCII class `/[a-z0-9]+/g` (no `u`, no `i`). Non-ASCII letters and Unicode digits are separators in both — verified by corpus entries (café→{caf}, arabic digits dropped, Straße→{stra,e}).
+
+## Seven-dimension review
+
+1. **Over/under-reach** — Pure deterministic functions, no I/O, no global state, not imported by any runtime path. Cannot affect existing behavior. Risk is equivalence-to-reference, addressed above.
+2. **Level-of-abstraction fit** — Processor-logic layer (`src/feedback-factory/processor/`), alongside the fingerprint port. Correct home.
+3. **Signal vs Authority** — N/A; pure computation. The threshold constants that turn a similarity score into a merge decision live in the (later) clustering driver, where the curated-lifecycle authority also lives.
+4. **Interactions** — None. New isolated module; nothing imports it yet. Parity scripts are LOCAL-only (external reference path via `PORTAL_PROCESSOR`), no CI dependency on the reference checkout.
+5. **Rollback cost** — Trivial: delete the module + tests + scripts. No data, no migration, no wiring.
+6. **Migration parity** — N/A. New internal library code; touches no agent-installed file.
+7. **Failure modes** — (a) Port diverges from reference → caught by the parity harness (20/20) + golden-shaped unit assertions in CI. (b) Float boundary divergence at exactly 0.35/0.55 → mitigated by identical IEEE-754 division + the parity harness asserting threshold DECISIONS, not just values. (c) Reference path absent → harness exits 2 with a clear message (local gate, not CI).
+
+## Tests
+
+- Tier-1 unit (CI): `tests/unit/feedback-factory/similarity.test.ts` — `tokenize` (lowercase/split/dedup, ASCII-only behavior, empty/punctuation), `jaccardSimilarity` (identical=1.0, disjoint=0.0, empty-guard=0.0, exact ∩/∪ ratios, threshold ordering). 8 tests.
+- Parity (local gate, evidence): `scripts/feedback-factory/similarity-parity.mjs` → **20/20** values + threshold decisions identical to the reference Python.
+- No integration/E2E this increment: not yet wired to a route/job; those tiers attach when the clustering driver + receiver land. Reasoned decision, documented.