@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/review/run-replay.js

@@ -0,0 +1,729 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReplay = runReplay;
+exports.semanticCaseRanking = semanticCaseRanking;
+// @implements A-SPEC-346
+// @implements A-SPEC-347
+// @implements A-SPEC-348
+// @implements A-SPEC-349
+// @implements A-SPEC-378
+// @implements A-SPEC-402
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+const rtm_builder_1 = require("../rtm/rtm-builder");
+const rtm_graph_1 = require("../rtm/rtm-graph");
+const test_scope_1 = require("../rtm/test-scope");
+const spec_store_1 = require("../spec/spec-store");
+const spec_types_1 = require("../spec/spec-types");
+const maintenance_analyze_1 = require("../mcp/maintenance-analyze");
+const point_in_time_replay_1 = require("./point-in-time-replay");
+const evaluation_metrics_1 = require("./evaluation-metrics");
+const replay_corpus_1 = require("./replay-corpus");
+const semantic_arm_1 = require("./semantic-arm");
+// @implements A-SPEC-479 — pre-emission verification of the union answer (measurement only).
+// @implements A-SPEC-488 — lexPoverty drives the gate simulation ("uncited ∨ lexically poor").
+const union_verify_1 = require("./union-verify");
+// @implements A-SPEC-480 — coherence verification: the emission's internal graph relations.
+const coherence_verify_1 = require("./coherence-verify");
+const localize_1 = require("../rtm/localize");
+// @implements A-SPEC-483 — content-level verification: the candidate's BODY, read from the
+// materialized parent tree.
+const content_verify_1 = require("./content-verify");
+// @implements A-SPEC-467 — the associative-recall arm: measured beside the product, never inside it.
+const assoc_arm_1 = require("../assoc/assoc-arm");
+// @implements A-SPEC-470 — the impact axis's Phase-B external yardstick, always scored.
+const impact_baseline_1 = require("../assoc/impact-baseline");
+const dense_retrieval_1 = require("./dense-retrieval");
+// @implements A-SPEC-472 — the three-arm iteration experiment (static / re-seed / judged).
+const explore_1 = require("../assoc/explore");
+const temporal_prior_1 = require("./temporal-prior");
+const commit_text_1 = require("./commit-text");
+/**
+ * Run the point-in-time replay against ANY corpus.
+ *
+ * Lifted verbatim from the benchmark that lived inside `maintenance-analyze.test.ts`, where it was
+ * bound to this repository's paths. Every verdict in this work came from that single corpus, so the
+ * measurements could not be falsified by a second one — this is what makes them falsifiable.
+ *
+ * Equivalence is the load-bearing property of the extraction: this repository's numbers must come
+ * out unchanged, or subsequent comparisons measure the refactor instead of the corpora.
+ */
+async function runReplay(corpus, limit, opts = {}) {
+    const started = Date.now();
+    const cases = (0, replay_corpus_1.casesFor)(corpus, limit, opts.offset ?? 0);
+    const outcomes = [];
+    const impactCases = [];
+    // @implements A-SPEC-470 — same cases, same denominator; only the predictor is poor on purpose.
+    const impactBaselineCases = [];
+    const unionCases = [];
+    const idfOutcomes = [];
+    const pprConfigs = opts.pprConfigs ?? [];
+    const pprOutcomes = new Map(pprConfigs.map((c) => [c.label, { rerank: [], admit: [] }]));
+    const PPR_IMPACT_KS = [5, 10, 20];
+    const pprImpactCases = new Map(pprConfigs.flatMap((c) => PPR_IMPACT_KS.map((k) => [`${c.label}@${k}`, []])));
+    // @implements A-SPEC-473 — arm D joins the same harness; A/B/C rows are untouched.
+    const ITER_ARMS = ['A', 'B', 'C', 'D'];
+    const ITER_E = 2, ITER_R = 10;
+    // per arm, per round index: macro-mean accumulators over cases
+    const iterAcc = new Map(opts.iterativeArms === true ? ITER_ARMS.map((a) => [a, []]) : []);
+    const semRerank = [];
+    const semAdmit = [];
+    // @implements A-SPEC-488 — one row set per simulated gate.
+    // @implements A-SPEC-491 — two admit-ACTION rows join the five rerank rows: where the lexical
+    // signal is poor, reranking the same pool cannot restore reach; only replacement can.
+    // @implements A-SPEC-492 — the compound STARVED gate: poverty alone over-fires cross-lingually
+    // (S-509), so replacement additionally requires the product's top-1 lexical score to be near
+    // zero — "the ranker found essentially nothing", a scale-free starvation verdict.
+    const SEM_GATES = ['uncited', 'poor@0.25', 'poor@0.5', 'or@0.25', 'or@0.5', 'admitPoor@0.25', 'admitPoor@0.5', 'admitStarved@1', 'admitStarved@5'];
+    const semGateRows = new Map(opts.semanticArm?.gates === true ? SEM_GATES.map((g) => [g, []]) : []);
+    // @implements A-SPEC-493 — union ∪ admit-top-K accumulators (gates runs only).
+    const UPA_KS = [3, 5];
+    const upaCases = new Map(opts.semanticArm?.gates === true ? UPA_KS.map((k) => [k, []]) : []);
+    const FRONTIER_ALPHAS = [0, 0.3, 0.5, 0.7];
+    const FRONTIER_KS = [1, 2, 3, 5, 10];
+    const frontierCases = new Map(opts.impactFrontier === true
+        ? FRONTIER_ALPHAS.flatMap((a) => FRONTIER_KS.map((k) => [`${a}@${k}`, []]))
+        : []);
+    // @implements A-SPEC-479 — the verification grid: per-candidate independent accept (no position
+    // budget in the verdict) behind an explicit head guard, the separate axis.
+    // @implements A-SPEC-484 — τ grid injectable (model-conditional absolute cosines); default
+    // frozen for S-497 reproducibility.
+    const UV_SEM_TAUS = (0, union_verify_1.semTauGrid)(opts.unionVerify?.semTaus);
+    const UV_LEX_TAUS = [0.05, 0.15, 0.3];
+    const UV_GUARDS = [0, 1, 3];
+    const uvCases = new Map(opts.unionVerify !== undefined
+        ? [
+            ...UV_SEM_TAUS.flatMap((t) => UV_GUARDS.map((g) => [`sem@${t}@${g}`, []])),
+            ...UV_LEX_TAUS.flatMap((t) => UV_GUARDS.map((g) => [`lex@${t}@${g}`, []])),
+        ]
+        : []);
+    // @implements A-SPEC-480 — the coherence grid: evidence mode × head size. Graph-only, no
+    // embeddings; the head is kept by the explicit guard, the tail lives or dies by its relations.
+    const UC_MODES = ['edge', 'spec', 'any'];
+    const UC_HS = [1, 2, 3];
+    const ucCases = new Map(opts.unionCoherence === true
+        ? UC_MODES.flatMap((m) => UC_HS.map((h) => [`${m}@${h}`, []]))
+        : []);
+    // @implements A-SPEC-481 — the position-independent grid: family × relation × guard.
+    const CR_RELS = ['edge', 'any'];
+    const CR_DS = [1, 2, 3];
+    const CR_GUARDS = [0, 1, 3];
+    const crCases = new Map(opts.coherenceRobust === true
+        ? CR_RELS.flatMap((rel) => CR_GUARDS.flatMap((g) => [
+            ...CR_DS.map((d) => [`deg@${rel}@${d}@${g}`, []]),
+            [`clu@${rel}@0@${g}`, []],
+        ]))
+        : []);
+    // @implements A-SPEC-482 — the combination grid, drawn ONLY from the published S-498/499 bests.
+    const AC_ANCHORS = [['edge', 2], ['spec', 1], ['spec', 2], ['any', 1]];
+    const AC_DS = [1, 2];
+    const AC_COMBS = ['or', 'and'];
+    const acCases = new Map(opts.anchoredConsensus === true
+        ? AC_ANCHORS.flatMap(([m, h]) => AC_DS.flatMap((d) => AC_COMBS.map((cb) => [`${m}@${h}@${d}@${cb}`, []])))
+        : []);
+    // @implements A-SPEC-483 — the content grid: five signals × the explicit guard axis.
+    const CV_SIGNALS = ['body1', 'body2', 'mention', 'bodyOrMention', 'bodyAndMention'];
+    const CV_GUARDS = [0, 1, 3];
+    const cvCases = new Map(opts.contentVerify === true
+        ? CV_SIGNALS.flatMap((s) => CV_GUARDS.map((g) => [`${s}@${g}`, []]))
+        : []);
+    const impactCeilingCases = [];
+    const unionCeilingCases = [];
+    let unmeasured = 0;
+    let casesWithoutSpecs = 0;
+    for (const c of cases) {
+        const dest = fs.mkdtempSync(path.join(os.tmpdir(), `replay-${c.commit.slice(0, 8)}-`));
+        const parent = `${c.commit}^`;
+        try {
+            const laid = (0, point_in_time_replay_1.materializeTreeAt)(corpus.root, parent, corpus.sourcePathspec[0], dest);
+            if (!laid.ok) {
+                unmeasured++;
+                continue;
+            }
+            for (const extra of corpus.sourcePathspec.slice(1)) {
+                (0, point_in_time_replay_1.materializeTreeAt)(corpus.root, parent, extra, dest, { allowNonEmpty: true });
+            }
+            // Proven, not trusted: a wrong tree still produces plausible numbers.
+            if ((0, point_in_time_replay_1.verifyTreeFidelity)(corpus.root, parent, corpus.sourcePathspec[0], dest).mismatches.length > 0) {
+                unmeasured++;
+                continue;
+            }
+            const laidSpecs = (0, point_in_time_replay_1.materializeTreeAt)(corpus.root, parent, corpus.specPathspec, dest, { allowNonEmpty: true });
+            if (!laidSpecs.ok)
+                casesWithoutSpecs++;
+            // Awaited, not stubbed: an earlier draft returned [] here for want of a sync reader, which
+            // would have scored every case with no specs and produced numbers that merely LOOKED like the
+            // originals. Equivalence is the whole point of this extraction.
+            const specs = laidSpecs.ok
+                ? (0, spec_types_1.filterGoverned)(await new spec_store_1.LocalMarkdownRepository(path.join(dest, corpus.specPathspec)).list())
+                : [];
+            const scanned = new cpg_scanner_1.CpgScanner().scan(dest, dest);
+            const anchors = (0, test_scope_1.scanTestAnchors)(dest);
+            const graph = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, graph);
+                // @implements A-SPEC-378
+                // Windowed at the PARENT. Reading the answer commit would make the file it touched look
+                // recently changed because it is about to be — the benchmark would be scoring a leak.
+                const prior = (0, temporal_prior_1.temporalPrior)(corpus.root, parent, 300);
+                const changePrior = {};
+                for (const [file, age] of prior.recency)
+                    changePrior[file] = 1 + Math.pow(0.5, age / 10);
+                // @implements A-SPEC-402
+                // The commit-prose layer, which the MCP handler supplies and this replay did not. Without it
+                // the benchmark scored FOUR of the five layers that ship and every "current product" figure
+                // reported from it understated what a caller actually gets — a benchmark measuring something
+                // adjacent to the product is worse than one measuring nothing, because it reads as if it
+                // measured the product.
+                const known = new Set(scanned.map((f) => f.sourcePath));
+                const profile = (0, commit_text_1.commitTextProfile)(corpus.root, parent, 400);
+                const ct = (0, commit_text_1.rankByCommitText)(c.subject, profile, 300).filter((h) => known.has(h.file));
+                const top = ct[0]?.score ?? 0;
+                const commitTextBoost = {};
+                if (top > 0)
+                    for (const h of ct)
+                        commitTextBoost[h.file] = h.score / top;
+                const result = (0, maintenance_analyze_1.analyzeMaintenance)({
+                    request: c.subject, scanned, specs, graph, testAnchors: anchors, history: [], changePrior, commitTextBoost,
+                    groundTruth: { files: c.files, tests: c.tests },
+                    basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
+                    coverage: { scannedFiles: scanned.length, skippedFiles: [], unsupportedLanguages: [] },
+                });
+                const ranked = result.candidates.map((x) => x.file);
+                // @implements A-SPEC-469 — the union scores what a caller actually RECEIVES as the impact
+                // answer, and that surface is now the graded rankedImpact (the closure stays gate-facing).
+                const impacted = (result.impacts?.rankedImpact ?? []).map((r) => r.file);
+                outcomes.push({ ranked, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests });
+                // @implements A-SPEC-487 — the dump: 2-pass with semantic injected when asked (vectors
+                // only for the files the 1-pass surfaced — the hot-path lookup contract holds), 1-pass
+                // otherwise. Nothing here feeds outcomes or any pin.
+                if (opts.caseDump !== undefined) {
+                    let dumpResult = result;
+                    if (opts.productSemantic !== undefined) {
+                        const dumpDocText = new Map(scanned.map((f) => [f.sourcePath,
+                            (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+                        const targets = [...new Set([...result.candidates.map((x) => x.file),
+                                ...(result.impacts?.rankedImpact ?? []).map((r) => r.file)])];
+                        const texts = targets.map((f) => dumpDocText.get(f)).filter((t) => t !== undefined);
+                        const [qv] = await opts.productSemantic.embedBatch([c.subject], 'query');
+                        const dvs = texts.length > 0 ? await opts.productSemantic.embedBatch(texts, 'doc') : [];
+                        const vecOf = new Map(texts.map((t, i) => [t, dvs[i] ?? null]));
+                        dumpResult = (0, maintenance_analyze_1.analyzeMaintenance)({
+                            request: c.subject, scanned, specs, graph, testAnchors: anchors, history: [], changePrior, commitTextBoost,
+                            semantic: {
+                                label: opts.productSemantic.label,
+                                queryVector: qv ?? null,
+                                cachedDocVector: (text) => vecOf.get(text) ?? null,
+                            },
+                            basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
+                            coverage: { scannedFiles: scanned.length, skippedFiles: [], unsupportedLanguages: [] },
+                        });
+                    }
+                    // @implements A-SPEC-489 — excerpts from the materialized tree, top union-order files.
+                    let bodies;
+                    if (opts.dumpBodies !== undefined) {
+                        bodies = {};
+                        const order = [...new Set([...dumpResult.candidates.map((x) => x.file),
+                                ...(dumpResult.impacts?.rankedImpact ?? []).map((r) => r.file)])].slice(0, opts.dumpBodies.top);
+                        for (const f of order) {
+                            try {
+                                const raw = fs.readFileSync(path.join(dest, f), 'utf8');
+                                // @implements A-SPEC-490 — the informative excerpt: license blocks first, then cut.
+                                const text = opts.dumpBodies.skipLicense === true ? (0, content_verify_1.skipLicenseHeader)(raw) : raw;
+                                bodies[f] = text.slice(0, opts.dumpBodies.chars);
+                            }
+                            catch { /* unreadable candidate: omitted */ }
+                        }
+                    }
+                    opts.caseDump({
+                        commit: c.commit, subject: c.subject,
+                        candidates: dumpResult.candidates,
+                        rankedImpact: dumpResult.impacts?.rankedImpact ?? [],
+                        truthFiles: c.files,
+                        ...(bodies !== undefined ? { bodies } : {}),
+                    });
+                }
+                // Same case, same truth, same `topN` the product used — an arm scored against a different
+                // denominator would produce a comparison of definitions rather than of rankers.
+                // One variable: same bonuses, same demotion, same ordering — only the term weight differs.
+                const w = (0, semantic_arm_1.normalisedIdf)(scanned);
+                idfOutcomes.push({
+                    ranked: (0, semantic_arm_1.rankWeighted)(c.subject, scanned, specs, ranked.length || 10, (t) => w.get(t) ?? 1)
+                        .map((h) => h.file),
+                    truthFiles: c.files,
+                    selectedTests: [...result.relevantTests], // the arm changes ranking only
+                    truthTests: c.tests,
+                });
+                // @implements A-SPEC-493 — captured per case for the union∪admit ceiling rows.
+                let semAdmitForCase = [];
+                // @implements A-SPEC-475 — the semantic arm, same cases and truth as everything else.
+                if (opts.semanticArm !== undefined) {
+                    const sem = await semanticCaseRanking(scanned.map((f) => ({ sourcePath: f.sourcePath, symbolNames: f.symbols.map((sym) => sym.qualifiedName) })), c.subject, ranked, ranked.length || 10, opts.semanticArm.embedBatch);
+                    semRerank.push({ ranked: sem.rerank, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests });
+                    semAdmit.push({ ranked: sem.admit, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests });
+                    semAdmitForCase = sem.admit;
+                    // @implements A-SPEC-488 — the gate simulation: cited exactly as the product decides
+                    // it, poverty as uniform-weight coverage by the product's top-1. A gate that stays
+                    // shut scores the product order for that case.
+                    if (opts.semanticArm.gates === true) {
+                        const uncited = (0, localize_1.citationsIn)(c.subject, new Set(specs.map((sp) => sp.id))).cited.length === 0;
+                        const subjTok = new Set((0, localize_1.significantTerms)(c.subject));
+                        const top1 = scanned.find((f) => f.sourcePath === ranked[0]);
+                        const top1Tok = top1 !== undefined ? (0, semantic_arm_1.fileTokens)(top1) : new Set();
+                        const poor25 = (0, union_verify_1.lexPoverty)(subjTok, top1Tok, 0.25);
+                        const poor50 = (0, union_verify_1.lexPoverty)(subjTok, top1Tok, 0.5);
+                        const open = {
+                            'uncited': uncited,
+                            'poor@0.25': poor25,
+                            'poor@0.5': poor50,
+                            'or@0.25': uncited || poor25,
+                            'or@0.5': uncited || poor50,
+                            'admitPoor@0.25': poor25,
+                            'admitPoor@0.5': poor50,
+                            // @implements A-SPEC-492 — starved = poor AND the product's top-1 lexical score
+                            // below a near-zero floor (consumed, not recomputed).
+                            'admitStarved@1': poor25 && (result.candidates[0]?.score ?? 0) < 1,
+                            'admitStarved@5': poor25 && (result.candidates[0]?.score ?? 0) < 5,
+                        };
+                        for (const g of SEM_GATES) {
+                            // @implements A-SPEC-491 — the admit rows REPLACE the pool when their gate opens;
+                            // every other row reranks it. A shut gate always scores the product order.
+                            const action = g.startsWith('admit') ? sem.admit : sem.rerank;
+                            semGateRows.get(g).push({ ranked: open[g] ? action : ranked,
+                                truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests });
+                        }
+                    }
+                }
+                // @implements A-SPEC-467 — the PPR arm, on the PARENT-time graph only (using the live
+                // graph here would leak present-time edges into a point-in-time benchmark, the exact leak
+                // A-SPEC-378 closed for recency). One graph view and one seed set per case; the spread
+                // itself is milliseconds, so every config shares the expensive part.
+                // One parse serves both axes' arms (A-SPEC-467 localization, A-SPEC-468 impact).
+                const view = pprConfigs.length > 0 ? (0, assoc_arm_1.graphViewOf)(graph.dumpCanonical()) : null;
+                if (view !== null) {
+                    const seeds = (0, assoc_arm_1.seedNodes)(c.subject, new Set(specs.map((sp) => sp.id)), view, w);
+                    const topN = ranked.length || 10;
+                    for (const config of pprConfigs) {
+                        const { rerank, admit } = (0, assoc_arm_1.pprCaseRanking)(view, seeds, ranked, topN, config);
+                        const bucket = pprOutcomes.get(config.label);
+                        bucket.rerank.push({ ranked: rerank, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests });
+                        bucket.admit.push({ ranked: admit, truthFiles: c.files, selectedTests: [...result.relevantTests], truthTests: c.tests });
+                    }
+                }
+                const unionList = [...new Set([...ranked, ...impacted])];
+                unionCases.push({ seed: '', expected: c.files, predicted: unionList });
+                // @implements A-SPEC-493 — the ceiling rows: a strict superset of the union prediction.
+                if (opts.semanticArm?.gates === true) {
+                    for (const k of UPA_KS) {
+                        upaCases.get(k).push({ seed: '', expected: c.files,
+                            predicted: [...new Set([...unionList, ...semAdmitForCase.slice(0, k)])] });
+                    }
+                }
+                // @implements A-SPEC-483 — the content class: bodies from the MATERIALIZED parent tree
+                // only. A body that cannot be read is a KEEP (signal absent, not verdict), matching the
+                // S-497 contract; the mention signal is bidirectional (candidate names the head, or the
+                // head names the candidate).
+                if (opts.contentVerify === true && unionList.length > 0) {
+                    const bodyOf = new Map();
+                    for (const f of unionList) {
+                        try {
+                            bodyOf.set(f, fs.readFileSync(path.join(dest, f), 'utf8').toLowerCase());
+                        }
+                        catch {
+                            bodyOf.set(f, null);
+                        }
+                    }
+                    const terms = (0, content_verify_1.topIdfTerms)((0, localize_1.significantTerms)(c.subject), w, 5);
+                    const headFile = unionList[0];
+                    const headSyms = scanned.filter((sf) => sf.sourcePath === headFile)
+                        .flatMap((sf) => sf.symbols.map((sy) => sy.qualifiedName));
+                    const headNames = (0, content_verify_1.mentionNames)(headFile, headSyms);
+                    const headBody = bodyOf.get(headFile) ?? null;
+                    const hitsOf = (f) => {
+                        const b = bodyOf.get(f) ?? null;
+                        return b === null ? null : (0, content_verify_1.bodyHitCount)(b, terms);
+                    };
+                    const mentionOf = (f) => {
+                        const b = bodyOf.get(f) ?? null;
+                        if (b === null)
+                            return null;
+                        if ((0, content_verify_1.mentionsAny)(b, headNames))
+                            return true;
+                        const base = (0, content_verify_1.mentionNames)(f, []);
+                        return headBody !== null && base.length > 0 && (0, content_verify_1.mentionsAny)(headBody, base);
+                    };
+                    const accepts = {
+                        body1: (f) => { const h = hitsOf(f); return h === null ? true : h >= 1; },
+                        body2: (f) => { const h = hitsOf(f); return h === null ? true : h >= 2; },
+                        mention: (f) => { const m = mentionOf(f); return m === null ? true : m; },
+                        bodyOrMention: (f) => {
+                            const h = hitsOf(f), m = mentionOf(f);
+                            if (h === null && m === null)
+                                return true;
+                            return (h ?? 0) >= 1 || m === true;
+                        },
+                        bodyAndMention: (f) => {
+                            const h = hitsOf(f), m = mentionOf(f);
+                            if (h === null && m === null)
+                                return true;
+                            return (h ?? 0) >= 1 && m === true;
+                        },
+                    };
+                    for (const s of CV_SIGNALS) {
+                        for (const g of CV_GUARDS) {
+                            cvCases.get(`${s}@${g}`).push({ seed: '', expected: c.files,
+                                predicted: (0, union_verify_1.verifyEmission)(unionList, accepts[s], g) });
+                        }
+                    }
+                }
+                // @implements A-SPEC-482 — prior and structure together, on the same emitted list.
+                if (opts.anchoredConsensus === true && unionList.length > 0) {
+                    const aidx = (0, coherence_verify_1.buildCoherenceIndex)(view ?? (0, assoc_arm_1.graphViewOf)(graph.dumpCanonical()));
+                    const acDeg = (0, coherence_verify_1.emissionDegree)(aidx, unionList, 'any');
+                    for (const [m, h] of AC_ANCHORS) {
+                        const anchor = (0, coherence_verify_1.coherentAccept)(aidx, new Set(unionList.slice(0, h)), m);
+                        for (const d of AC_DS) {
+                            for (const cb of AC_COMBS) {
+                                acCases.get(`${m}@${h}@${d}@${cb}`).push({ seed: '', expected: c.files,
+                                    predicted: (0, union_verify_1.verifyEmission)(unionList, (0, coherence_verify_1.anchoredConsensusAccept)(anchor, acDeg, d, cb), h) });
+                            }
+                        }
+                    }
+                }
+                // @implements A-SPEC-481 — the emission judges itself: degree and largest-component
+                // verdicts over the same emitted list, no reference point taken from the ranking.
+                if (opts.coherenceRobust === true && unionList.length > 0) {
+                    const ridx = (0, coherence_verify_1.buildCoherenceIndex)(view ?? (0, assoc_arm_1.graphViewOf)(graph.dumpCanonical()));
+                    for (const rel of CR_RELS) {
+                        const deg = (0, coherence_verify_1.emissionDegree)(ridx, unionList, rel);
+                        const cluster = (0, coherence_verify_1.largestCluster)(ridx, unionList, rel);
+                        for (const g of CR_GUARDS) {
+                            for (const d of CR_DS) {
+                                crCases.get(`deg@${rel}@${d}@${g}`).push({ seed: '', expected: c.files,
+                                    predicted: (0, union_verify_1.verifyEmission)(unionList, (f) => (deg.get(f) ?? 0) >= d, g) });
+                            }
+                            crCases.get(`clu@${rel}@0@${g}`).push({ seed: '', expected: c.files,
+                                predicted: (0, union_verify_1.verifyEmission)(unionList, (f) => cluster.has(f), g) });
+                        }
+                    }
+                }
+                // @implements A-SPEC-480 — coherence over the exact emitted list, parent-time graph only.
+                if (opts.unionCoherence === true && unionList.length > 0) {
+                    const cidx = (0, coherence_verify_1.buildCoherenceIndex)(view ?? (0, assoc_arm_1.graphViewOf)(graph.dumpCanonical()));
+                    for (const mode of UC_MODES) {
+                        for (const h of UC_HS) {
+                            const head = new Set(unionList.slice(0, h));
+                            ucCases.get(`${mode}@${h}`).push({ seed: '', expected: c.files,
+                                predicted: (0, union_verify_1.verifyEmission)(unionList, (0, coherence_verify_1.coherentAccept)(cidx, head, mode), h) });
+                        }
+                    }
+                }
+                // @implements A-SPEC-479 — verify the exact list the union scores, in its emitted order.
+                // A candidate the signal cannot see (no doc text, no vector) is KEPT: recall is spent only
+                // where the verdict actually spoke.
+                if (opts.unionVerify !== undefined && unionList.length > 0) {
+                    const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
+                        (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+                    const known = unionList.map((f, i) => ({ text: docTextOf.get(f), i })).filter((x) => x.text !== undefined);
+                    const [qv] = await opts.unionVerify.embedBatch([c.subject], 'query');
+                    const dvs = known.length > 0
+                        ? await opts.unionVerify.embedBatch(known.map((x) => x.text), 'doc') : [];
+                    const vecByFile = new Map(unionList.map((f) => [f, null]));
+                    known.forEach((x, n) => vecByFile.set(unionList[x.i], dvs[n] ?? null));
+                    const subjTokens = new Set((0, localize_1.significantTerms)(c.subject));
+                    const tokByFile = new Map(scanned.map((f) => [f.sourcePath, (0, semantic_arm_1.fileTokens)(f)]));
+                    for (const g of UV_GUARDS) {
+                        for (const tau of UV_SEM_TAUS) {
+                            const acc = (0, union_verify_1.semAcceptor)(qv ?? null, (f) => vecByFile.get(f) ?? null, tau);
+                            uvCases.get(`sem@${tau}@${g}`).push({ seed: '', expected: c.files, predicted: (0, union_verify_1.verifyEmission)(unionList, acc, g) });
+                        }
+                        for (const tau of UV_LEX_TAUS) {
+                            uvCases.get(`lex@${tau}@${g}`).push({
+                                seed: '', expected: c.files,
+                                predicted: (0, union_verify_1.verifyEmission)(unionList, (f) => {
+                                    const tok = tokByFile.get(f);
+                                    return tok === undefined ? true : (0, union_verify_1.lexScore)(subjTokens, tok, w) >= tau;
+                                }, g),
+                            });
+                        }
+                    }
+                }
+                const seed = [...c.files].sort()[0];
+                const expected = c.files.filter((f) => f !== seed);
+                if (expected.length > 0) {
+                    const run = (0, maintenance_analyze_1.analyzeMaintenance)({
+                        request: c.subject, scanned, specs, graph, testAnchors: anchors, history: [],
+                        changedFiles: [seed], changePrior, commitTextBoost,
+                        basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
+                        coverage: { scannedFiles: scanned.length, skippedFiles: [], unsupportedLanguages: [] },
+                    });
+                    // @implements A-SPEC-469 — score the SHIPPED prediction surface (ablation must score
+                    // what ships): the graded top-K, not the ungraded closure the gates keep.
+                    impactCases.push({ seed, expected, predicted: (run.impacts?.rankedImpact ?? []).map((r) => r.file) });
+                    // @implements A-SPEC-470 — the frozen string-property heuristic on the same case.
+                    impactBaselineCases.push({ seed, expected,
+                        predicted: (0, impact_baseline_1.impactBaselinePredict)(seed, scanned.map((f) => f.sourcePath)) });
+                    impactCeilingCases.push({ expected, reachable: reachableFrom(graph, scanned, seed) });
+                    // @implements A-SPEC-468 — the grading arm on the SAME case and the SAME expected set as
+                    // the product's ungraded closure above, so the two share a denominator. Seed nodes are
+                    // identified exactly as reachableFrom identifies them; the seed file cannot predict itself.
+                    if (view !== null) {
+                        const seedNodeIds = scanned.filter((f) => f.sourcePath === seed)
+                            .flatMap((f) => f.symbols.flatMap((sym) => graph.codeNodeIds(sym.qualifiedName)))
+                            .filter((id) => id.endsWith(`@${seed}`));
+                        const impactSeeds = new Map(seedNodeIds.map((id) => [id, 1]));
+                        for (const config of pprConfigs) {
+                            for (const k of PPR_IMPACT_KS) {
+                                const predicted = (0, assoc_arm_1.pprImpactPredict)(view, impactSeeds, seed, k, config);
+                                pprImpactCases.get(`${config.label}@${k}`).push({ seed, expected, predicted });
+                            }
+                        }
+                    }
+                    // @implements A-SPEC-472 — three arms, one oracle (membership in the case's expected
+                    // set, revealed only for emitted files — the loop owns that invariant), one budget.
+                    if (opts.iterativeArms === true) {
+                        const iview = view ?? (0, assoc_arm_1.graphViewOf)(graph.dumpCanonical());
+                        const seedNodeIds3 = scanned.filter((f) => f.sourcePath === seed)
+                            .flatMap((f) => f.symbols.flatMap((sym) => graph.codeNodeIds(sym.qualifiedName)))
+                            .filter((id) => id.endsWith(`@${seed}`));
+                        const staticList = (0, assoc_arm_1.pprImpactRanked)(iview, new Map(seedNodeIds3.map((id) => [id, 1])), new Set([seed]), 20, assoc_arm_1.RANKED_IMPACT_CONFIG)
+                            .map((r) => r.file);
+                        const truthSet = new Set(expected);
+                        for (const arm of ITER_ARMS) {
+                            const rounds = (0, explore_1.exploreIterative)({ view: iview, seedFile: seed, seedNodeIds: seedNodeIds3, issueText: c.subject, idf: w, staticList }, arm, { E: ITER_E, R: ITER_R, verify: (f) => truthSet.has(f) });
+                            // Cumulative trajectory, extended to ITER_R with the last state (fixed denominator
+                            // for the macro mean — an early-terminating case keeps contributing its final state).
+                            let hits = 0, emitted = 0;
+                            const acc = iterAcc.get(arm);
+                            for (let r = 0; r < ITER_R; r++) {
+                                const row = rounds[r];
+                                if (row !== undefined) {
+                                    hits += row.hits.length;
+                                    emitted += row.emitted.length;
+                                }
+                                const slot = acc[r] ?? (acc[r] = { recallSum: 0, precSum: 0, precN: 0, emittedSum: 0, n: 0 });
+                                slot.recallSum += hits / expected.length;
+                                if (emitted > 0) {
+                                    slot.precSum += hits / emitted;
+                                    slot.precN += 1;
+                                }
+                                slot.emittedSum += emitted;
+                                slot.n += 1;
+                            }
+                        }
+                    }
+                    // @implements A-SPEC-471 — one scored list per case (the ADOPTED config), twenty cuts.
+                    if (opts.impactFrontier === true) {
+                        const fview = view ?? (0, assoc_arm_1.graphViewOf)(graph.dumpCanonical());
+                        const seedNodeIds2 = scanned.filter((f) => f.sourcePath === seed)
+                            .flatMap((f) => f.symbols.flatMap((sym) => graph.codeNodeIds(sym.qualifiedName)))
+                            .filter((id) => id.endsWith(`@${seed}`));
+                        const scoredList = (0, assoc_arm_1.pprImpactRanked)(fview, new Map(seedNodeIds2.map((id) => [id, 1])), new Set([seed]), 20, assoc_arm_1.RANKED_IMPACT_CONFIG);
+                        for (const a of FRONTIER_ALPHAS) {
+                            for (const k of FRONTIER_KS) {
+                                frontierCases.get(`${a}@${k}`).push({ seed, expected, predicted: (0, assoc_arm_1.emitByRule)(scoredList, a, k) });
+                            }
+                        }
+                    }
+                }
+                // The lexical axis has a different, weaker denominator: ranking needs no graph path, but a
+                // file absent from the parent-time scan can never be named at all (A-SPEC-317). Conflating
+                // the two would move this axis with the impact axis's connectivity for no stated reason.
+                const scannedPaths = new Set(scanned.map((f) => f.sourcePath));
+                unionCeilingCases.push({ expected: c.files, reachable: c.files.filter((f) => scannedPaths.has(f)) });
+            }
+            finally {
+                graph.close();
+            }
+        }
+        finally {
+            fs.rmSync(dest, { recursive: true, force: true });
+        }
+    }
+    const impact = (0, evaluation_metrics_1.impactMetrics)(impactCases);
+    const impactBaseline = (0, evaluation_metrics_1.impactMetrics)(impactBaselineCases);
+    const union = (0, evaluation_metrics_1.impactMetrics)(unionCases);
+    const impactCeiling = (0, evaluation_metrics_1.ceilingMetrics)(impactCeilingCases);
+    const unionCeiling = (0, evaluation_metrics_1.ceilingMetrics)(unionCeilingCases);
+    return {
+        corpus: path.basename(corpus.root),
+        cases: outcomes.length,
+        unmeasured,
+        casesWithoutSpecs,
+        metrics: (0, evaluation_metrics_1.evaluationMetrics)(outcomes),
+        impact, impactBaseline, union,
+        impactCeiling, unionCeiling,
+        idfArm: (0, evaluation_metrics_1.evaluationMetrics)(idfOutcomes),
+        ...(pprConfigs.length > 0 ? {
+            pprArms: pprConfigs.map((c) => ({
+                label: c.label,
+                rerank: (0, evaluation_metrics_1.evaluationMetrics)(pprOutcomes.get(c.label).rerank),
+                admit: (0, evaluation_metrics_1.evaluationMetrics)(pprOutcomes.get(c.label).admit),
+            })),
+            pprImpact: pprConfigs.flatMap((c) => PPR_IMPACT_KS.map((k) => {
+                const m = (0, evaluation_metrics_1.impactMetrics)(pprImpactCases.get(`${c.label}@${k}`));
+                return { label: c.label, k, recall: m.recall, precision: m.precision };
+            })),
+        } : {}),
+        ...(opts.impactFrontier === true ? {
+            impactFrontier: [...frontierCases.entries()].map(([key, cases]) => {
+                const [a, k] = key.split('@').map(Number);
+                const m = (0, evaluation_metrics_1.impactMetrics)(cases);
+                return { alpha: a, k, recall: m.recall, precision: m.precision };
+            }),
+        } : {}),
+        ...(opts.iterativeArms === true ? {
+            iterative: [...iterAcc.entries()].flatMap(([arm, slots]) => slots.map((sl, i) => ({
+                arm: arm,
+                round: i + 1,
+                recall: sl.n > 0 ? sl.recallSum / sl.n : null,
+                precision: sl.precN > 0 ? sl.precSum / sl.precN : null,
+                emitted: sl.n > 0 ? sl.emittedSum / sl.n : 0,
+            }))),
+        } : {}),
+        ...(opts.semanticArm !== undefined ? {
+            semanticArm: { rerank: (0, evaluation_metrics_1.evaluationMetrics)(semRerank), admit: (0, evaluation_metrics_1.evaluationMetrics)(semAdmit) },
+        } : {}),
+        ...(opts.semanticArm?.gates === true ? {
+            semanticGates: [...semGateRows.entries()].map(([gate, rows]) => ({ gate, metrics: (0, evaluation_metrics_1.evaluationMetrics)(rows) })),
+            unionPlusAdmit: [...upaCases.entries()].map(([k, cases]) => {
+                const m = (0, evaluation_metrics_1.impactMetrics)(cases);
+                return { k, recall: m.recall, precision: m.precision };
+            }),
+        } : {}),
+        ...(opts.unionVerify !== undefined ? {
+            unionVerify: [...uvCases.entries()].map(([key, cases]) => {
+                const [signal, tau, guard] = key.split('@');
+                const m = (0, evaluation_metrics_1.impactMetrics)(cases);
+                return { signal: signal, tau: Number(tau), guard: Number(guard), recall: m.recall, precision: m.precision };
+            }),
+        } : {}),
+        ...(opts.unionCoherence === true ? {
+            unionCoherence: [...ucCases.entries()].map(([key, cases]) => {
+                const [mode, h] = key.split('@');
+                const m = (0, evaluation_metrics_1.impactMetrics)(cases);
+                return { mode: mode, h: Number(h), recall: m.recall, precision: m.precision };
+            }),
+        } : {}),
+        ...(opts.contentVerify === true ? {
+            contentVerify: [...cvCases.entries()].map(([key, cases]) => {
+                const [signal, g] = key.split('@');
+                const m = (0, evaluation_metrics_1.impactMetrics)(cases);
+                return { signal, guard: Number(g), recall: m.recall, precision: m.precision };
+            }),
+        } : {}),
+        ...(opts.anchoredConsensus === true ? {
+            anchoredConsensus: [...acCases.entries()].map(([key, cases]) => {
+                const [m, h, d, cb] = key.split('@');
+                const met = (0, evaluation_metrics_1.impactMetrics)(cases);
+                return { mode: m, h: Number(h), d: Number(d), comb: cb, recall: met.recall, precision: met.precision };
+            }),
+        } : {}),
+        ...(opts.coherenceRobust === true ? {
+            coherenceRobust: [...crCases.entries()].map(([key, cases]) => {
+                const [fam, rel, d, g] = key.split('@');
+                const m = (0, evaluation_metrics_1.impactMetrics)(cases);
+                return {
+                    family: (fam === 'deg' ? 'degree' : 'cluster'),
+                    rel: rel,
+                    d: fam === 'deg' ? Number(d) : null,
+                    guard: Number(g), recall: m.recall, precision: m.precision,
+                };
+            }),
+        } : {}),
+        impactAchievement: (0, evaluation_metrics_1.achievementRate)(impact.recall, impactCeiling.ceiling),
+        unionAchievement: (0, evaluation_metrics_1.achievementRate)(union.recall, unionCeiling.ceiling),
+        elapsedMs: Date.now() - started,
+    };
+}
+/**
+ * Which files the impact walk could POSSIBLY have reached from the seed — the ceiling's numerator.
+ *
+ * CODE-to-CODE edges only. The permissive walk reaches a second file through the SPEC node they both
+ * anchor, which is a path no impact algorithm should follow; counting it would raise the denominator
+ * and make the algorithm look worse for a reason that is not about the algorithm (A-SPEC-307).
+ */
+function reachableFrom(graph, scanned, seed) {
+    const adj = new Map();
+    const link = (a, b) => {
+        (adj.get(a) ?? adj.set(a, []).get(a)).push(b);
+        (adj.get(b) ?? adj.set(b, []).get(b)).push(a);
+    };
+    for (const line of graph.dumpCanonical().split('\n')) {
+        const cols = line.split('\t');
+        if (cols[0] !== 'E' || !cols[1]?.startsWith('CODE:') || !cols[2]?.startsWith('CODE:'))
+            continue;
+        link(cols[1], cols[2]);
+    }
+    const seen = new Set(scanned.filter((f) => f.sourcePath === seed)
+        .flatMap((f) => f.symbols.flatMap((sym) => graph.codeNodeIds(sym.qualifiedName)))
+        .filter((id) => id.endsWith(`@${seed}`)));
+    let wave = [...seen];
+    while (wave.length > 0) {
+        const next = [];
+        for (const id of wave)
+            for (const n of adj.get(id) ?? []) {
+                if (seen.has(n))
+                    continue;
+                seen.add(n);
+                next.push(n);
+            }
+        wave = next;
+    }
+    return [...seen].filter((id) => id.startsWith('CODE:') && id.includes('@'))
+        .map((id) => id.slice(id.lastIndexOf('@') + 1));
+}
+/**
+ * @implements A-SPEC-475
+ * One case of the semantic arm, pure given an embedder: documents follow the S-491 convention
+ * (`sourcePath + qualified symbol names`, 2000 chars) so numbers stay comparable across the
+ * traceability and localization experiments; the query is the commit subject as-is. rerank reuses
+ * `rerankPool` — the pool-stays-fixed invariant is shared code, not a re-promise.
+ */
+async function semanticCaseRanking(files, subject, pool, topN, embedBatch) {
+    const docTexts = files.map((f) => (f.sourcePath + ' ' + f.symbolNames.join(' ')).slice(0, 2000));
+    const dv = await embedBatch(docTexts, 'doc');
+    const [qv] = await embedBatch([subject], 'query');
+    const sim = new Map();
+    files.forEach((f, i) => sim.set(f.sourcePath, (0, dense_retrieval_1.cosine)(qv, dv[i])));
+    const admit = [...sim.entries()]
+        .sort((a, b) => (b[1] - a[1]) || (a[0] < b[0] ? -1 : 1))
+        .slice(0, topN)
+        .map(([f]) => f);
+    return { rerank: (0, assoc_arm_1.rerankPool)(pool, sim), admit, docTexts };
+}