@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/mcp/maintenance-analyze.js

@@ -0,0 +1,994 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRIMARY_TIER_WIDTH = exports.EVIDENCE_DIMENSIONS = exports.MAINTENANCE_ANALYSIS_EXTRACTOR = exports.MAINTENANCE_ANALYSIS_SCHEMA = void 0;
+exports.unquoteGitPath = unquoteGitPath;
+exports.analyzeMaintenance = analyzeMaintenance;
+// @implements A-SPEC-295
+// @implements A-SPEC-294
+// @implements A-SPEC-293
+// @implements A-SPEC-292
+// @implements A-SPEC-290
+// @implements A-SPEC-289
+// @implements A-SPEC-288
+// @implements A-SPEC-286
+// @implements A-SPEC-285
+// @implements A-SPEC-279
+// @implements A-SPEC-274
+// @implements A-SPEC-271
+// @implements A-SPEC-269
+// @implements A-SPEC-267
+const crypto_1 = require("crypto");
+const localize_1 = require("../rtm/localize");
+const dense_retrieval_1 = require("../review/dense-retrieval");
+const test_scope_1 = require("../rtm/test-scope");
+const scope_1 = require("../review/scope");
+// @implements A-SPEC-469 — the SAME code path the S-484 measurement ran; identity is the reason
+// the measured numbers transfer to the shipped surface.
+const assoc_arm_1 = require("../assoc/assoc-arm");
+const acceptance_quality_1 = require("../spec/acceptance-quality");
+const taint_1 = require("../rtm/taint");
+const test_evidence_1 = require("../review/test-evidence");
+const language_capability_1 = require("../cpg/language-capability");
+// @implements A-SPEC-409 — the SHAPE gained a field (`rerankPool`), so a consumer can detect it.
+// @implements A-SPEC-405 A-SPEC-407 — the EXTRACTOR changed too: the same request now returns a
+// differently ordered candidate list (keep-head rank fusion, then the graph-hop list), so two
+// artifacts are only comparable when this string matches.
+exports.MAINTENANCE_ANALYSIS_SCHEMA = 'maintenance-analysis/1.13';
+exports.MAINTENANCE_ANALYSIS_EXTRACTOR = 'holmes-graph-fusion/1.13';
+/**
+ * The evidence kinds an ablation arm can actually produce. Completeness is measured by asking each
+ * arm which of these it FILLED — the first cut hardcoded 1 / 2 / 2+n, so "enhanced beats current"
+ * was an identity of the code rather than a result of a measurement.
+ */
+exports.EVIDENCE_DIMENSIONS = [
+    'candidates', 'specs', 'directImpact', 'transitiveImpact', 'tests', 'history', 'versionedBasis',
+];
+/**
+ * @implements A-SPEC-271
+ * How many ranked candidates form the `primary` tier. A fixed rank cut, not a score threshold:
+ * measured over the 12-commit replay corpus at matched set sizes, a `score >= ratio * top` cut was
+ * never better than the plain rank cut on both axes at once (top-3 beat ratio>=0.5 on recall AND
+ * precision), and tuning a threshold on 12 samples would be fitting noise.
+ */
+exports.PRIMARY_TIER_WIDTH = 3;
+function sortedUnique(values) {
+    return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+function codeQualifiedName(codeId) {
+    const body = codeId.startsWith('CODE:') ? codeId.slice(5) : codeId;
+    const delimiter = body.indexOf('@');
+    return delimiter === -1 ? body : body.slice(0, delimiter);
+}
+/**
+ * Recall/precision against a ground-truth set. An ABSENT or EMPTY truth set yields `null`, never 0:
+ * "we did not measure" and "we measured zero" are different claims, and collapsing them would let an
+ * unmeasured arm look like a failed one (or, worse, let a vacuous 1.0 stand as a score).
+ */
+function scoreAgainst(predicted, truth) {
+    if (!truth || truth.length === 0)
+        return { recall: null, precision: null };
+    const expected = new Set(truth);
+    const actual = new Set(predicted);
+    let hits = 0;
+    for (const value of actual)
+        if (expected.has(value))
+            hits++;
+    return { recall: hits / expected.size, precision: actual.size === 0 ? 0 : hits / actual.size };
+}
+function arm(files, symbols, tests, dimensions, truth, primary, impacted, importedBy) {
+    const localization = scoreAgainst(files, truth?.files);
+    const impact = scoreAgainst(symbols, truth?.symbols);
+    const test = scoreAgainst(tests, truth?.tests);
+    const filled = exports.EVIDENCE_DIMENSIONS.filter((dimension) => dimensions.includes(dimension));
+    return {
+        localizationCandidates: new Set(files).size,
+        localizationRecall: localization.recall,
+        localizationPrecision: localization.precision,
+        impactRecall: impact.recall,
+        impactPrecision: impact.precision,
+        testRecall: test.recall,
+        testPrecision: test.precision,
+        evidenceDimensions: [...filled],
+        evidenceCompleteness: filled.length / exports.EVIDENCE_DIMENSIONS.length,
+        // An arm without tiers has no primary claim to score — null, not a borrowed flat number.
+        primaryRecall: primary ? scoreAgainst(primary, truth?.files).recall : null,
+        primaryPrecision: primary ? scoreAgainst(primary, truth?.files).precision : null,
+        impactedFilesRecall: impacted ? scoreAgainst(impacted, truth?.files).recall : null,
+        impactedFilesPrecision: impacted ? scoreAgainst(impacted, truth?.files).precision : null,
+        importedByRecall: importedBy ? scoreAgainst(importedBy, truth?.files).recall : null,
+        importedByPrecision: importedBy ? scoreAgainst(importedBy, truth?.files).precision : null,
+    };
+}
+/**
+ * Decode a pathname as git prints it in `--name-only`/`--name-status` output. With the default
+ * `core.quotepath=true`, any non-ASCII or control byte makes git wrap the name in double quotes and
+ * emit C-style escapes (`"src/\354\227\260.ts"`). Comparing that raw form against the scanner's
+ * real relative path never matches, which silently emptied the historical rationale while the
+ * provenance still claimed the history was `available`.
+ */
+function unquoteGitPath(line) {
+    if (line.length < 2 || !line.startsWith('"') || !line.endsWith('"'))
+        return line;
+    const body = line.slice(1, -1);
+    const bytes = [];
+    for (let i = 0; i < body.length; i++) {
+        if (body[i] !== '\\') {
+            bytes.push(...Buffer.from(body[i], 'utf8'));
+            continue;
+        }
+        const next = body[++i];
+        if (next === undefined)
+            break;
+        const simple = { a: 7, b: 8, f: 12, n: 10, r: 13, t: 9, v: 11, '\\': 92, '"': 34 };
+        if (next in simple) {
+            bytes.push(simple[next]);
+            continue;
+        }
+        if (next >= '0' && next <= '7') {
+            const octal = next + (body[i + 1] ?? '') + (body[i + 2] ?? '');
+            const digits = octal.match(/^[0-7]{1,3}/)[0];
+            i += digits.length - 1;
+            bytes.push(parseInt(digits, 8));
+            continue;
+        }
+        bytes.push(...Buffer.from(next, 'utf8'));
+    }
+    return Buffer.from(bytes).toString('utf8');
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * Fuse lexical localization, RTM ancestry, call-graph blast radius, test anchors, and history into a
+ * single immutable evidence contract. This core intentionally performs no I/O, so handlers can
+ * reproduce and compare an analysis from the exact same captured inputs.
+ */
+function analyzeMaintenance(input) {
+    const scanned = [...input.scanned];
+    const specs = [...input.specs];
+    // @implements A-SPEC-378 — a wide pool so the re-rank has something to promote; the cut to ten
+    // happens after the prior is applied.
+    const LOCALIZATION_TOP_N = 10;
+    // @implements A-SPEC-388 — swept over 0.5/1/2/4 on the clean slice; 2 was the smallest value at
+    // the plateau on both corpora, and a larger one bought nothing.
+    const COMMIT_TEXT_WEIGHT = 2;
+    // @implements A-SPEC-409 A-SPEC-411 A-SPEC-440 — the narrow path asked for exactly ten, which left
+    // no eleventh to hand the caller. Widened to sixty, which is `LOCALIZATION_TOP_N + RERANK_POOL_N`:
+    // the window can only be as wide as the list it is cut from, and a narrow-path caller was silently
+    // getting a shorter pool than a caller who supplied history. The first ten are the same ten in the
+    // same order — this is one ranked list read further down.
+    const localization = (0, localize_1.localizeIssue)(input.request, scanned, specs, input.changePrior === undefined && input.commitTextBoost === undefined ? LOCALIZATION_TOP_N * 6 : 500);
+    // @implements A-SPEC-378
+    // Re-ranked over a WIDE pool, then cut to ten. Re-ranking the top ten alone would leave the gain
+    // unrealised: the files recency promotes are usually ranked 11th to 50th lexically, which is
+    // exactly why the lexical layer misses them.
+    const prior = input.changePrior;
+    const boost = input.commitTextBoost;
+    const hasPrior = prior !== undefined && Object.keys(prior).length > 0;
+    const hasBoost = boost !== undefined && Object.keys(boost).length > 0;
+    // @implements A-SPEC-388
+    // Files the commit prose names but the lexical layer never scored have to be able to ENTER, or the
+    // fusion can only reorder what lexical already found — and reaching what it missed is where the
+    // measured gain came from (Top-10 recall 0.393 -> 0.601 on the second corpus).
+    const seeded = hasBoost
+        ? [...localization.hits, ...Object.keys(boost)
+                .filter((file) => !localization.hits.some((h) => h.file === file))
+                .map((file) => ({ file, score: 0, matchedSymbols: [], viaSpecs: [], why: ['reached through commit history'] }))]
+        : localization.hits;
+    const reranked = !hasPrior && !hasBoost
+        ? localization.hits
+        : [...seeded]
+            .map((hit) => ({
+            ...hit,
+            score: (hit.score * (hasPrior ? (prior[hit.file] ?? 1) : 1))
+                // @implements A-SPEC-431
+                // Scaling this by the CASE (median positive lexical score) instead of the file's own
+                // score was implemented, measured on all three corpora, and reverted: Top-5 recall fell
+                // 0.509 -> 0.476 here and 0.528 -> 0.494 on the second corpus, with pool coverage
+                // unchanged everywhere. The multiplication looks wrong — it lets a large file grow by
+                // the product of two signals, which is how `config/config.ts` reached 135.43 — but it is
+                // doing work: prose reinforcing a file that ALREADY has lexical evidence ranks better
+                // than prose spread evenly. Kept, with the cost named rather than defended.
+                + (hasBoost ? COMMIT_TEXT_WEIGHT * (boost[hit.file] ?? 0) * Math.max(1, hit.score) : 0),
+        }))
+            .sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+    // @implements A-SPEC-405
+    // S-405 decomposed the recall loss measured in S-404: on the eight blind cases 18 of 18 truth
+    // files were already in this pool and 7 sat at ranks 12-93, so widening retrieval could not have
+    // helped — only the ordering could. Twelve of the eighteen scored ZERO lexically; they were
+    // reached through commit prose alone, and the product formula above multiplies a [0,1] boost
+    // against an unbounded lexical score, which leaves them permanently under anything the lexical
+    // layer did score.
+    //
+    // Rank fusion is scale-free and fixes exactly that. Measured on the 30-case clean slice of both
+    // corpora, plain fusion also COST Top-1 (jarvis 0.533 -> 0.367) because it discards the margin by
+    // which a strong lexical winner won, and no weighting recovered it (best 0.433 across w=2/3/4/6).
+    // So the score-ranked head is kept verbatim and only the tail is fused: Top-1 is preserved by
+    // construction rather than by luck.
+    //   holmes  Top-5 recall 0.382 -> 0.493, Top-10 0.604 -> 0.633, Top-10 precision 0.117 -> 0.127
+    //   jarvis  Top-5 recall 0.459 -> 0.488, Top-10 0.612 -> 0.612, Top-10 precision 0.145 -> 0.135
+    // The jarvis precision dip is real and is recorded rather than smoothed over.
+    const RRF_K = 60;
+    const fuseTail = () => {
+        if (!hasPrior && !hasBoost)
+            return reranked;
+        const byFile = new Map(seeded.map((h) => [h.file, h]));
+        const desc = (pick) => [...byFile.keys()].filter((f) => pick(f) > 0)
+            .sort((a, b) => pick(b) - pick(a) || a.localeCompare(b));
+        // @implements A-SPEC-407
+        // The knowledge graph as a ranking list. S-406 measured that 9 of the 12 answers the lexical
+        // layer scored at zero sit one hop from a lexically strong file (8 by call edge, 1 by shared
+        // spec) — the graph held them all along and nothing consulted it.
+        //
+        // It both reorders and admits, and the distinction matters enough to state plainly: a file the
+        // hop reaches enters the fusion even when no other layer scored it. The first implementation
+        // restricted it to files that were already candidates, which is NOT what the arm measured, and
+        // it reproduced none of the gain. What keeps this from repeating the rejected retrieval attempts
+        // is not a rule against admission but the seed count.
+        //
+        // FIVE seeds, measured rather than chosen: at 20 both corpora get worse (holmes Top-5 recall
+        // 0.554 -> 0.482, jarvis 0.517 -> 0.506). A wide seed set is what turned this axis into noise
+        // before, and the narrowness is the mechanism, not a tuning detail.
+        const HOP_SEEDS = 5;
+        // @implements A-SPEC-407
+        // Query-conditioned, exactly as spec admission is (A-SPEC-399), and for a measured reason. On
+        // the newest-60 slice of this repository, where 88.3% of requests name their spec outright, the
+        // hop list made things WORSE across the board (union precision 0.172 -> 0.134). When the author
+        // has already said which spec this is, the RTM answers exactly and a graph fan-out can only
+        // dilute that answer. The gain measured on the clean slice came from requests with no citation
+        // at all — which is what a real bug report looks like — so that is where the hop is consulted.
+        const cited = (0, localize_1.citationsIn)(input.request, new Set(specs.map((sp) => sp.id))).cited;
+        const hopList = () => {
+            const byPath = new Map(scanned.map((f) => [f.sourcePath, f]));
+            const touched = new Map();
+            const fileOfNode = (nodeId) => {
+                const at = nodeId.lastIndexOf('@');
+                return at < 0 ? null : nodeId.slice(at + 1);
+            };
+            for (const seed of desc((f) => byFile.get(f).score).slice(0, HOP_SEEDS)) {
+                const file = byPath.get(seed);
+                if (file === undefined)
+                    continue;
+                const reached = new Set();
+                for (const sym of file.symbols) {
+                    for (const nodeId of input.graph.codeNodeIds(sym.qualifiedName)) {
+                        for (const n of [...input.graph.callees(nodeId), ...input.graph.callersOf(nodeId)]) {
+                            const f = fileOfNode(n);
+                            if (f !== null)
+                                reached.add(f);
+                        }
+                    }
+                }
+                for (const importer of input.graph.importersOf(seed))
+                    reached.add(String(importer).replace(/^FILE:/, ''));
+                for (const n of input.graph.neighborsWithRel(`FILE:${seed}`)) {
+                    if (n.rel === 'imports')
+                        reached.add(n.id.replace(/^FILE:/, ''));
+                }
+                for (const f of reached) {
+                    if (f !== seed && byPath.has(f))
+                        touched.set(f, (touched.get(f) ?? 0) + 1);
+                }
+            }
+            return [...touched.entries()]
+                .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+                .map(([file]) => file);
+        };
+        const hops = cited.length > 0 ? [] : hopList();
+        for (const file of hops) {
+            if (!byFile.has(file)) {
+                byFile.set(file, { file, score: 0, matchedSymbols: [], viaSpecs: [], why: ['reached through the knowledge graph'] });
+            }
+        }
+        ;
+        const lists = [
+            desc((f) => byFile.get(f).score),
+            hasBoost ? desc((f) => boost[f] ?? 0) : [],
+            hasPrior ? desc((f) => (prior[f] ?? 1) - 1) : [],
+            cited.length > 0 ? [] : hops,
+        ];
+        const fused = new Map();
+        for (const list of lists) {
+            list.forEach((file, i) => fused.set(file, (fused.get(file) ?? 0) + 1 / (RRF_K + i + 1)));
+        }
+        const head = reranked[0];
+        if (head === undefined)
+            return reranked;
+        const tail = [...fused.entries()]
+            .filter(([file]) => file !== head.file)
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .filter(([file]) => byFile.has(file))
+            .map(([file]) => byFile.get(file));
+        return [head, ...tail];
+    };
+    const ordered = fuseTail();
+    // @implements A-SPEC-411
+    // Widened from ten to thirty, so the caller sees forty rather than twenty. S-410 left exactly one
+    // axis behind a person with grep — Top-10 recall 0.764 to 0.821 — and decomposing that gap over
+    // all sixteen cases found it to be FOUR truth files: one I saw and skipped, one the pool never
+    // held, and TWO at ranks 33 and 34, below the width the caller was given.
+    //
+    // The width curve on those same sixteen: 0.651 at ten, 0.829 at twenty, 0.829 at thirty (flat, so
+    // thirty buys nothing), 0.885 at forty, flat thereafter. Forty is the next step, and 0.885 is
+    // above the 0.821 the human method actually reached.
+    //
+    // The cost is real and is not paid by this repository: forty annotated items occupy the CALLER's
+    // context. What it buys is two truth files in sixteen cases, and only if the caller reranks well.
+    // @implements A-SPEC-440
+    // Fifty, so the caller sees sixty. A-SPEC-411 set this from a curve over sixteen cases and landed
+    // on forty; with a third corpus and the clean slices re-measured, sixty is where the gain actually
+    // arrives. Truth inside the exposed window, measured through this path:
+    //
+    //   width 40   holmes 48/65   jarvis 52/70   gemini 14/19
+    //   width 60   holmes 49/65   jarvis 59/70   gemini 14/19
+    //   width 80   holmes 50/65   jarvis 59/70   gemini 14/19
+    //
+    // Jarvis's whole gain is in by sixty; eighty buys one more file on this repository for double the
+    // caller's context, so sixty is the knee rather than the maximum. No corpus is worse at sixty than
+    // at forty — the first width or signal change in this line of work that clears A-SPEC-425's bar
+    // instead of trading one corpus against another.
+    //
+    // Top-5 and Top-10 recall are identical at all three widths: `candidates` is untouched, and the
+    // pinned floors read that field.
+    const RERANK_POOL_N = 50;
+    // @implements A-SPEC-486 — the S-502/503 calibration point for gemini cosines. Display only:
+    // nothing in this module compares against it to drop or reorder anything.
+    const SEM_VERIFY_TAU = 0.65;
+    const shape = (hit) => ({
+        file: hit.file,
+        score: hit.score,
+        symbols: sortedUnique(hit.matchedSymbols),
+        evidence: hit.why,
+    });
+    // @implements A-SPEC-428
+    // The fusion can delete a correct answer outright. Measured on a third party's repository,
+    // leak-free at the parent commit: `localizeIssue` ranked `packages/core/src/tools/ask-user.ts`
+    // FIRST for "properly format markdown in the AskUser tool", and the forty candidates this function
+    // exposed did not contain it. Over eight blind cases, seven answers were in the lexical top ten
+    // and FIVE of those were absent from the exposed forty — ranks 1, 2, 4, 5 and 8.
+    //
+    // A-SPEC-405's kept head does not cover this: it preserves the head of the score ordering, and
+    // that score has already been multiplied by change-recency and added to commit-prose boost, so
+    // the file the lexical layer was surest about is not the file that survives.
+    //
+    // The guarantee is on the WINDOW, not the ranking. `candidates` keeps exactly the ten it had —
+    // the pinned replay floors read that field and are unchanged by construction — and the reserved
+    // slots come out of the pool, which is material for the caller rather than a verdict.
+    const LEXICAL_GUARANTEE = 10;
+    const exposedTail = ordered.slice(LOCALIZATION_TOP_N);
+    const inCandidates = new Set(ordered.slice(0, LOCALIZATION_TOP_N).map((h) => h.file));
+    const wouldShow = new Set(exposedTail.slice(0, RERANK_POOL_N).map((h) => h.file));
+    const rescued = localization.hits.slice(0, LEXICAL_GUARANTEE)
+        .filter((h) => !inCandidates.has(h.file) && !wouldShow.has(h.file))
+        .map((h) => exposedTail.find((o) => o.file === h.file))
+        .filter((h) => h !== undefined);
+    const rescuedFiles = new Set(rescued.map((h) => h.file));
+    const rerankPool = [...rescued, ...exposedTail.filter((h) => !rescuedFiles.has(h.file))]
+        .slice(0, RERANK_POOL_N).map(shape);
+    const candidates = ordered.slice(0, LOCALIZATION_TOP_N).map((hit) => ({
+        file: hit.file,
+        score: hit.score,
+        symbols: sortedUnique(hit.matchedSymbols),
+        evidence: [...hit.why],
+    }));
+    // @implements A-SPEC-478 — the uncited semantic head rerank, exactly the arm S-495 measured:
+    // same math (cosine over cached doc vectors, pool FIXED), same gate (the request cited no
+    // spec). The gate is load-bearing both ways — uncited corpora gained +26%/+93% at the head,
+    // and the citation-rich corpus LOST 61% when reranked, so a citation anywhere disables this.
+    // Only candidates with a CACHED vector move (stable order otherwise); any failure is a no-op.
+    {
+        const sem = input.semantic;
+        const citedForSem = (0, localize_1.citationsIn)(input.request, new Set(specs.map((sp) => sp.id))).cited;
+        if (sem !== undefined && sem.queryVector !== null && citedForSem.length === 0 && candidates.length > 1) {
+            const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
+                (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+            const sim = new Map();
+            let covered = 0;
+            for (const c of candidates) {
+                const dt = docTextOf.get(c.file);
+                const dv = dt !== undefined ? sem.cachedDocVector(dt) : null;
+                if (dv !== null) {
+                    sim.set(c.file, (0, dense_retrieval_1.cosine)(sem.queryVector, dv));
+                    covered++;
+                }
+            }
+            if (covered > 0) {
+                candidates.sort((a, b) => (sim.get(b.file) ?? -Infinity) === (sim.get(a.file) ?? -Infinity)
+                    ? 0 : ((sim.get(b.file) ?? -Infinity) - (sim.get(a.file) ?? -Infinity)));
+                for (const c of candidates) {
+                    if (sim.has(c.file))
+                        c.evidence.push(`semantic-rerank(${sem.label}, coverage ${covered}/${candidates.length})`);
+                }
+            }
+        }
+    }
+    // @implements A-SPEC-486 — sem-verify EVIDENCE, never a filter. The τ0.65 precision multiple
+    // (~×1.7) replicated in three independent windows (S-502/503), but its recall cost is
+    // window-dependent, so the harness attaches the verdict and the CONSUMER selects. Cloud tier
+    // only: the threshold is a gemini-cosine calibration; local bge-m3 cosines are quasi-binary
+    // (S-497) and a grade on them would mislead. Sets, orders and scores never move here.
+    {
+        const sem = input.semantic;
+        if (sem !== undefined && sem.queryVector !== null && sem.label.startsWith('cloud:')) {
+            const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
+                (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+            for (const c of candidates) {
+                const dt = docTextOf.get(c.file);
+                const dv = dt !== undefined ? sem.cachedDocVector(dt) : null;
+                if (dv === null)
+                    continue;
+                const cos = (0, dense_retrieval_1.cosine)(sem.queryVector, dv);
+                c.evidence.push(`sem-verify(${sem.label}, cos=${cos.toFixed(2)}, τ${SEM_VERIFY_TAU} ${cos >= SEM_VERIFY_TAU ? 'pass' : 'fail'})`);
+            }
+        }
+    }
+    // @implements A-SPEC-307
+    // Impact must start from what CHANGED, not only from what the request text happened to match.
+    // Until this slice `changedFiles` fed the architecture check alone, so asking "what does changing
+    // this file affect" was answered from the request instead of from the change. Measured consequence
+    // (A-SPEC-306): the walk reached 11% of what the graph could reach. Additive on purpose — callers
+    // that pass a request and no changed files keep the previous behaviour exactly.
+    const changedSymbols = input.changedFiles === undefined
+        ? []
+        : scanned.filter((f) => input.changedFiles.includes(f.sourcePath))
+            .flatMap((f) => f.symbols.map((sym) => sym.qualifiedName));
+    // A file you edited is not unaffected by your edit, so these are direct impact and not merely a
+    // traversal starting point.
+    const direct = sortedUnique([...candidates.flatMap((candidate) => candidate.symbols), ...changedSymbols]);
+    const transitiveIds = new Set();
+    const maxCallDepth = 3;
+    const hubInDegree = 12;
+    const stoppedAt = [];
+    const seeds = direct.flatMap((qualifiedName) => input.graph.codeNodeIds(qualifiedName));
+    const seen = new Set(seeds);
+    const candidateSpecs = new Set(localization.matchedSpecs);
+    for (const qualifiedName of direct) {
+        for (const id of input.graph.codeNodeIds(qualifiedName)) {
+            for (const specId of input.graph.specsOf(id))
+                candidateSpecs.add(specId.replace(/^SPEC:/, ''));
+        }
+    }
+    // Snapshot of what a graph WITHOUT caller-closure could reach. The "current" ablation arm is
+    // computed from this, not from the enhanced result, so the comparison is not self-referential.
+    const directSpecIds = sortedUnique(candidateSpecs);
+    let frontier = seeds;
+    for (let depth = 1; depth <= maxCallDepth && frontier.length > 0; depth++) {
+        const next = [];
+        for (const id of frontier) {
+            const inDegree = input.graph.callerCount(id);
+            if (depth > 1 && inDegree > hubInDegree) {
+                stoppedAt.push({ id, reason: 'hub', inDegree });
+                continue;
+            }
+            // @implements A-SPEC-309
+            // Still UPSTREAM only, and now for a measured reason rather than an oversight. Adding the
+            // downstream half (Goal Phase 5 names it, and `impactNeighborsOf` implements it) was tried on
+            // the 36-case corpus:
+            //
+            //   recall     0.093 -> 0.199   (2.1x better)
+            //   precision  0.064 -> 0.0093  (6.8x worse — one predicted file in 107 is right)
+            //   depth stops   39 -> 3646, hub stops 1 -> 110
+            //
+            // Direction IS the lever — recall more than doubled where seeds, ground truth and bounds had
+            // each moved nothing. But operating principle 12 puts precision first, and a set where 1 in
+            // 107 is right cannot drive test scope. Reverted as a trade, not as a failure: the next
+            // attempt has to pair the direction with a cost control, and `expectedBehindStops` rising from
+            // 3 to 50 says the bounds finally matter once the walk goes both ways.
+            // @implements A-SPEC-313
+            // Upstream only — and now judged on the ruler that measures the PRODUCT, not a part of it.
+            //
+            // A-SPEC-309..311 rejected downstream on impact-only precision. A-SPEC-312 showed that number
+            // describes a component: what the caller receives is candidates UNION impacts. So the best
+            // downstream variant (one hop, utilities damped) was re-measured on the union:
+            //
+            //                        union recall   union precision   impact-only truths
+            //   upstream only        0.874          0.155             26
+            //   + damped one hop     0.894          0.0790            30
+            //
+            // Four more true files out of 155, for HALF the product's precision. The criterion was written
+            // into REQ-313 before the run, and it says no. The earlier verdicts were reached with the
+            // wrong ruler and still landed on the right answer — worth knowing, and worth having checked
+            // rather than assumed.
+            for (const caller of input.graph.impactSourcesOf(id)) {
+                if (seen.has(caller))
+                    continue;
+                seen.add(caller);
+                transitiveIds.add(caller);
+                next.push(caller);
+            }
+        }
+        frontier = next;
+    }
+    for (const id of frontier)
+        stoppedAt.push({ id, reason: 'depth' });
+    const transitive = sortedUnique([...transitiveIds].map(codeQualifiedName).filter((qn) => !direct.includes(qn)));
+    for (const qualifiedName of transitive) {
+        for (const id of input.graph.codeNodeIds(qualifiedName)) {
+            for (const specId of input.graph.specsOf(id))
+                candidateSpecs.add(specId.replace(/^SPEC:/, ''));
+        }
+    }
+    const specIds = sortedUnique(candidateSpecs);
+    const fileOfSymbol = new Map();
+    for (const file of scanned) {
+        for (const symbol of file.symbols) {
+            if (!fileOfSymbol.has(symbol.qualifiedName))
+                fileOfSymbol.set(symbol.qualifiedName, file.sourcePath);
+        }
+    }
+    const rankedFiles = candidates.map((candidate) => candidate.file);
+    const primaryTier = rankedFiles.slice(0, exports.PRIMARY_TIER_WIDTH);
+    const secondaryTier = rankedFiles.slice(exports.PRIMARY_TIER_WIDTH);
+    const reachableTier = sortedUnique(transitive
+        .map((qualifiedName) => fileOfSymbol.get(qualifiedName))
+        .filter((file) => !!file && !rankedFiles.includes(file)));
+    // @implements A-SPEC-469 — the graded surface, seeded like the S-484 measurement was: from the
+    // CHANGED files' symbols when a change is named (the impact question), from every direct symbol
+    // otherwise (the request-only question). The whole changed set is excluded from the prediction.
+    const rankedImpactSeedSymbols = (input.changedFiles?.length ?? 0) > 0 ? changedSymbols : direct;
+    const rankedImpactSeeds = new Map(rankedImpactSeedSymbols
+        .flatMap((qualifiedName) => input.graph.codeNodeIds(qualifiedName))
+        .map((id) => [id, 1]));
+    const rankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(input.graph.dumpCanonical()), rankedImpactSeeds, new Set(input.changedFiles ?? []), assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
+    // @implements A-SPEC-486 — the same additive verdict on the graded impact surface: a cached
+    // cosine per row, no row added or removed, score untouched.
+    {
+        const sem = input.semantic;
+        if (sem !== undefined && sem.queryVector !== null && sem.label.startsWith('cloud:')) {
+            const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
+                (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+            for (const row of rankedImpact) {
+                const dt = docTextOf.get(row.file);
+                const dv = dt !== undefined ? sem.cachedDocVector(dt) : null;
+                if (dv !== null)
+                    row.semCos = Math.round((0, dense_retrieval_1.cosine)(sem.queryVector, dv) * 1e4) / 1e4;
+            }
+        }
+    }
+    // @implements A-SPEC-494 — the alternates: cached-lookup cosines over every scanned file the
+    // emission missed, top-3. Pure addition — no set, order or score above moves because of this.
+    let semanticAlternates;
+    {
+        const sem = input.semantic;
+        if (sem !== undefined && sem.queryVector !== null && sem.label.startsWith('cloud:')) {
+            const emitted = new Set([...candidates.map((c) => c.file), ...rankedImpact.map((r) => r.file)]);
+            const scoredAlt = [];
+            for (const f of scanned) {
+                if (emitted.has(f.sourcePath))
+                    continue;
+                const dt = (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000);
+                const dv = sem.cachedDocVector(dt);
+                if (dv === null)
+                    continue;
+                scoredAlt.push({ file: f.sourcePath, cos: Math.round((0, dense_retrieval_1.cosine)(sem.queryVector, dv) * 1e4) / 1e4 });
+            }
+            scoredAlt.sort((a, b) => b.cos - a.cos);
+            if (scoredAlt.length > 0)
+                semanticAlternates = scoredAlt.slice(0, 3);
+        }
+    }
+    // @implements A-SPEC-274 — the prediction is the RANKED set. The closure's files are reported on
+    // the impact axis instead of being folded in here.
+    const localizedFiles = sortedUnique(rankedFiles);
+    // @implements A-SPEC-289 — who depends on the predicted files, via resolved FILE imports.
+    const importedByFiles = sortedUnique(localizedFiles.flatMap((file) => input.graph.importersOf(file)).filter((file) => !localizedFiles.includes(file)));
+    // @implements A-SPEC-290 — observation is only evidence about the tree it was taken on.
+    const runtimeRecord = input.runtimeEvidence;
+    const runtimeStatus = !runtimeRecord ? 'absent' : (0, test_evidence_1.isFresh)(runtimeRecord, input.basis.head) ? 'fresh' : 'stale';
+    // @implements A-SPEC-285 — what the languages in THIS scan could not contribute.
+    const languageCoverage = (0, language_capability_1.capabilityGapsFor)(scanned.map((f) => f.sourcePath));
+    // @implements A-SPEC-279 — security axis. Reachability, NOT a vulnerability proof: the limits ride
+    // along so nobody reads "reaches" as "exploitable". Filtered to paths that touch a predicted file,
+    // because a taint pair elsewhere in the tree is true but not about this change.
+    const localizedSet = new Set(localizedFiles);
+    const fileOfNode = (id) => {
+        const at = id.lastIndexOf('@');
+        return at === -1 ? '' : id.slice(at + 1);
+    };
+    const securityAssessed = scanned.length > 0;
+    const securityPaths = securityAssessed
+        ? (0, taint_1.taintReachability)(input.graph, taint_1.DEFAULT_TAINT_CONFIG).pairs
+            .map((pair) => ({
+            source: pair.source,
+            sink: pair.sink,
+            files: sortedUnique(pair.path.map(fileOfNode).filter(Boolean)),
+        }))
+            .filter((pair) => pair.files.some((file) => localizedSet.has(file)))
+            .sort((a, b) => a.source.localeCompare(b.source) || a.sink.localeCompare(b.sink))
+        : [];
+    // @implements A-SPEC-279 — compatibility axis. `none` is a declaration that there is nothing to
+    // carry, so it is not collected; a missing field means the spec never declared, which is why the
+    // axis reports what it FOUND rather than asserting the change is compatible.
+    // @implements A-SPEC-295 — of the candidate requirements, which cannot define "satisfied".
+    const candidateReqs = new Set(specIds.filter((id) => id.startsWith('REQ-')));
+    const unactionableCriteria = (0, acceptance_quality_1.unactionableRequirements)(specs.filter((spec) => candidateReqs.has(spec.id)));
+    // @implements A-SPEC-294 — the intent recorded on the candidate requirements' own REQs.
+    const knownDecisions = new Set(input.graph.decisionsConstraining([]));
+    const intent = [];
+    for (const id of specIds.filter((i) => i.startsWith('REQ-'))) {
+        const raw = specs.find((spec) => spec.id === id)?.frontmatter?.source;
+        for (const entry of Array.isArray(raw) ? raw : []) {
+            if (!entry || typeof entry !== 'object')
+                continue; // malformed rows are skipped, never crashed on
+            const e = entry;
+            const kind = typeof e.kind === 'string' ? e.kind : null;
+            if (!kind)
+                continue;
+            const ref = typeof e.ref === 'string' ? e.ref : null;
+            intent.push({
+                req: id,
+                kind,
+                ref,
+                retrieved: typeof e.retrieved === 'string' ? e.retrieved : null,
+                note: typeof e.note === 'string' ? e.note : null,
+                // An `adr` source names the decision the requirement came from. Linked only when that
+                // decision exists — a reference nobody can open is not a link.
+                decision: kind === 'adr' && ref && /^ADR-\d{3}$/.test(ref) ? ref : null,
+            });
+        }
+    }
+    // @implements A-SPEC-293 — decisions cited by what this change touches.
+    const constrainingDecisions = input.graph.decisionsConstraining([
+        ...localizedFiles.map((f) => `FILE:${f}`),
+        ...specIds.map((id) => `SPEC:${id}`),
+    ]);
+    const compatibilityAssessed = specs.length > 0;
+    const breakingChanges = compatibilityAssessed
+        ? specIds
+            .map((id) => specs.find((spec) => spec.id === id))
+            .filter((spec) => !!spec && spec.type === 'A-SPEC')
+            .map((spec) => ({ spec: spec.id, raw: String(spec.frontmatter?.breaking_change ?? '') }))
+            .filter((entry) => entry.raw.trim() !== '')
+            .map((entry) => ({ spec: entry.spec, kind: entry.raw.split(':')[0].trim().toLowerCase() }))
+            .filter((entry) => entry.kind !== 'none' && entry.kind !== '')
+            .sort((a, b) => a.spec.localeCompare(b.spec))
+        : [];
+    const candidateAspecs = new Set(specIds.filter((id) => id.startsWith('A-SPEC-')));
+    const relevantTestSpecs = sortedUnique(specs
+        .filter((spec) => spec.type === 'T-SPEC' && spec.dependsOn.some((id) => candidateAspecs.has(id)))
+        .map((spec) => spec.id));
+    const relevantTests = sortedUnique(Object.entries(input.testAnchors)
+        .filter(([, anchors]) => anchors.some((id) => candidateAspecs.has(id)))
+        .map(([file]) => file));
+    const testCoverageGaps = [...candidateAspecs]
+        .filter((aspec) => !relevantTestSpecs.some((id) => specs.find((spec) => spec.id === id)?.dependsOn.includes(aspec)));
+    // A bounded walk that stopped early has NOT proven the absence of further callers. Treating that
+    // silence as "no impact" is the one failure mode this analysis exists to prevent, so the
+    // truncation travels into the test scope as an unresolved axis (which forces a full run) instead
+    // of quietly leaving the tier at `unit`. Measured on this repository 2026-08-28: 6 `depth` stops
+    // coexisted with tier `unit`, empty coverage gaps, and no `unknowns` line at all.
+    const truncationReasons = sortedUnique(stoppedAt.map((stop) => stop.reason));
+    const truncationMarkers = sortedUnique(stoppedAt.map((stop) => `impact-truncated:${stop.reason}:${stop.id}`));
+    const unresolvedCoverage = [
+        ...input.coverage.skippedFiles,
+        ...input.coverage.unsupportedLanguages.map((language) => `unsupported:${language}`),
+        ...truncationMarkers,
+    ];
+    // @implements A-SPEC-269 — the same two signals `test_run`/`review_scope` already feed in. Without
+    // them a maintenance analysis could hand back a NARROWER tier than the runner would compute for
+    // the identical impact set, which is the one direction this codebase treats as unacceptable.
+    const obligationGaps = (0, scope_1.obligationGapsFor)(specs, specIds);
+    const architectureAssessed = input.changedFiles !== undefined;
+    const architectureTouched = architectureAssessed ? (0, test_scope_1.architectureGoverningFiles)([...input.changedFiles]) : [];
+    const testScope = (0, test_scope_1.computeTestScope)(specIds, input.testAnchors, specs, testCoverageGaps, undefined, { unresolvedFiles: unresolvedCoverage, architectureTouched, obligationGaps });
+    const candidateFiles = new Set(candidates.map((candidate) => candidate.file));
+    const history = input.history
+        .filter((record) => record.files.some((file) => candidateFiles.has(file)))
+        .map((record) => ({ ...record, files: [...record.files].sort() }))
+        .sort((a, b) => b.date.localeCompare(a.date) || a.commit.localeCompare(b.commit));
+    const skippedFiles = sortedUnique(input.coverage.skippedFiles);
+    const unsupportedLanguages = sortedUnique(input.coverage.unsupportedLanguages);
+    const coverageGaps = skippedFiles.length > 0 || unsupportedLanguages.length > 0
+        || input.coverage.scannedFiles === 0 || truncationMarkers.length > 0;
+    const stale = input.basis.loadedBuild !== input.basis.diskBuild;
+    const unknowns = [];
+    if (input.coverage.scannedFiles === 0)
+        unknowns.push('No source files were represented in the analyzed graph.');
+    if (skippedFiles.length > 0)
+        unknowns.push(`Skipped files are outside the evidence basis: ${skippedFiles.join(', ')}`);
+    if (unsupportedLanguages.length > 0)
+        unknowns.push(`Unsupported languages are outside the evidence basis: ${unsupportedLanguages.join(', ')}`);
+    if (truncationMarkers.length > 0) {
+        unknowns.push(`Impact closure was truncated (${truncationReasons.join(', ')}) at ${stoppedAt.length} node(s): callers beyond the bound were never explored, so the transitive impact is a lower bound, not a complete set. Stopped at ${stoppedAt.map((stop) => stop.id).join(', ')}.`);
+    }
+    // @implements A-SPEC-286 — two different facts, two different sentences. Emitting the first
+    // template unconditionally produced "Files in .py contributed no  relation" once Python's only
+    // remaining gap became the extracted-but-unresolved kind.
+    for (const gap of languageCoverage) {
+        if (gap.missing.length > 0) {
+            unknowns.push(`Files in ${gap.ext} contributed no ${gap.missing.join(' or ')} relation: that extractor does not recover ${gap.missing.length > 1 ? 'those kinds' : 'that kind'}, so impact through them is invisible rather than absent.`);
+        }
+        if (gap.extractedButUnresolved.length > 0) {
+            unknowns.push(`Files in ${gap.ext} had ${gap.extractedButUnresolved.join(' and ')} recovered from the source but never resolved into a graph edge, so nothing that queries the graph can traverse ${gap.extractedButUnresolved.length > 1 ? 'them' : 'it'}.`);
+        }
+    }
+    // @implements A-SPEC-292 — two different facts, two different sentences. An unknown target is
+    // almost always external and NOT a miss; an ambiguous one names code that is right here.
+    const discarded = input.resolution;
+    if (discarded && discarded.ambiguous > 0) {
+        unknowns.push(`${discarded.ambiguous} call/inherit relation(s) were left unlinked as ambiguous because the target name is defined in several files: that code IS in this repository and the graph declined to guess which copy, so impact through those relations is missing rather than absent.`);
+    }
+    if (discarded && discarded.unknownTarget > 0) {
+        unknowns.push(`${discarded.unknownTarget} call/inherit relation(s) name a target outside the scan — external packages and runtime builtins. They are unresolvable by design, not evidence of a gap in this repository's own graph.`);
+    }
+    for (const row of unactionableCriteria) {
+        unknowns.push(row.quality === 'absent'
+            ? `${row.req} states no Success Criteria, so whether this change satisfies it cannot be checked — only that it compiles and its tests pass.`
+            : `${row.req}'s Success Criteria say only that the implementation was completed and tested, which is not a definition of satisfied: whether this change meets the requirement cannot be checked against it.`);
+    }
+    if (constrainingDecisions.length > 0) {
+        unknowns.push(`This change is constrained by architecture decision(s) ${constrainingDecisions.join(', ')}: read them before altering the behaviour they fixed — they are what must not break, not merely what is touched.`);
+    }
+    if (runtimeStatus !== 'fresh') {
+        // Name the category the reader actually sees in the result (`runtimeObserved`), so the sentence
+        // and the field cannot be mistaken for different subjects.
+        unknowns.push(runtimeStatus === 'stale'
+            ? `The runtime observation on record was produced at ${runtimeRecord.head}, not at ${input.basis.head}: it is not evidence about this tree, so test relevance rests on anchors alone.`
+            : 'No runtime observation exists, so test relevance rests on anchors alone — no test is known to have actually executed the impacted contracts.');
+    }
+    if (!securityAssessed) {
+        unknowns.push('The security axis was not assessed: there was no scanned code to walk, so no data-flow reachability was checked.');
+    }
+    if (!compatibilityAssessed) {
+        unknowns.push('The compatibility axis was not assessed: no specifications were available, so no breaking-change declaration could be read.');
+    }
+    if (!architectureAssessed) {
+        // Assessed-and-empty and never-assessed are different claims. This axis has no input to read
+        // without a diff, so it is disclosed rather than escalated: unlike a truncated closure (where we
+        // looked and stopped early), here there was nothing to look at.
+        unknowns.push('Architecture-governing documents were not assessed: no changed-file basis was supplied. Pass changedFiles (e.g. a base..head diff) to cover the .ax/decisions and C-SPEC axis.');
+    }
+    if (input.coverage.historyStatus === 'unavailable')
+        unknowns.push('Git history was unavailable; historical rationale is incomplete.');
+    if (stale)
+        unknowns.push('The loaded MCP build differs from the disk build; restart is required for a current tool basis.');
+    for (const aspec of candidateAspecs) {
+        if (!relevantTestSpecs.some((id) => specs.find((spec) => spec.id === id)?.dependsOn.includes(aspec))) {
+            unknowns.push(`No T-SPEC was found for impacted contract ${aspec}.`);
+        }
+    }
+    const implementedMatchedSpecs = new Set(localization.hits.flatMap((hit) => hit.viaSpecs));
+    const contradictions = localization.matchedSpecs
+        .filter((id) => !implementedMatchedSpecs.has(id))
+        .map((id) => `Request text matches ${id}, but no localized code candidate implements it.`);
+    // @implements A-SPEC-358 — surfaced for the reader rather than silently folded into the verdict.
+    for (const line of contradictions)
+        unknowns.push(line);
+    // @implements A-SPEC-358
+    // `contradictions` no longer forces ambiguity, and the reason is a measurement rather than a
+    // preference. Over 60 point-in-time cases `confidence` took exactly ONE value (0.25) while the
+    // analysis delivered 0.770 recall; counted over 20 of them, this trigger fired in 20 — and
+    // `candidateSpecs` was non-empty in all 20, so it alone was pinning every case to `ambiguous`.
+    //
+    // Look at what the trigger means: an A-SPEC whose text shares words with the request, whose
+    // anchored files did not make the candidate list. In a corpus of several hundred specs such a
+    // spec always exists. So the more specs a project wrote, the less its analysis could ever commit
+    // — governance disabling the tool that reads it. The signal is real but far too weak to be a
+    // verdict, so it stays in `contradictions` and in `unknowns` where a reader can weigh it.
+    //
+    // The genuinely-incomplete cases still force ambiguity: an unscanned file, an unsupported
+    // language, a truncated closure, an empty scan, a stale build. This narrows what counts as
+    // incomplete; it does not remove the caution.
+    const classification = coverageGaps || stale
+        ? 'ambiguous'
+        : specIds.length > 0
+            ? 'existing-requirement-change'
+            : candidates.length === 0
+                ? 'ambiguous'
+                : 'new-requirement';
+    // @implements A-SPEC-360
+    // NOT a probability, and the disclaimer is measured rather than modest. This number summarizes
+    // which KINDS of evidence were present, never how good any of them was — a candidate matching one
+    // ubiquitous word and one matching three distinctive ones contribute identically. Correlated
+    // against delivered localization accuracy over 60 point-in-time cases: **-0.062** here and -0.016
+    // on a second corpus, with the confident cases marginally LESS accurate than the ambiguous ones.
+    //
+    // Eight other computed signals were tested as replacements (top score, first-to-second margin and
+    // its ratio, matched specs, candidate count, relevant tests, scanned files, and this field). None
+    // agreed even in SIGN across the two corpora, so there is nothing here to rebuild it on. The value
+    // is left as it is deliberately: changing it would silently alter an existing contract with no
+    // measurement showing the new one is better.
+    const confidence = classification === 'existing-requirement-change'
+        ? Math.min(1, 0.55 + (direct.length > 0 ? 0.15 : 0) + (relevantTests.length > 0 ? 0.15 : 0) + (history.length > 0 ? 0.1 : 0))
+        : classification === 'new-requirement' ? 0.65 : 0.25;
+    // @implements A-SPEC-375
+    // Ranked by the localization that just ran, so the suggestion inherits whatever evidence the
+    // lexical layer found rather than re-deriving a second, possibly disagreeing, opinion.
+    // Shared with the scorer rather than re-detected: a second citation reader would drift, and the
+    // drift would show up as the tool suggesting a citation to a request that already made one.
+    const requestCitations = (0, localize_1.citationsIn)(input.request, new Set(specs.map((spec) => spec.id)));
+    const citationCandidates = requestCitations.cited.length > 0
+        ? []
+        : localization.hits.flatMap((hit) => hit.viaSpecs)
+            .concat(localization.matchedSpecs)
+            .filter((id, i, all) => all.indexOf(id) === i)
+            .slice(0, 3);
+    if (citationCandidates.length > 0) {
+        unknowns.push(`The request cites no specification. Measured over 60 point-in-time cases, a request that names `
+            + `its A-SPEC reaches Top-10 localization recall 0.770 where one that does not reaches 0.349 — `
+            + `level with plain word matching. Consider re-asking while citing one of: `
+            + `${citationCandidates.join(', ')}.`);
+    }
+    // @implements A-SPEC-390
+    const declaredIn = new Map();
+    for (const f of scanned) {
+        for (const sym of f.symbols) {
+            const bare = sym.qualifiedName.includes('.')
+                ? sym.qualifiedName.slice(sym.qualifiedName.lastIndexOf('.') + 1) : sym.qualifiedName;
+            for (const key of new Set([sym.qualifiedName, bare])) {
+                (declaredIn.get(key) ?? declaredIn.set(key, new Set()).get(key)).add(f.sourcePath);
+            }
+        }
+    }
+    let edgeTotal = 0, edgeInternal = 0, edgeAmbiguous = 0, edgeOutOfScan = 0, edgeWithin = 0;
+    for (const f of scanned) {
+        for (const e of f.edges ?? []) {
+            if (e.rel !== 'calls')
+                continue;
+            edgeTotal++;
+            const targets = declaredIn.get(e.to);
+            if (!targets || targets.size === 0) {
+                edgeOutOfScan++;
+                continue;
+            }
+            if (targets.size > 1) {
+                edgeAmbiguous++;
+                continue;
+            }
+            if (targets.has(f.sourcePath))
+                edgeWithin++;
+            else
+                edgeInternal++;
+        }
+    }
+    const callEdges = {
+        total: edgeTotal,
+        internalResolved: edgeInternal,
+        ambiguous: edgeAmbiguous,
+        outOfScan: edgeOutOfScan,
+        withinFile: edgeWithin,
+        internalResolvedShare: edgeTotal === 0 ? null : edgeInternal / edgeTotal,
+    };
+    if (edgeTotal > 0 && edgeInternal / edgeTotal < 0.5) {
+        unknowns.push(`Call graph density is narrower than the edge count suggests: ${edgeInternal} of ${edgeTotal} `
+            + `call edges bind to exactly one other scanned file; ${edgeOutOfScan} name targets outside the `
+            + `scan (libraries and builtins) and ${edgeAmbiguous} are ambiguous. Impact traversal uses only `
+            + `the resolved ones.`);
+    }
+    const evidence = {
+        schemaVersion: exports.MAINTENANCE_ANALYSIS_SCHEMA,
+        extractorVersion: exports.MAINTENANCE_ANALYSIS_EXTRACTOR,
+        classification,
+        confidence,
+        citationCandidates,
+        callEdges,
+        candidates,
+        ...(semanticAlternates !== undefined ? { semanticAlternates } : {}),
+        rerankPool,
+        candidateSpecs: specIds,
+        impacts: {
+            files: localizedFiles,
+            tiers: { primary: primaryTier, secondary: secondaryTier },
+            impactedFiles: reachableTier,
+            rankedImpact,
+            importedByFiles,
+            unresolvedRelations: input.resolution ?? null,
+            runtimeObserved: {
+                status: runtimeStatus,
+                specs: runtimeStatus === 'fresh'
+                    ? specIds.filter((id) => (runtimeRecord.executedByAspec[id] ?? 0) > 0)
+                    : [],
+            },
+            direct, transitive, contract: specIds, test: relevantTests,
+        },
+        impactBounds: {
+            maxCallDepth,
+            hubInDegree,
+            stoppedAt: stoppedAt.sort((a, b) => a.id.localeCompare(b.id) || a.reason.localeCompare(b.reason)),
+            ...(seeds.reduce((max, id) => Math.max(max, input.graph.callerCount(id)), 0) > hubInDegree
+                ? { seedIsHub: { callers: seeds.reduce((max, id) => Math.max(max, input.graph.callerCount(id)), 0), threshold: hubInDegree } }
+                : {}),
+        },
+        constraints: {
+            security: { assessed: securityAssessed, limits: [...taint_1.TAINT_LIMITS], paths: securityPaths },
+            compatibility: { assessed: compatibilityAssessed, breakingChanges },
+            decisions: constrainingDecisions,
+        },
+        languageCoverage,
+        unactionableCriteria,
+        intent,
+        testScope,
+        relevantTests,
+        relevantTestSpecs,
+        historicalRationale: history,
+        contextBundle: input.contextBundle ?? null,
+        assumptions: ['Static graph evidence is advisory and must be validated by the selected tests.'],
+        contradictions,
+        unknowns,
+        coverage: { scannedFiles: input.coverage.scannedFiles, skippedFiles, unsupportedLanguages, historyStatus: input.coverage.historyStatus },
+        graphBasis: { ...input.basis, stale },
+        ablation: buildAblation({
+            request: input.request,
+            scanned,
+            testAnchors: input.testAnchors,
+            candidates,
+            direct,
+            transitive,
+            directSpecIds,
+            localizedFiles,
+            primaryTier,
+            impactedTier: reachableTier,
+            importedByTier: importedByFiles,
+            relevantTests,
+            historyCount: history.length,
+            fileOfSymbol,
+            groundTruth: input.groundTruth,
+        }),
+    };
+    return {
+        ...evidence,
+        evidenceDigest: `sha256:${(0, crypto_1.createHash)('sha256').update(canonical(evidence)).digest('hex')}`,
+    };
+}
+/**
+ * Three arms computed from the SAME raw inputs by three different amounts of graph:
+ *
+ *   graphOff  — lexical only: no spec linkage, no call edges, no anchors. What a plain grep gets.
+ *   current   — localization + spec ancestry of the directly matched symbols + their anchored tests.
+ *   enhanced  — adds the bounded caller closure (and the files/specs/tests it alone reaches),
+ *               history, and the versioned coverage/build basis.
+ *
+ * Each arm's numbers come from its OWN prediction scored against externally supplied ground truth.
+ * No arm is scored against another arm's output.
+ */
+function buildAblation(a) {
+    const truth = a.groundTruth;
+    // --- graph-off: term overlap against raw scanned symbols and paths, ranked, top-10 like the
+    // localizer's own cut-off so the arms are compared at the same budget.
+    const terms = new Set((0, localize_1.significantTerms)(a.request));
+    const lexical = a.scanned.map((file) => {
+        const matched = file.symbols
+            .filter((symbol) => (0, localize_1.significantTerms)(symbol.qualifiedName).some((term) => terms.has(term)))
+            .map((symbol) => symbol.qualifiedName);
+        const pathHit = (0, localize_1.significantTerms)(file.sourcePath).some((term) => terms.has(term));
+        return { file: file.sourcePath, matched, score: matched.length + (pathHit ? 1 : 0) };
+    }).filter((entry) => entry.score > 0)
+        .sort((x, y) => y.score - x.score || x.file.localeCompare(y.file))
+        .slice(0, 10);
+    const graphOff = arm(lexical.map((entry) => entry.file), sortedUnique(lexical.flatMap((entry) => entry.matched)), [], [
+        ...(lexical.length > 0 ? ['candidates'] : []),
+        ...(lexical.some((entry) => entry.matched.length > 0) ? ['directImpact'] : []),
+    ], truth);
+    // --- current: spec-aware localization, but no caller closure and no versioned basis.
+    const currentAspecs = new Set(a.directSpecIds.filter((id) => id.startsWith('A-SPEC-')));
+    const currentTests = sortedUnique(Object.entries(a.testAnchors)
+        .filter(([, anchors]) => anchors.some((id) => currentAspecs.has(id)))
+        .map(([file]) => file));
+    const current = arm(sortedUnique(a.candidates.map((candidate) => candidate.file)), [...a.direct], currentTests, [
+        ...(a.candidates.length > 0 ? ['candidates'] : []),
+        ...(a.directSpecIds.length > 0 ? ['specs'] : []),
+        ...(a.direct.length > 0 ? ['directImpact'] : []),
+        ...(currentTests.length > 0 ? ['tests'] : []),
+    ], truth);
+    // --- enhanced: the caller closure also LOCALIZES — a file reachable only through a call edge is a
+    // modification candidate the lexical and no-closure arms structurally cannot name.
+    const enhancedFiles = a.localizedFiles;
+    const enhanced = arm(enhancedFiles, sortedUnique([...a.direct, ...a.transitive]), [...a.relevantTests], [
+        ...(enhancedFiles.length > 0 ? ['candidates'] : []),
+        ...(a.directSpecIds.length > 0 ? ['specs'] : []),
+        ...(a.direct.length > 0 ? ['directImpact'] : []),
+        ...(a.transitive.length > 0 ? ['transitiveImpact'] : []),
+        ...(a.relevantTests.length > 0 ? ['tests'] : []),
+        ...(a.historyCount > 0 ? ['history'] : []),
+        // The versioned coverage/build/digest basis is emitted unconditionally — including when it
+        // reports zero coverage, which is itself the evidence that matters.
+        'versionedBasis',
+    ], truth, a.primaryTier, a.impactedTier, a.importedByTier);
+    return { graphOff, current, enhanced };
+}