ruvnet-brain 4.3.21 → 4.3.25

package/scripts/oracle/unit-inventory.mjs

@@ -0,0 +1,141 @@
+/**
+ * scripts/oracle/unit-inventory.mjs — the parser-independent core of oracle-source-units/2.
+ *
+ * ADR-086:248 asks for U "meaningful source units" per repository. The EXTEND_FIRST Dual verdict
+ * (2026-09-14) made that operational, and this module enforces the parts that do not depend on which
+ * parsers are chosen:
+ *
+ *   - Every tracked entry of the pinned tree (scripts/oracle/source-tree.mjs) receives exactly ONE
+ *     disposition. Nothing is skipped without a named reason.
+ *   - A narrow, published exclusion list only: lockfiles, vendored dependency trees, license
+ *     boilerplate, submodule pointers, symlinks, and opaque binary / LFS modality. Tests, examples,
+ *     configuration, dist output and large files are NOT blanket-excluded any more.
+ *   - Anything else must be claimed by an ADAPTER. Adapters are injected (their parsers are a separate
+ *     decision); each returns units plus errors.
+ *   - COMPLETENESS: any adapter error, or any entry no adapter supports, makes the inventory INCOMPLETE:
+ *     `inventoryComplete: false`, `U: null`, and a separately named `enumeratedU` lower bound. An
+ *     incomplete inventory is never sampled, because it "cannot authorize a passing C3 result".
+ *   - Opaque binaries, LFS pointers, symlinks and gitlinks never count toward emptiness.
+ *
+ * Adapter contract:
+ *   { id, version, parserIdentity, matches(entry, text) -> boolean,
+ *     enumerate({ path, text, bytes }) -> { units: [{ kind, name, sourceType, startByte, endByte, startLine, endLine }],
+ *                                           errors: [{ message, location }] } }
+ */
+import crypto from 'node:crypto';
+import { selectUnits, DEFAULT_SEED } from './unit-sampling.mjs';
+
+export const RULES_VERSION = 'oracle-source-units/2';
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+
+const LOCKFILES = new Set(['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'Cargo.lock', 'poetry.lock', 'Pipfile.lock',
+  'bun.lockb', 'go.sum', 'composer.lock', 'Gemfile.lock', 'flake.lock', 'uv.lock', 'npm-shrinkwrap.json']);
+// External code vendored into the tree is outside the declared repository-source scope. `dist`, `build`
+// and `target` are NOT here: the verdict removed that blanket exclusion, since sole-source distribution
+// content is still the repository's own.
+const VENDORED_DIRS = new Set(['node_modules', 'bower_components', 'vendor', 'vendors', 'third_party', 'third-party',
+  'site-packages', '.venv', 'venv']);
+const LICENSE_FILE = /^(license|licence|copying|notice|patents)(\.[a-z0-9]+)?$/i;
+
+/** The single disposition for an entry that is decided without any adapter, or null if an adapter must decide. */
+export function fixedDisposition(entry) {
+  const segments = entry.path.split('/');
+  const base = segments[segments.length - 1];
+  if (entry.entryKind === 'gitlink') return { disposition: 'excluded', reason: 'submodule-pointer' };
+  if (entry.entryKind === 'symlink') return { disposition: 'excluded', reason: 'symlink' };
+  if (entry.entryKind === 'lfs-pointer') return { disposition: 'modality-excluded', reason: 'lfs-object-not-in-tree' };
+  if (entry.entryKind === 'binary') return { disposition: 'modality-excluded', reason: 'opaque-binary' };
+  if (segments.slice(0, -1).some((s) => VENDORED_DIRS.has(s))) return { disposition: 'excluded', reason: 'vendored-dependency' };
+  if (LOCKFILES.has(base)) return { disposition: 'excluded', reason: 'lockfile' };
+  if (LICENSE_FILE.test(base)) return { disposition: 'excluded', reason: 'license-boilerplate' };
+  return null;
+}
+
+export function unitIdFor({ repo, path, objectSha, kind, startByte, endByte }) {
+  return sha256(Buffer.from(JSON.stringify([repo, path, objectSha, kind, startByte, endByte]), 'utf8')).slice(0, 16);
+}
+
+/**
+ * Build a v2 inventory from a snapshot manifest, its blob bytes and the injected adapters. Pure over its
+ * inputs. `adapters` order is the published dialect precedence: the first adapter that matches claims
+ * the entry.
+ */
+export function buildInventory({ manifest, blobs, adapters, seed = DEFAULT_SEED }) {
+  if (!manifest?.repo || !manifest?.treeSha || !Array.isArray(manifest.entries)) {
+    throw new Error('buildInventory needs a source-tree snapshot manifest');
+  }
+  const rows = [];
+  const units = [];
+  const failures = [];
+  const unsupported = [];
+  for (const entry of manifest.entries) {
+    const fixed = fixedDisposition(entry);
+    if (fixed) { rows.push({ path: entry.path, entryKind: entry.entryKind, ...fixed }); continue; }
+    const bytes = blobs.get(entry.objectSha);
+    if (!bytes) throw new Error(`no blob bytes for ${entry.path} (${entry.objectSha})`);
+    const text = bytes.toString('utf8');
+    if (Buffer.byteLength(text, 'utf8') !== bytes.length || text.includes('�')) {
+      failures.push({ path: entry.path, objectSha: entry.objectSha, adapter: null, message: 'not valid UTF-8 text' });
+      rows.push({ path: entry.path, entryKind: entry.entryKind, disposition: 'extraction-failed', reason: 'decoding' });
+      continue;
+    }
+    const adapter = adapters.find((a) => a.matches(entry, text));
+    if (!adapter) {
+      unsupported.push({ path: entry.path, objectSha: entry.objectSha });
+      rows.push({ path: entry.path, entryKind: entry.entryKind, disposition: 'unsupported-modality', reason: 'no adapter claims this entry' });
+      continue;
+    }
+    let result;
+    try {
+      result = adapter.enumerate({ path: entry.path, text, bytes });
+    } catch (error) {
+      result = { units: [], errors: [{ message: `adapter threw: ${error.message}`, location: null }] };
+    }
+    if (result.errors?.length) {
+      for (const e of result.errors) failures.push({ path: entry.path, objectSha: entry.objectSha, adapter: `${adapter.id}@${adapter.version}`, ...e });
+      rows.push({ path: entry.path, entryKind: entry.entryKind, disposition: 'extraction-failed', adapter: adapter.id, reason: 'parser diagnostics' });
+      continue;
+    }
+    const fileUnits = (result.units || []).map((u) => {
+      if (!(Number.isSafeInteger(u.startByte) && Number.isSafeInteger(u.endByte) && u.startByte >= 0 && u.endByte > u.startByte && u.endByte <= bytes.length)) {
+        throw new Error(`${adapter.id} returned an invalid owned span for ${entry.path}: ${u.startByte}..${u.endByte}`);
+      }
+      const owned = bytes.subarray(u.startByte, u.endByte);
+      return {
+        unitId: unitIdFor({ repo: manifest.repo, path: entry.path, objectSha: entry.objectSha, kind: u.kind, startByte: u.startByte, endByte: u.endByte }),
+        path: entry.path, blobSha: entry.objectSha, kind: u.kind, name: u.name ?? null, sourceType: u.sourceType,
+        startByte: u.startByte, endByte: u.endByte, startLine: u.startLine, endLine: u.endLine,
+        bytesSha256: sha256(owned), chars: owned.toString('utf8').length, adapter: `${adapter.id}@${adapter.version}`,
+      };
+    });
+    units.push(...fileUnits);
+    rows.push({ path: entry.path, entryKind: entry.entryKind, disposition: fileUnits.length ? 'eligible' : 'no-eligible-units', adapter: adapter.id, units: fileUnits.length });
+  }
+
+  const inventoryComplete = failures.length === 0 && unsupported.length === 0;
+  const identity = {
+    rulesVersion: RULES_VERSION, repo: manifest.repo, commitSha: manifest.commitSha, treeSha: manifest.treeSha,
+    manifestSha256: manifest.manifestSha256,
+    adapters: adapters.map((a) => ({ id: a.id, version: a.version, parserIdentity: a.parserIdentity })),
+  };
+  if (!inventoryComplete) {
+    return {
+      ...identity, inventoryComplete: false, U: null, enumeratedU: units.length,
+      failures, unsupported, entries: rows, units, selection: null,
+    };
+  }
+  if (units.length === 0) {
+    // Complete accounting that finds no eligible unit is NOT a measurement and NOT proof of emptiness:
+    // N=0 is NOT_MEASURED, and emptySources needs an independent review receipt over this manifest.
+    return {
+      ...identity, inventoryComplete: true, U: 0, enumeratedU: 0, emptyOfEligibleSource: true, requiresEmptinessReview: true,
+      failures, unsupported, entries: rows, units, selection: null,
+    };
+  }
+  const selection = selectUnits({ units, repo: manifest.repo, treeSha: manifest.treeSha, seed });
+  return {
+    ...identity, inventoryComplete: true, U: units.length, enumeratedU: units.length, emptyOfEligibleSource: false,
+    requiresEmptinessReview: false, failures, unsupported, entries: rows, units, selection,
+  };
+}

