ruvnet-brain 4.0.1 → 4.0.4

package/scripts/corpus-qa.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// corpus-qa.mjs — permanent machine gate: "everything embeds correctly and everything gets read
+// correctly." Born from the 2026-07-10 depth-restore failure, where a rebuilt ruvector store had
+// 18,491 passages and 0 full bodies and nothing noticed until a human grepped for '(full body):'.
+//
+// For EVERY .rvf store in the kb dir. Canonical repository stores are .big bge-768; legacy
+// MiniLM-384 stores remain discoverable during migration, and big-only stores may share the
+// canonical unsuffixed passages sidecar to avoid storing the same source text twice.
+//
+//   STRUCTURAL (cheap, always):
+//     S1  <name>.passages.jsonl exists and has > 0 rows
+//     S2  full-body passage count > 0 whenever scripts/full-hints.mjs FULL_HINTS names the store
+//         (the exact failure class this gate exists to kill — hints defined, bodies zeroed = FAIL)
+//     S3  .rvf totalVectors === passages rows (no missing/extra rows), via RvfDatabase.openReadonly
+//     S4  <name>.rvf.embed.json exists (a store the read path can't embed queries for is unreadable)
+//
+//   ROUND-TRIP (heavy, skipped with --structural):
+//     R1  sample 3 passages DETERMINISTICALLY (FNV-1a of "store.variant:k" — reproducible, no RNG),
+//         re-embed each passage exactly as the pipeline indexed it (small: "title — path\ntext",
+//         mean pooling; big: raw text, cls pooling — read from the store's own embed.json),
+//         query THAT store, and require the sampled row itself (same id, same path, or identical
+//         text — overlapping chunks of one doc may legitimately outrank each other) in top-3,
+//         OR within NEAR_DUP_EPS cosine distance of the best hit inside top-10. The epsilon arm
+//         exists because near-duplicate corpus rows (e.g. FACT's timestamped benchmark_report
+//         JSONs, ~95% identical text) crowd the podium while quantized batch-vs-single embed
+//         drift (~0.035 measured) exceeds the true gap between near-dups — the row IS stored and
+//         readable (fact.big id=722: rank 6, Δ0.007 behind rank 1), so that's a photo-finish,
+//         not a broken store. Photo-finish passes are still surfaced as a `note` so the
+//         near-dup-noise signal feeds the dedup backlog instead of being hidden. A row absent
+//         from top-10 (or far from the leader) remains a hard FAIL — missing/zero vectors and
+//         broken read paths cannot hide behind the epsilon.
+//         Proves embed-write AND read-path in one check. Retrieval QUALITY (real questions) stays
+//         forge-guard/prove's job; this gate proves the machinery, not the answers.
+//
+// Usage:
+//   node scripts/corpus-qa.mjs                     # whole corpus, structural + round-trip, serial
+//   node scripts/corpus-qa.mjs --store ruvector    # one store (both variants)
+//   node scripts/corpus-qa.mjs --structural        # cheap checks only
+//   [--dir <kb-dir>] [--samples N]                 # fixture/test hooks
+//
+// Output: one table row per store-variant, PASS/FAIL + reasons; skipped store classes are printed
+// with why (nothing is skipped silently). Exit 1 if ANY row fails — self-update.mjs runs this per
+// rebuilt store and aborts before publish on failure.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { FULL_HINTS } from './full-hints.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KB = path.join(ROOT, 'kb');
+
+// resolve-deps lives in the real kb/ regardless of --dir (fixtures point --dir elsewhere).
+const { loadRvf, loadTransformers, configureModel, chooseModelCache, closeReadonlyRvf } =
+  await import(path.join(KB, 'resolve-deps.mjs')).then((m) => m);
+const { materializeModelRevision } =
+  await import(path.join(KB, 'model-requirements.mjs')).then((m) => m);
+
+const FULL_BODY_MARK = '(full body):';
+// R1 photo-finish epsilon: measured quantized batch-vs-single embed drift is ~0.035 cosine
+// distance (fact.big id=722 replay); near-dup siblings sit within ~0.005 of each other. 0.02
+// forgives the drift-scale tie WITHOUT forgiving genuinely different rows.
+const NEAR_DUP_EPS = 0.02;
+
+function fnv1a(s) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+  return h >>> 0;
+}
+
+function readPassages(file) {
+  return new Promise((resolve, reject) => {
+    const rows = [];
+    const rl = readline.createInterface({ input: fs.createReadStream(file), crlfDelay: Infinity });
+    rl.on('line', (l) => { const s = l.trim(); if (!s) return; try { rows.push(JSON.parse(s)); } catch { /* counted structurally via row parse below */ } });
+    rl.on('close', () => resolve(rows));
+    rl.on('error', reject);
+  });
+}
+
+// Deterministic k distinct sample indices for a store-variant. Same store => same samples, always.
+export function sampleIndices(storeKey, n, k) {
+  const idx = new Set();
+  for (let salt = 0; idx.size < Math.min(k, n) && salt < 50 * k; salt++) idx.add(fnv1a(`${storeKey}:${salt}`) % n);
+  return [...idx].slice(0, Math.min(k, n));
+}
+
+// ---- embedder cache: one pipeline per model, shared across stores. Caches the in-flight PROMISE
+// (not just the resolved pipe) so concurrent qaStore() calls that both miss on the same model don't
+// each trigger their own T.pipeline() load — first caller wins, the rest await its promise.
+const pipelines = new Map();
+function getPipeline(embedConf) {
+  const { model, revision } = embedConf;
+  const key = `${model}@${revision || 'unversioned'}`;
+  if (pipelines.has(key)) return pipelines.get(key);
+  const p = (async () => {
+    const { T } = await loadTransformers();
+    const cache = chooseModelCache();
+    materializeModelRevision(cache, model, revision);
+    configureModel(T, cache);
+    return T.pipeline('feature-extraction', model, {
+      quantized: true,
+      ...(revision ? { revision } : {}),
+    });
+  })();
+  pipelines.set(key, p);
+  return p;
+}
+
+/**
+ * QA one store-variant. Returns { store, variant, passages, fullBodies, vectors, roundtrip, fails, notes }.
+ * `fails` is [] on PASS; every entry is a specific reason string (receipts, not adjectives).
+ * `notes` are non-fatal signals (e.g. near-dup crowding) that should reach the dedup backlog.
+ */
+export async function qaStore(dir, store, variant, { roundtrip = true, samples = 3 } = {}) {
+  const base = variant === 'big' ? `${store}.big` : store;
+  const rvfPath = path.join(dir, `${base}.rvf`);
+  const variantPassages = path.join(dir, `${base}.passages.jsonl`);
+  const canonicalPassages = path.join(dir, `${store}.passages.jsonl`);
+  const passagesPath = variant === 'big' && !fs.existsSync(variantPassages)
+    ? canonicalPassages
+    : variantPassages;
+  const embedPath = `${rvfPath}.embed.json`;
+  const res = { store, variant, passages: 0, fullBodies: 0, vectors: null, roundtrip: 'skipped', fails: [], notes: [] };
+
+  // S1: passages sidecar
+  if (!fs.existsSync(passagesPath)) { res.fails.push(`S1 missing ${path.basename(passagesPath)}`); return res; }
+  const rows = await readPassages(passagesPath);
+  res.passages = rows.length;
+  if (rows.length === 0) { res.fails.push('S1 passages file has 0 rows'); return res; }
+
+  // S2: full-body floor wherever hints exist (the 2026-07-10 failure class)
+  res.fullBodies = rows.filter((r) => typeof r.text === 'string' && r.text.includes(FULL_BODY_MARK)).length;
+  if (FULL_HINTS[store] && res.fullBodies === 0) {
+    res.fails.push(`S2 FULL_HINTS defines --full for "${store}" but store has 0 full-body passages (silent depth loss)`);
+  }
+
+  // S3: vector count parity
+  let db = null;
+  try {
+    const { mod } = loadRvf();
+    db = await mod.RvfDatabase.openReadonly(rvfPath);
+    const st = await db.status();
+    res.vectors = st.totalVectors;
+    if (st.totalVectors !== rows.length) res.fails.push(`S3 vectors=${st.totalVectors} != passages=${rows.length}`);
+  } catch (e) {
+    res.fails.push(`S3 cannot open ${path.basename(rvfPath)}: ${e.message.split('\n')[0]}`);
+  }
+
+  // S4: query-side embed config
+  let embedConf = null;
+  if (!fs.existsSync(embedPath)) res.fails.push(`S4 missing ${path.basename(embedPath)} (read path cannot embed queries)`);
+  else embedConf = JSON.parse(fs.readFileSync(embedPath, 'utf8'));
+
+  // R1: deterministic self-retrieval round trip
+  if (roundtrip && db && embedConf && !res.fails.some((f) => f.startsWith('S3'))) {
+    try {
+      const picks = sampleIndices(`${store}.${variant}`, rows.length, samples);
+      const byId = new Map(rows.map((r) => [String(r.id), r]));
+      let hit = 0;
+      const misses = [];
+      const pipe = await getPipeline(embedConf);
+      for (const i of picks) {
+        const r = rows[i];
+        // Re-embed EXACTLY what the pipeline indexed for this variant (forge-build/forge-big):
+        const text = variant === 'big'
+          ? r.text
+          : `${r.title} — ${r.path}\n${r.text}`.slice(0, 4300);
+        const out = await pipe([text], { pooling: embedConf.pooling || 'mean', normalize: true });
+        if (out.dims[1] !== embedConf.dimensions) throw new Error(`embed dim ${out.dims[1]} != ${embedConf.dimensions}`);
+        const top = await db.query(Array.from(out.data), 10);
+        const matches = (t) => String(t.id) === String(r.id)
+          || byId.get(String(t.id))?.path === r.path
+          || byId.get(String(t.id))?.text === r.text;
+        const rank = top.findIndex(matches); // -1 = absent from top-10
+        if (rank >= 0 && rank < 3) hit++;
+        else if (rank >= 0 && top[rank].distance - top[0].distance <= NEAR_DUP_EPS) {
+          hit++; // photo-finish behind near-duplicates: stored + readable; surface the crowd as a note
+          res.notes.push(`near-dup crowd: id=${r.id} rank ${rank + 1}, Δ${(top[rank].distance - top[0].distance).toFixed(4)} behind #1 (${r.path})`);
+        } else {
+          misses.push(`id=${r.id} ${rank < 0 ? 'ABSENT from top-10' : `rank ${rank + 1}, Δ${(top[rank].distance - top[0].distance).toFixed(4)}`} ${r.path}`);
+        }
+      }
+      res.roundtrip = `${hit}/${picks.length}`;
+      if (hit < picks.length) res.fails.push(`R1 self-retrieval missed: ${misses.join('; ')}`);
+    } catch (e) {
+      res.roundtrip = 'error';
+      res.fails.push(`R1 round-trip error: ${e.message.split('\n')[0]}`);
+    }
+  }
+  await closeReadonlyRvf(db);
+  return res;
+}
+
+/** Discover store-variants in a dir. Returns { stores: [{store, variant}], skipped: [{file, why}] }. */
+export function discoverStores(dir) {
+  const stores = [];
+  const skipped = [];
+  for (const f of fs.readdirSync(dir).sort()) {
+    if (!f.endsWith('.rvf')) continue;               // idmaps/embed.json/etc. are per-store sidecars, not stores
+    const name = f.slice(0, -'.rvf'.length);
+    if (name.endsWith('.big')) stores.push({ store: name.slice(0, -'.big'.length), variant: 'big' });
+    else stores.push({ store: name, variant: 'small' });
+  }
+  return { stores, skipped };
+}
+
+// ---------------- CLI ----------------
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const arg = (f, d) => { const i = process.argv.indexOf(f); return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : d; };
+  const has = (f) => process.argv.includes(f);
+  const DIR = path.resolve(arg('--dir', KB));
+  const ONLY = arg('--store', null);
+  const STRUCTURAL_ONLY = has('--structural');
+  const SAMPLES = parseInt(arg('--samples', '3'), 10) || 3;
+  const CONC = Math.max(1, parseInt(arg('--concurrency', '4'), 10) || 4);
+
+  const { stores } = discoverStores(DIR);
+  const todo = ONLY ? stores.filter((s) => s.store === ONLY) : stores;
+  if (ONLY && todo.length === 0) { console.error(`[corpus-qa] no store named "${ONLY}" in ${DIR}`); process.exit(2); }
+  console.log(`[corpus-qa] ${todo.length} store-variant(s) in ${DIR}${ONLY ? ` (store=${ONLY})` : ''}${STRUCTURAL_ONLY ? ' [structural only]' : ' [structural + round-trip]'} — concurrency ${CONC}, one process`);
+
+  // qaStore() shares the in-process pipelines cache (getPipeline above) and each store-variant
+  // touches its own .rvf/.passages.jsonl files, so concurrent runs don't step on each other.
+  const results = new Array(todo.length);
+  let cursor = 0;
+  const runOne = async () => {
+    while (true) {
+      const i = cursor++;
+      if (i >= todo.length) return;
+      const { store, variant } = todo[i];
+      results[i] = await qaStore(DIR, store, variant, { roundtrip: !STRUCTURAL_ONLY, samples: SAMPLES });
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(CONC, todo.length) }, runOne));
+
+  const pad = (s, n) => String(s).padEnd(n);
+  console.log('\n' + pad('store', 26) + pad('variant', 8) + pad('passages', 10) + pad('full-b', 8) + pad('vectors', 9) + pad('roundtrip', 11) + 'verdict');
+  let failed = 0;
+  for (const r of results) {
+    const verdict = r.fails.length ? 'FAIL' : 'PASS';
+    if (r.fails.length) failed++;
+    console.log(pad(r.store, 26) + pad(r.variant, 8) + pad(r.passages, 10) + pad(r.fullBodies, 8) + pad(r.vectors ?? '?', 9) + pad(r.roundtrip, 11) + verdict);
+    for (const f of r.fails) console.log('    ↳ ' + f);
+    for (const n of r.notes) console.log('    · note: ' + n);
+  }
+  console.log(`\n[corpus-qa] ${results.length - failed}/${results.length} store-variants PASS${failed ? ` — ${failed} FAILED` : ''}`);
+  process.exit(failed ? 1 : 0);
+}