package/scripts/oracle/unit-sampling.mjs

@@ -0,0 +1,128 @@
+/**
+ * scripts/oracle/unit-sampling.mjs — deterministic stratified selection of min(100, U) source units.
+ *
+ * ADR-086:248: "Deterministically stratify and select min(100, U) units across modules and source
+ * types." The exact procedure below is the one the EXTEND_FIRST Dual verdict (2026-09-14) specified:
+ *
+ *   stratum   = (source type, module), module = first repository-relative path component, root files
+ *               assigned to the "(root)" module;
+ *   K         = min(100, U);
+ *   if |nonempty strata| <= K: one slot per stratum, then the remaining K - |strata| slots by HAMILTON
+ *               (largest remainder) allocation proportional to each stratum's remaining capacity, ties
+ *               broken by a published seeded hash ordering;
+ *   if |nonempty strata| > K:  choose K strata by the seeded hash ordering, one unit each, and publish
+ *               the omitted strata rather than claim comprehensive representation;
+ *   within a stratum: order unit ids by SHA-256 of the canonical tuple
+ *               [seed, repository, tree, stratum, unit id] and take the allocated prefix.
+ *
+ * Pure: no filesystem, no clock, no randomness. The same input yields the same selection in any process.
+ */
+import crypto from 'node:crypto';
+
+export const SAMPLING_VERSION = 'oracle-unit-sampling/1';
+export const MAX_SELECTED = 100;
+export const DEFAULT_SEED = 'adr-086-c3/1';
+export const ROOT_MODULE = '(root)';
+// The tuple is encoded as a JSON array of strings. JSON.stringify on an array of strings is canonical:
+// no key ordering exists and string escaping is fully specified.
+export const TUPLE_ENCODING = 'json-array-of-strings/utf-8';
+
+const sha256Hex = (text) => crypto.createHash('sha256').update(Buffer.from(text, 'utf8')).digest('hex');
+const byHashThenId = (a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+export function moduleOf(unitPath) {
+  const parts = String(unitPath).split('/').filter(Boolean);
+  return parts.length > 1 ? parts[0] : ROOT_MODULE;
+}
+
+export function stratumOf(unit) {
+  if (!unit?.sourceType) throw new Error(`unit ${unit?.unitId ?? '(unnamed)'} has no sourceType`);
+  return `${unit.sourceType}|${moduleOf(unit.path)}`;
+}
+
+export function orderKey({ seed, repo, treeSha, stratum, unitId }) {
+  return sha256Hex(JSON.stringify([seed, repo, treeSha, stratum, unitId]));
+}
+
+function stratumKey({ seed, repo, treeSha, stratum }) {
+  return sha256Hex(JSON.stringify([seed, repo, treeSha, stratum]));
+}
+
+/** Slots per stratum. `sizes` maps stratum -> eligible unit count (> 0). */
+export function allocate({ sizes, K, seed, repo, treeSha }) {
+  const strata = [...sizes.entries()].filter(([, n]) => n > 0)
+    .map(([id, n]) => ({ id, n, key: stratumKey({ seed, repo, treeSha, stratum: id }) }))
+    .sort(byHashThenId);
+  const total = strata.reduce((s, x) => s + x.n, 0);
+  if (!Number.isSafeInteger(K) || K < 0 || K > total) throw new Error(`cannot allocate K=${K} slots over ${total} units`);
+  const slots = new Map(strata.map((s) => [s.id, 0]));
+  if (K === 0) return { slots, omittedStrata: strata.map((s) => s.id) };
+
+  if (strata.length > K) {
+    // More strata than slots: K strata by seeded hash order, one unit each; the rest are published as omitted.
+    strata.slice(0, K).forEach((s) => slots.set(s.id, 1));
+    return { slots, omittedStrata: strata.slice(K).map((s) => s.id) };
+  }
+
+  strata.forEach((s) => slots.set(s.id, 1));
+  let remaining = K - strata.length;
+  const capacity = strata.map((s) => ({ ...s, cap: s.n - 1 }));
+  const capTotal = capacity.reduce((s, x) => s + x.cap, 0);
+  if (remaining > 0 && capTotal > 0) {
+    // Hamilton: floor of each exact quota, then the leftover to the largest remainders. Remainders are
+    // compared as exact integer numerators (remaining * cap mod capTotal) — no floating point.
+    const quotas = capacity.map((s) => ({
+      ...s,
+      floor: Math.floor((remaining * s.cap) / capTotal),
+      remainder: (remaining * s.cap) % capTotal,
+    }));
+    for (const q of quotas) slots.set(q.id, slots.get(q.id) + q.floor);
+    let leftover = remaining - quotas.reduce((s, q) => s + q.floor, 0);
+    const byRemainder = quotas
+      .filter((q) => slots.get(q.id) < q.n)
+      .sort((a, b) => (b.remainder - a.remainder) || byHashThenId(a, b));
+    for (const q of byRemainder) {
+      if (leftover === 0) break;
+      slots.set(q.id, slots.get(q.id) + 1);
+      leftover -= 1;
+    }
+    remaining = leftover;
+  }
+  if (remaining !== 0) throw new Error(`allocation left ${remaining} slot(s) unassigned`);
+  return { slots, omittedStrata: [] };
+}
+
+/**
+ * Select min(100, U) of `units` (each: { unitId, path, sourceType }). Returns the full publication record
+ * the Dual verdict requires: U, K, seed, algorithm identity, per-stratum allocations, omitted strata and
+ * the exact selected ids in selection order.
+ */
+export function selectUnits({ units, repo, treeSha, seed = DEFAULT_SEED, maxSelected = MAX_SELECTED }) {
+  if (!repo || !treeSha) throw new Error('selectUnits requires the repository and tree identity it samples');
+  const seen = new Set();
+  const byStratum = new Map();
+  for (const unit of units) {
+    if (seen.has(unit.unitId)) throw new Error(`duplicate unit id ${unit.unitId}`);
+    seen.add(unit.unitId);
+    const stratum = stratumOf(unit);
+    if (!byStratum.has(stratum)) byStratum.set(stratum, []);
+    byStratum.get(stratum).push({ id: unit.unitId, key: orderKey({ seed, repo, treeSha, stratum, unitId: unit.unitId }) });
+  }
+  const U = units.length;
+  const K = Math.min(maxSelected, U);
+  const sizes = new Map([...byStratum].map(([s, list]) => [s, list.length]));
+  const { slots, omittedStrata } = allocate({ sizes, K, seed, repo, treeSha });
+  const selected = [];
+  const allocations = [];
+  for (const stratum of [...byStratum.keys()].sort()) {
+    const take = slots.get(stratum) || 0;
+    const ordered = byStratum.get(stratum).sort(byHashThenId);
+    allocations.push({ stratum, eligible: ordered.length, selected: take });
+    selected.push(...ordered.slice(0, take).map((u) => u.id));
+  }
+  if (selected.length !== K) throw new Error(`selected ${selected.length} units, expected K=${K}`);
+  return {
+    samplingVersion: SAMPLING_VERSION, tupleEncoding: TUPLE_ENCODING, seed, repo, treeSha,
+    U, K, N: 2 * K, allocations, omittedStrata, selected,
+  };
+}

package/scripts/oracle/validate-labels.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/validate-labels.mjs — Step 14 (ADR-086 C3) deterministic label validation.
+ *
+ * NO LLM. Every produced label is checked against exact upstream bytes re-read from disk:
+ *   (a) verbatim  — the span is an exact substring of the unit text at the pinned blob SHA (the blob is
+ *                   re-hashed; drift fails everything). Diagnostics record whether the span would have
+ *                   matched after whitespace normalisation, and whether the producer's line range points
+ *                   at the same text — the two facts that decide the Step 15 span-binding design.
+ *   (b) non-trivial — ≥ 40 chars and ≥ 6 tokens, not the whole unit (≤ 90% of it), not a heading alone.
+ *   (c) no leakage  — neither question restates the answer: bge-base cosine(question, span) < 0.92 AND
+ *                   4-gram coverage of the question by the span < 0.5. The 0.92 bound is calibrated in
+ *                   the run itself: synthetic leaky questions built from the span's own words are
+ *                   embedded and their cosine distribution is reported next to the real one.
+ *   (d) paraphrase differs — token Jaccard(direct, paraphrase) ≤ 0.7 and not equal after normalisation.
+ *   (e) informational, not scored — cosine(direct, paraphrase) ≥ 0.70 (a paraphrase that drifted).
+ * Labels the producer skipped or failed on FAIL every check: errors count as failures (Dual threshold).
+ *
+ * The embedder is the local ONNX Xenova/bge-base-en-v1.5 already cached for the KB (768-dim, cls
+ * pooling, normalised) — no network. If it is not cached the validator refuses rather than downloads.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gitBlobSha, sha256Hex, unitText } from './source-units.mjs';
+
+export const THRESHOLDS = Object.freeze({
+  minSpanChars: 40, minSpanTokens: 6, maxSpanFractionOfUnit: 0.9,
+  leakCosine: 0.92, leakNgramCoverage: 0.5, ngram: 4,
+  paraphraseMaxJaccard: 0.7, paraphraseMinCosine: 0.70,
+});
+
+export const normalizeWs = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
+export const tokens = (s) => String(s ?? '').toLowerCase().match(/[a-z0-9_]+/g) || [];
+export function jaccard(a, b) {
+  const A = new Set(a); const B = new Set(b);
+  if (A.size === 0 && B.size === 0) return 1;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter++;
+  return inter / (A.size + B.size - inter);
+}
+export function ngramCoverage(question, span, n = THRESHOLDS.ngram) {
+  const q = tokens(question); const s = tokens(span);
+  if (q.length < n) return q.length && q.every((t) => s.includes(t)) ? 1 : 0;
+  const grams = new Set();
+  for (let i = 0; i + n <= s.length; i++) grams.add(s.slice(i, i + n).join(' '));
+  let hit = 0; let total = 0;
+  for (let i = 0; i + n <= q.length; i++) { total++; if (grams.has(q.slice(i, i + n).join(' '))) hit++; }
+  return total ? hit / total : 0;
+}
+export function cosine(a, b) {
+  let dot = 0; let na = 0; let nb = 0;
+  for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+  return na && nb ? dot / Math.sqrt(na * nb) : 0;
+}
+const isHeadingLine = (line) => /^\s*#{1,6}\s/.test(line);
+
+export function checkVerbatim(unit, label) {
+  const span = String(label.span ?? '');
+  const pass = span.length > 0 && unit.includes(span);
+  const normalizedMatch = span.length > 0 && normalizeWs(unit).includes(normalizeWs(span));
+  const lines = unit.split('\n');
+  const s = label.spanStartLine; const e = label.spanEndLine;
+  let lineRangeMatch = false;
+  if (Number.isInteger(s) && Number.isInteger(e) && s >= 1 && e >= s && e <= lines.length) {
+    // CONTAINMENT, not Jaccard: a short span inside a long line is a correct line reference, and
+    // Jaccard would score it ~0.27 purely because the line has other words on it.
+    const rangeTokens = new Set(tokens(lines.slice(s - 1, e).join('\n')));
+    const spanTokens = tokens(span);
+    lineRangeMatch = spanTokens.length > 0 && spanTokens.filter((t) => rangeTokens.has(t)).length / spanTokens.length >= 0.8;
+  }
+  return { pass, reason: pass ? '' : span.length === 0 ? 'empty span' : normalizedMatch ? 'not verbatim (matches after whitespace normalisation)' : 'span not found in unit', normalizedMatch, lineRangeMatch };
+}
+
+export function checkNonTrivial(unit, span, t = THRESHOLDS) {
+  span = String(span ?? '');
+  const toks = tokens(span);
+  if (span.length < t.minSpanChars) return { pass: false, reason: `span ${span.length} chars < ${t.minSpanChars}` };
+  if (toks.length < t.minSpanTokens) return { pass: false, reason: `span ${toks.length} tokens < ${t.minSpanTokens}` };
+  if (normalizeWs(span) === normalizeWs(unit)) return { pass: false, reason: 'span is the whole unit' };
+  if (span.length > t.maxSpanFractionOfUnit * unit.length) return { pass: false, reason: `span is ${Math.round((100 * span.length) / unit.length)}% of the unit` };
+  const contentLines = span.split('\n').filter((l) => l.trim());
+  if (contentLines.length && contentLines.every((l) => isHeadingLine(l))) return { pass: false, reason: 'span is a heading line alone' };
+  return { pass: true, reason: '' };
+}
+
+export function checkNoLeak({ question, span, cos }, t = THRESHOLDS) {
+  const coverage = ngramCoverage(question, span, t.ngram);
+  const reasons = [];
+  if (cos >= t.leakCosine) reasons.push(`cosine ${cos.toFixed(3)} >= ${t.leakCosine}`);
+  if (coverage >= t.leakNgramCoverage) reasons.push(`${t.ngram}-gram coverage ${coverage.toFixed(2)} >= ${t.leakNgramCoverage}`);
+  return { pass: reasons.length === 0, reason: reasons.join('; '), cosine: cos, ngramCoverage: coverage };
+}
+
+export function checkParaphraseDiffers(direct, paraphrase, t = THRESHOLDS) {
+  if (!normalizeWs(paraphrase)) return { pass: false, reason: 'empty paraphrase', jaccard: 0 };
+  if (normalizeWs(direct).toLowerCase() === normalizeWs(paraphrase).toLowerCase()) return { pass: false, reason: 'paraphrase equals direct question', jaccard: 1 };
+  const j = jaccard(tokens(direct), tokens(paraphrase));
+  return { pass: j <= t.paraphraseMaxJaccard, reason: j <= t.paraphraseMaxJaccard ? '' : `token Jaccard ${j.toFixed(2)} > ${t.paraphraseMaxJaccard}`, jaccard: j };
+}
+
+function readUnit(snapshotDir, label, cache) {
+  if (!cache.has(label.path)) {
+    let buf;
+    try { buf = fs.readFileSync(path.join(snapshotDir, label.path)); } catch { cache.set(label.path, null); return null; }
+    cache.set(label.path, { blobSha: gitBlobSha(buf), lines: buf.toString('utf8').split('\n') });
+  }
+  const file = cache.get(label.path);
+  if (!file || file.blobSha !== label.blobSha) return null;
+  const text = unitText(file.lines, label.startLine, label.endLine);
+  return sha256Hex(Buffer.from(text, 'utf8')) === label.bytesSha256 ? text : null;
+}
+
+const failAll = (reason) => ({ a: { pass: false, reason }, b: { pass: false, reason }, c: { pass: false, reason }, d: { pass: false, reason } });
+const quantiles = (xs) => {
+  const s = [...xs].sort((a, b) => a - b);
+  const q = (p) => (s.length ? s[Math.min(s.length - 1, Math.floor(p * (s.length - 1)))] : null);
+  return { n: s.length, min: q(0), p10: q(0.1), p50: q(0.5), p90: q(0.9), max: q(1) };
+};
+
+/** Synthetic leaky question: the span's own first 20 tokens — what a lazy producer would emit. */
+export const leakyQuestionFor = (span) => `According to the text, ${tokens(span).slice(0, 20).join(' ')}?`;
+
+export async function validateLabels({ labels, snapshotDir, embed, thresholds = THRESHOLDS }) {
+  const cache = new Map();
+  const rows = labels.labels.map((label) => ({ label, unit: label.producerError || label.skip ? null : readUnit(snapshotDir, label, cache) }));
+  const live = rows.filter((r) => r.unit !== null);
+  const texts = [];
+  const index = (t) => { texts.push(t); return texts.length - 1; };
+  for (const r of live) r.emb = { d: index(r.label.direct), p: index(r.label.paraphrase), s: index(r.label.span), leak: index(leakyQuestionFor(r.label.span)) };
+  const vectors = texts.length ? await embed(texts) : [];
+  const perLabel = [];
+  const leakyCos = [];
+  const directCos = [];
+  const paraCos = [];
+  for (const { label, unit, emb } of rows) {
+    if (label.producerError) { perLabel.push({ unitId: label.unitId, path: label.path, pass: false, checks: failAll(`producer error: ${label.producerError}`) }); continue; }
+    if (label.skip) { perLabel.push({ unitId: label.unitId, path: label.path, pass: false, checks: failAll(`skipped by producer: ${label.skipReason}`) }); continue; }
+    if (unit === null) { perLabel.push({ unitId: label.unitId, path: label.path, pass: false, checks: failAll('blob or unit drift: upstream bytes differ from the inventory') }); continue; }
+    const v = (i) => vectors[i];
+    const a = checkVerbatim(unit, label);
+    const b = checkNonTrivial(unit, label.span, thresholds);
+    const cd = checkNoLeak({ question: label.direct, span: label.span, cos: cosine(v(emb.d), v(emb.s)) }, thresholds);
+    const cp = checkNoLeak({ question: label.paraphrase, span: label.span, cos: cosine(v(emb.p), v(emb.s)) }, thresholds);
+    const c = { pass: cd.pass && cp.pass, reason: [cd.reason && `direct: ${cd.reason}`, cp.reason && `paraphrase: ${cp.reason}`].filter(Boolean).join('; '), direct: cd, paraphrase: cp };
+    const d = checkParaphraseDiffers(label.direct, label.paraphrase, thresholds);
+    const eCos = cosine(v(emb.d), v(emb.p));
+    const e = { pass: eCos >= thresholds.paraphraseMinCosine, cosine: eCos, reason: eCos >= thresholds.paraphraseMinCosine ? '' : `cosine(direct, paraphrase) ${eCos.toFixed(3)} < ${thresholds.paraphraseMinCosine}` };
+    leakyCos.push(cosine(v(emb.leak), v(emb.s)));
+    directCos.push(cd.cosine);
+    paraCos.push(cp.cosine);
+    // Role-neutral judge verdicts: path B (2026-09-14) lets claude judge, so read `judge` and fall back to
+    // the historical codex-shaped record. `codex` is still carried unchanged for existing consumers.
+    const judge = label.judge ?? (label.codex ? { host: 'codex', ...label.codex } : undefined);
+    perLabel.push({ unitId: label.unitId, path: label.path, kind: label.kind, pass: a.pass && b.pass && c.pass && d.pass, checks: { a, b, c, d }, informational: { e }, codex: label.codex, judge });
+  }
+  const count = (key) => ({ pass: perLabel.filter((r) => r.checks[key].pass).length, fail: perLabel.filter((r) => !r.checks[key].pass).length });
+  const codexVerdicts = perLabel.filter((r) => r.codex && !r.codex.error);
+  const yes = (side) => codexVerdicts.filter((r) => r.codex[side]?.answers === 'yes').length;
+  return {
+    schemaVersion: 1, kind: 'oracle-validation', repo: labels.repo, commit: labels.commit, thresholds,
+    aggregate: {
+      total: perLabel.length, pass: perLabel.filter((r) => r.pass).length,
+      producerErrors: rows.filter((r) => r.label.producerError).length, skipped: rows.filter((r) => r.label.skip).length,
+      byCheck: { a: count('a'), b: count('b'), c: count('c'), d: count('d') },
+      informationalE: { pass: perLabel.filter((r) => r.informational?.e.pass).length, evaluated: perLabel.filter((r) => r.informational).length },
+      secondary: {
+        whitespaceNormalizedMatch: perLabel.filter((r) => r.checks.a.normalizedMatch).length,
+        lineRangeMatch: perLabel.filter((r) => r.checks.a.lineRangeMatch).length,
+        verbatimOrNormalized: perLabel.filter((r) => r.checks.a.pass || r.checks.a.normalizedMatch).length,
+      },
+      codex: {
+        withVerdicts: codexVerdicts.length, directYes: yes('direct'), paraphraseYes: yes('paraphrase'),
+        bothYes: codexVerdicts.filter((r) => r.codex.direct?.answers === 'yes' && r.codex.paraphrase?.answers === 'yes').length,
+        bothYesAndAllChecksPass: codexVerdicts.filter((r) => r.pass && r.codex.direct?.answers === 'yes' && r.codex.paraphrase?.answers === 'yes').length,
+      },
+      // Whichever host judged. `allThreeYes` also requires the pair-equivalence verdict Dual required:
+      // two supported questions are not proof the paraphrase means the same thing.
+      judge: (() => {
+        const judged = perLabel.filter((r) => r.judge && !r.judge.error && !r.judge.direct?.error);
+        const yesOn = (side) => judged.filter((r) => r.judge[side]?.answers === 'yes').length;
+        const allThree = (r) => ['direct', 'paraphrase', 'equivalent'].every((side) => r.judge[side]?.answers === 'yes');
+        return {
+          hosts: [...new Set(judged.map((r) => r.judge.host))], withVerdicts: judged.length,
+          directYes: yesOn('direct'), paraphraseYes: yesOn('paraphrase'), equivalentYes: yesOn('equivalent'),
+          allThreeYes: judged.filter(allThree).length, allThreeYesAndAllChecksPass: judged.filter((r) => r.pass && allThree(r)).length,
+        };
+      })(),
+      cosineCalibration: { directVsSpan: quantiles(directCos), paraphraseVsSpan: quantiles(paraCos), syntheticLeakyVsSpan: quantiles(leakyCos) },
+    },
+    perLabel,
+  };
+}
+
+/** Local ONNX bge-base via the KB's own loader. Refuses to download: validation must be offline. */
+export async function loadBgeEmbedder({ kbDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../kb') } = {}) {
+  const [{ loadTransformers, chooseModelCache }, { BGE_MODEL, configureTransformersModel, modelCacheReady }] = await Promise.all([
+    import(path.join(kbDir, 'resolve-deps.mjs')), import(path.join(kbDir, 'model-requirements.mjs')),
+  ]);
+  const { T } = await loadTransformers();
+  const cache = chooseModelCache({ kbDir });
+  if (!modelCacheReady(cache, BGE_MODEL)) throw new Error(`bge-base is not cached at ${cache}; set KB_MODEL_CACHE to a warm cache (validation never downloads)`);
+  configureTransformersModel(T, cache, BGE_MODEL);
+  T.env.allowRemoteModels = false;
+  const fe = await T.pipeline('feature-extraction', BGE_MODEL, { quantized: true });
+  return async (texts) => {
+    const out = [];
+    for (let i = 0; i < texts.length; i += 32) {
+      const batch = texts.slice(i, i + 32).map((t) => (t && t.trim() ? t : ' '));
+      const res = await fe(batch, { pooling: 'cls', normalize: true });
+      const [, dim] = res.dims;
+      for (let j = 0; j < batch.length; j++) out.push(Array.from(res.data.slice(j * dim, (j + 1) * dim)));
+    }
+    return out;
+  };
+}
+
+function arg(argv, flag) { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : undefined; }
+
+export async function main(argv = process.argv.slice(2)) {
+  const labelsFile = arg(argv, '--labels');
+  const snapshotDir = arg(argv, '--dir');
+  const out = arg(argv, '--out');
+  if (!labelsFile || !snapshotDir) { process.stderr.write('Usage: validate-labels.mjs --labels <labels.json> --dir <snapshot> [--out <validation.json>]\n'); return 64; }
+  const labels = JSON.parse(fs.readFileSync(labelsFile, 'utf8'));
+  const embed = await loadBgeEmbedder();
+  const validation = await validateLabels({ labels, snapshotDir: path.resolve(snapshotDir), embed });
+  const json = `${JSON.stringify(validation, null, 2)}\n`;
+  if (out) fs.writeFileSync(out, json); else process.stdout.write(json);
+  const a = validation.aggregate;
+  process.stderr.write(`[validate] ${labels.repo}: ${a.pass}/${a.total} pass | a=${a.byCheck.a.pass} b=${a.byCheck.b.pass} c=${a.byCheck.c.pass} d=${a.byCheck.d.pass} | ws-normalised=${a.secondary.whitespaceNormalizedMatch} line-range=${a.secondary.lineRangeMatch}\n`);
+  return 0;
+}
+
+// Entry-point guard. Compares REALPATHS on both sides: path.resolve() normalizes a path but does
+// NOT follow symlinks, while import.meta.url IS symlink-resolved by Node. Through a symlink (npm bin
+// shims, wrapper scripts, and every os.tmpdir() path on macOS) the two sides disagree, so main()
+// never runs -- and because nothing throws, the process exits 0. A silent exit 0 is indistinguishable
+// from "ran, found nothing", which is how prepareCorpusCandidate once reported SUCCESS with no
+// archive on disk. Reproduced live 2026-07-27; pinned by tests/unit/entrypoint-symlink.test.mjs.
+function isDirectInvocation() {
+  try {
+    if (!process.argv[1]) return false;
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation()) process.exitCode = await main();