package/scripts/correction-detect-embed.mjs

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+// correction-detect-embed.mjs — an HONEST measurement of whether a DIFFERENT PRIMITIVE (a local
+// embedding k-NN classifier) clears ADR-033 §2's floor (≥90% precision on ≥100 detections) where
+// the lexical regex detector (scripts/correction-detect.mjs) did not.
+//
+// This is a MEASUREMENT SCRIPT, not a shipped feature. It does not wire into any hook, gate, or
+// store. It answers one question for an owner decision: does swapping the primitive from regex to
+// embedding similarity change the verdict on THIS corpus? See the accompanying report for the
+// answer; this file is how the numbers in that report were produced, reproducibly.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// THE PRIMITIVE: k-NEAREST-NEIGHBOUR OVER LOCAL MiniLM EMBEDDINGS — NOT A TRAINED CLASSIFIER
+//
+// Grounded against how this repo already does embeddings (kb/forge-build.mjs, kb/resolve-deps.mjs):
+// the SAME model (`Xenova/all-MiniLM-L6-v2`, 384-dim, mean-pooled, L2-normalized, pinned to the
+// same HuggingFace revision the KB build uses) via the SAME local ONNX runtime
+// (`@xenova/transformers`, resolved through `kb/resolve-deps.mjs`'s `loadTransformers()` /
+// `configureModel()` — no network call when the model is already cached, per CLAUDE.md Rule 1: RVF/
+// local-ONNX first, never an external embedding API). This script imports that resolver directly
+// rather than re-implementing model loading, cache resolution, or the network-hang guard a second
+// time — those are already solved once, correctly, in `kb/resolve-deps.mjs`.
+//
+// The classifier itself is deliberately the simplest thing that could work (Karpathy: minimum code,
+// no speculative abstraction): embed each candidate as `PRECEDING ACTION: <summary> \n USER:
+// <utterance>` (utterance ± the preceding-action context the task asked for), embed a small labelled
+// reference set drawn ONLY from the TUNE split, and classify a holdout candidate by a similarity-
+// weighted vote of its k nearest TUNE neighbours. k and the similarity floor are chosen by
+// leave-one-out cross-validation ON THE TUNE SET ONLY, then frozen before touching holdout — the
+// same no-leakage discipline `correction-detect-measure.mjs` uses for its file-level split.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// WHERE THE GROUND TRUTH COMES FROM
+//
+// `scripts/correction-detect-measure.mjs --dump-pool` already builds a candidate pool (Signal-1:
+// adjacent to a preceding assistant action) and this task's own grounding pass narrowed it with the
+// SAME loose superset lexical net that script's `broad-pool.mjs` companion applies (deliberately
+// looser than the regex's own signals — a safety margin so a genuine correction is not excluded from
+// the labelling pool just because it doesn't use the regex's exact vocabulary). That pool — 271
+// candidates, 112 tune / 159 holdout, spanning ALL 1,328 transcripts — was hand-labelled by this
+// task's author (true / borderline / false) against ADR-033's actual four-signal definition, NOT
+// against what either detector happens to fire on. That hand-labelling is the same self-graded
+// caveat every number in `correction-detect.mjs`'s own header already carries (Verification #6 in
+// ADR-033: "not independently graded") — repeated here rather than hidden.
+//
+// The labelled pool contains real (if redacted-of-secrets) transcript text and is NOT committed to
+// this repo, for the same reason `correction-detect-measure.mjs` never writes transcript text into
+// the repo. Point `--labels` / `--tune-pool` / `--holdout-pool` at that data (default: this
+// project's scratchpad locations used to build it) to reproduce the run. A small, hand-picked,
+// already-public-in-spirit subset (utterances that already became named standing orders in this
+// project's own committed memory index) ships as `tests/fixtures/correction-embed-sample.jsonl` so
+// `tests/unit/correction-detect-embed.test.mjs` can run the classifier's MECHANICS without any
+// private corpus present.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// MEASURED, 2026-07-23 — same 271-item hand-labelled pool (112 tune / 159 holdout, all 1,328
+// transcripts) the total-genuine-correction count in the report was taken from. Reproduce with the
+// `measure` command below, pointed at that pool + labels.json (see this file's own USAGE).
+//
+//   tune-set ground truth:     14 true  /  98 false   (of 112)
+//   holdout ground truth:      23 true  /   6 borderline  /  130 false   (of 159)
+//
+//   Leave-one-out search on TUNE ONLY (no holdout leakage) picked k=1, minSim=0.6 (tune-LOO
+//   precision 66.7% / recall 42.9% — already far below the regex's tune-side 100%/4-of-4).
+//
+//   Applied to the SAME 159-item holdout the regex's own 4 detections came from:
+//       flagged positive:        8
+//       true positives:          2
+//       false positives:         6        (0 of the 6 borderline-labelled rows were flagged)
+//       PRECISION:               25.0%   (2/8)
+//       RECALL (of 29 true+borderline):   6.9%
+//
+//   With the frozen default operating point below (k=5, minSim=0.3, chosen the same way but on an
+//   earlier tune-only search) instead of a fresh --tune-k run: 7 flagged, 2 true positives, 5 false
+//   — precision 28.6%, recall 6.9%. Same order of magnitude either way: roughly a QUARTER of what
+//   this primitive flags on the real holdout is a genuine correction, versus the regex's own
+//   50-100% (n=4) on the same pool.
+//
+//   Extended to the FULL Signal-1 holdout population (784 candidates, `--wide-pool`, not just the
+//   159-item loose-net subset a human would ever be asked to label): 12 flagged, of which 5 fall
+//   OUTSIDE the labelled subset. Hand-reviewed those 5 for this measurement: all 5 are false
+//   (a repo-naming brainstorm, two raw image-paste captions, a status question, and a delegation
+//   statement) — so at realistic operational scale, precision is 2/12 ≈ 16.7%, recall unchanged.
+//
+//   CONCLUSION: this primitive does NOT beat the regex on precision on this corpus, and comes
+//   nowhere near ADR-033 §2's ≥90% floor at any N tried. See the report this task produced for the
+//   full discussion (why: MiniLM sentence embeddings here separate by TOPIC — "this utterance is
+//   about AgentDB/versions/the console" — not by the PRAGMATIC property ADR-033 actually needs
+//   ("is this utterance correcting the agent's behaviour"). Two utterances about the same topic,
+//   one a bug report and one a correction, land close together in embedding space; two genuine
+//   corrections about DIFFERENT topics (READMEs vs. scoring vs. version pinning) often do not.
+//   This is the same conclusion ADR-033 reached about lexical overlap, now shown to also hold for
+//   semantic (embedding) overlap on this corpus — it is not a lexical-vs-semantic gap, it is a
+//   topic-vs-pragmatics gap that neither primitive, as tried, closes.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// USAGE
+//   node scripts/correction-detect-embed.mjs measure \
+//     --tune-pool <broad-tune.jsonl> --holdout-pool <broad-holdout.jsonl> --labels <labels.json> \
+//     [--wide-pool <cand-holdout.jsonl>] [--k 5] [--min-sim 0.35] [--tune-k]
+//
+//   --wide-pool, optional: the FULL Signal-1 holdout pool (784 candidates, not just the 159-item
+//   loose-net subset) — runs the frozen classifier over it and reports how many candidates OUTSIDE
+//   the labelled subset it flags positive, honestly marked UNLABELLED rather than guessed at.
+//
+//   --tune-k: run leave-one-out CV over a small (k, minSim) grid on the tune set only, print the
+//   chosen operating point, then use it. Without this flag the script uses the value already found
+//   this way and recorded in DEFAULT_K / DEFAULT_MIN_SIM below (reproducible without re-searching).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const KB_DIR = path.join(__dirname, '..', 'kb');
+
+// Pinned to the exact commit forge-build.mjs pins to, so this script's vectors are byte-identical
+// to the ones the shipped KB would produce for the same text (see forge-build.mjs's own comment on
+// MINILM_REVISION for why: address-by-SHA, not floating `main`).
+const MINILM_REVISION = '751bff37182d3f1213fa05d7196b954e230abad9';
+
+// Found by `--tune-k` leave-one-out search over k in [1,3,5,7,9] and minSim in [0.0,0.15,...,0.6],
+// maximizing tune-set F1 (ties broken toward higher minSim, i.e. more conservative — precision is
+// the safety property here, per ADR-033 §2, so a tie goes to the pickier operating point). Re-run
+// `--tune-k` to reproduce; this corpus is small (112 tune rows) so the search is seconds, not a
+// separate offline step, but the chosen point is frozen here so a bare `measure` run is deterministic
+// without depending on the search being re-run identically.
+export const DEFAULT_K = 5;
+export const DEFAULT_MIN_SIM = 0.3;
+
+/** Resolve the local MiniLM embedder through this repo's OWN resolver — no re-implementation, no
+ *  external API call (CLAUDE.md Rule 1). Fails loudly (via loadTransformers' own network guard) if
+ *  neither a project node_modules nor an env override can find @xenova/transformers. */
+async function loadEmbedder() {
+  const { loadTransformers, configureModel } = await import(path.join(KB_DIR, 'resolve-deps.mjs'));
+  const { T, modelCache, via } = await loadTransformers();
+  const { haveLocalModel } = configureModel(T, modelCache);
+  const embed = await T.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
+    quantized: true, revision: MINILM_REVISION,
+  });
+  return { embed, via, modelCache, haveLocalModel };
+}
+
+/** Utterance ± preceding-action context, exactly as the task specified — the same two fields
+ *  `detectCorrection()` consumes (Signal 1's adjacency evidence), just embedded instead of regexed. */
+export function candidateText(row) {
+  const prior = row.precedingAssistantAction || {};
+  const action = prior.summary || prior.tool || '';
+  return action
+    ? `PRECEDING ACTION: ${String(action).slice(0, 200)}\nUSER: ${row.promptText}`
+    : `USER: ${row.promptText}`;
+}
+
+async function embedBatch(embed, texts, batchSize = 16) {
+  const vectors = [];
+  for (let i = 0; i < texts.length; i += batchSize) {
+    const batch = texts.slice(i, i + batchSize);
+    const out = await embed(batch, { pooling: 'mean', normalize: true });
+    const dim = out.dims[1];
+    for (let j = 0; j < batch.length; j++) vectors.push(Array.from(out.data.slice(j * dim, (j + 1) * dim)));
+  }
+  return vectors;
+}
+
+/** Vectors are already L2-normalized (normalize:true above), so dot product IS cosine similarity —
+ *  same convention kb/forge-build.mjs uses for its RVF store (metric:'cosine' over normalized vecs). */
+function dot(a, b) {
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += a[i] * b[i];
+  return s;
+}
+
+/**
+ * The classifier: similarity-weighted k-NN vote against a labelled reference set. Deliberately NOT
+ * a trained model (no gradient descent, no held weights beyond the reference vectors themselves) —
+ * this keeps every verdict traceable to "which labelled examples it resembles, and how much" rather
+ * than to opaque learned parameters. It is still less legible than the regex (see LEGIBILITY note
+ * at the bottom of this file), but it is the most legible embedding-based option available: the
+ * `neighbors` returned alongside every verdict ARE the explanation, not a post-hoc rationalization.
+ */
+export function classify(vec, refs, { k = DEFAULT_K, minSim = DEFAULT_MIN_SIM } = {}) {
+  const scored = refs.map((r) => ({ ...r, sim: dot(vec, r.vector) })).sort((a, b) => b.sim - a.sim);
+  const top = scored.slice(0, k).filter((r) => r.sim >= minSim);
+  if (!top.length) return { isCorrection: false, score: 0, neighbors: scored.slice(0, 3) };
+  const posWeight = top.filter((r) => r.label === 'true').reduce((s, r) => s + r.sim, 0);
+  const negWeight = top.filter((r) => r.label !== 'true').reduce((s, r) => s + r.sim, 0);
+  return { isCorrection: posWeight > negWeight, score: posWeight - negWeight, neighbors: top.slice(0, 3) };
+}
+
+/** Leave-one-out CV over a small grid, TUNE SET ONLY — never touches holdout. Maximizes F1; ties
+ *  broken toward the higher minSim (more conservative), per ADR-033's precision-over-recall stance. */
+function looSearch(tuneVecs, tuneLabels) {
+  const refs = tuneVecs.map((vector, i) => ({ vector, label: tuneLabels[i] }));
+  let best = null;
+  for (const k of [1, 3, 5, 7, 9]) {
+    for (const minSim of [0, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5, 0.55, 0.6]) {
+      let tp = 0, fp = 0, fn = 0;
+      for (let i = 0; i < refs.length; i++) {
+        const others = refs.slice(0, i).concat(refs.slice(i + 1));
+        const { isCorrection } = classify(refs[i].vector, others, { k, minSim });
+        const truth = refs[i].label === 'true';
+        if (isCorrection && truth) tp++;
+        else if (isCorrection && !truth) fp++;
+        else if (!isCorrection && truth) fn++;
+      }
+      const precision = tp + fp ? tp / (tp + fp) : 0;
+      const recall = tp + fn ? tp / (tp + fn) : 0;
+      const f1 = precision + recall ? (2 * precision * recall) / (precision + recall) : 0;
+      const cand = { k, minSim, tp, fp, fn, precision, recall, f1 };
+      if (!best || f1 > best.f1 || (f1 === best.f1 && minSim > best.minSim)) best = cand;
+    }
+  }
+  return best;
+}
+
+// ── I/O helpers ──────────────────────────────────────────────────────────────────────────────────
+
+function readJsonl(file) {
+  return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+}
+
+function loadLabels(file) {
+  const rows = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const map = new Map();
+  for (const r of rows) map.set(`${r.file}#${r.turnIndex}`, r.label);
+  return map;
+}
+
+function flag(name, fallback = null) {
+  const i = process.argv.indexOf(name);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+
+// ── Measurement ──────────────────────────────────────────────────────────────────────────────────
+
+async function measure() {
+  const tunePoolFile = flag('--tune-pool');
+  const holdoutPoolFile = flag('--holdout-pool');
+  const labelsFile = flag('--labels');
+  const widePoolFile = flag('--wide-pool');
+  const doSearch = process.argv.includes('--tune-k');
+
+  if (!tunePoolFile || !holdoutPoolFile || !labelsFile) {
+    console.error('Usage: node scripts/correction-detect-embed.mjs measure --tune-pool <jsonl> '
+      + '--holdout-pool <jsonl> --labels <labels.json> [--wide-pool <jsonl>] [--tune-k]');
+    console.error('These point at real (private) transcript-derived data — see this file\'s header '
+      + 'for how to regenerate them; nothing of that shape is committed to this repo.');
+    process.exit(1);
+  }
+
+  const labels = loadLabels(labelsFile);
+  const tuneRows = readJsonl(tunePoolFile).map((r) => ({ ...r, label: labels.get(`${r.file}#${r.turnIndex}`) || 'false' }));
+  const holdoutRows = readJsonl(holdoutPoolFile).map((r) => ({ ...r, label: labels.get(`${r.file}#${r.turnIndex}`) || 'false' }));
+
+  console.error(`[embed] tune=${tuneRows.length} (true=${tuneRows.filter(r=>r.label==='true').length}) `
+    + `holdout=${holdoutRows.length} (true=${holdoutRows.filter(r=>r.label==='true').length}, `
+    + `borderline=${holdoutRows.filter(r=>r.label==='borderline').length})`);
+
+  const { embed, via, haveLocalModel, modelCache } = await loadEmbedder();
+  console.error(`[embed] transformers via: ${via} | model: ${haveLocalModel ? 'local cache' : 'REMOTE DOWNLOAD'} (${modelCache})`);
+
+  const tuneVecs = await embedBatch(embed, tuneRows.map(candidateText));
+  const holdoutVecs = await embedBatch(embed, holdoutRows.map(candidateText));
+
+  let opPoint = { k: DEFAULT_K, minSim: DEFAULT_MIN_SIM };
+  if (doSearch) {
+    const found = looSearch(tuneVecs, tuneRows.map((r) => r.label));
+    console.error(`[embed] --tune-k search (leave-one-out, tune only): k=${found.k} minSim=${found.minSim} `
+      + `tune-LOO precision=${(100*found.precision).toFixed(1)}% recall=${(100*found.recall).toFixed(1)}% f1=${found.f1.toFixed(3)}`);
+    opPoint = { k: found.k, minSim: found.minSim };
+  } else {
+    console.error(`[embed] using frozen operating point k=${opPoint.k} minSim=${opPoint.minSim} (rerun with --tune-k to re-search)`);
+  }
+
+  const refs = tuneVecs.map((vector, i) => ({ vector, label: tuneRows[i].label, text: tuneRows[i].promptText }));
+
+  // ── Primary measurement: SAME 159-item labelled holdout population the regex's own examples
+  // came from (broad-holdout.jsonl) — apples-to-apples with correction-detect.mjs's own numbers. ──
+  let tp = 0, fp = 0, fpBorderline = 0, fn = 0, tn = 0;
+  const positives = [];
+  for (let i = 0; i < holdoutRows.length; i++) {
+    const { isCorrection, score, neighbors } = classify(holdoutVecs[i], refs, opPoint);
+    const row = holdoutRows[i];
+    if (isCorrection) {
+      positives.push({ ...row, score, neighbors: neighbors.map((n) => ({ label: n.label, sim: n.sim.toFixed(3), text: n.text.slice(0, 100) })) });
+      if (row.label === 'true') tp++;
+      else if (row.label === 'borderline') { fpBorderline++; }
+      else fp++;
+    } else {
+      if (row.label === 'true' || row.label === 'borderline') fn++;
+      else tn++;
+    }
+  }
+  const totalFp = fp + fpBorderline; // strict: borderline counts against precision, same as the regex's own header treats its 2 holdout borderlines
+  const precisionStrict = tp + totalFp ? tp / (tp + totalFp) : 0;
+  const precisionLenient = (tp + fpBorderline) + fp ? (tp + fpBorderline) / (tp + fpBorderline + fp) : 0;
+  const recallStrict = tp + fn ? tp / (tp + fn) : 0; // fn includes borderlines missed, conservative
+
+  console.log(`\n=== EMBEDDING CLASSIFIER — holdout (n=${holdoutRows.length}, same pool the regex's hand-labelled examples came from) ===`);
+  console.log(`positives (flagged): ${positives.length}`);
+  console.log(`  true positives:        ${tp}`);
+  console.log(`  borderline positives:  ${fpBorderline}`);
+  console.log(`  false positives:       ${fp}`);
+  console.log(`  false negatives (missed true+borderline): ${fn}`);
+  console.log(`precision (strict, borderline counts against): ${(100*precisionStrict).toFixed(1)}%  (${tp}/${tp+totalFp})`);
+  console.log(`precision (lenient, borderline counts for):    ${(100*precisionLenient).toFixed(1)}%  (${tp+fpBorderline}/${tp+fpBorderline+fp})`);
+  console.log(`recall (of ${tp+fn+ (holdoutRows.filter(r=>r.label==='true'||r.label==='borderline').length - (tp+fn))} known true/borderline): ${(100*recallStrict).toFixed(1)}%`);
+
+  console.log(`\n--- flagged positives, with nearest tune neighbours (the "legibility" a verdict can offer) ---`);
+  for (const p of positives) {
+    console.log(`[${p.label.toUpperCase()}] score=${p.score.toFixed(3)} file=${p.file} turn=${p.turnIndex}`);
+    console.log(`  UTTERANCE: ${p.promptText.slice(0, 160).replace(/\n/g,' ')}`);
+    for (const n of p.neighbors) console.log(`   neighbor(${n.label}, sim=${n.sim}): ${n.text.replace(/\n/g,' ')}`);
+  }
+
+  // ── Secondary, optional: the FULL Signal-1 holdout population (not just the loose-net subset) —
+  // the real deployment-scale test. Anything flagged OUTSIDE the labelled 159 is marked UNLABELLED,
+  // never silently assumed either way. ──
+  if (widePoolFile) {
+    const wideRows = readJsonl(widePoolFile);
+    const labelledKeys = new Set(holdoutRows.map((r) => `${r.file}#${r.turnIndex}`));
+    const wideVecs = await embedBatch(embed, wideRows.map(candidateText));
+    let wideFlagged = 0, outsideSubset = 0;
+    const outsideHits = [];
+    for (let i = 0; i < wideRows.length; i++) {
+      const { isCorrection, score } = classify(wideVecs[i], refs, opPoint);
+      if (!isCorrection) continue;
+      wideFlagged++;
+      const k = `${wideRows[i].file}#${wideRows[i].turnIndex}`;
+      if (!labelledKeys.has(k)) { outsideSubset++; outsideHits.push({ ...wideRows[i], score }); }
+    }
+    console.log(`\n=== WIDE HOLDOUT (n=${wideRows.length}, full Signal-1 pool, not just the loose-net subset) ===`);
+    console.log(`flagged: ${wideFlagged}  (of which ${outsideSubset} fall OUTSIDE the 159-item labelled subset — UNLABELLED, hand-review needed, not counted in precision/recall above)`);
+    for (const h of outsideHits.slice(0, 20)) {
+      console.log(`  UNLABELLED file=${h.file} turn=${h.turnIndex} score=${h.score.toFixed(3)}: ${h.promptText.slice(0,160).replace(/\n/g,' ')}`);
+    }
+  }
+}
+
+const invokedDirectly = process.argv[1]
+  && path.resolve(process.argv[1]).endsWith(`correction-detect-embed${path.extname(process.argv[1])}`);
+if (invokedDirectly) {
+  const cmd = process.argv[2];
+  if (cmd === 'measure') measure().catch((e) => { console.error(e); process.exit(1); });
+  else { console.error('Usage: node scripts/correction-detect-embed.mjs measure ...'); process.exit(1); }
+}