@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/review/dense-retrieval.d.ts

@@ -0,0 +1,66 @@
+import type { Spec } from '../spec/spec-parser';
+/**
+ * The eighth attempt: does a dense embedding beat matching the words?
+ *
+ * Seven mechanisms have been measured against uncited requests and all seven were negative. The last
+ * two aimed straight at the matching step — BM25 with morphological normalisation, and query
+ * expansion through the graph — and both traded recall for precision or the reverse. The hypothesis
+ * left standing is that what failed was not the idea but the offline bag-of-words implementing it: a
+ * report saying "uploads are being rejected" and a spec saying "quarantine of malformed payloads"
+ * share no token at all, and no amount of stemming makes them share one.
+ *
+ * ## Why this is optional, and stays optional
+ *
+ * The model is tens of megabytes and its first use may need a network. Making that a condition of
+ * installing Holmes-Kit would tax every user for a feature most will not switch on, so:
+ *
+ * - the dependency is OPTIONAL — absent by default, installed only when a project opts in;
+ * - it is imported dynamically inside a try/catch, so a missing module is a normal state and not a
+ *   crash;
+ * - when it is unavailable the result says `available: false` and the caller falls back to the
+ *   lexical path. It never returns an empty ranking, because "the model is not here" and "nothing
+ *   was similar" are different facts and one of them must not be reported as the other.
+ */
+export interface DenseAvailability {
+    available: boolean;
+    /** Why not, when it is not — for a diagnostic that tells the user what to do about it. */
+    reason?: 'module-absent' | 'model-unavailable';
+}
+export interface DenseRanked {
+    id: string;
+    similarity: number;
+}
+export interface DenseIndex {
+    availability: DenseAvailability;
+    /** null when unavailable — never an empty ranking, which would read as "nothing matched". */
+    rank(issueText: string, topK: number): Promise<DenseRanked[] | null>;
+}
+/**
+ * @implements A-SPEC-474 — the model becomes a PARAMETER so a discriminating re-measure can swap
+ * only that axis. The historical verdicts (0.424 vs 0.699; 6 of 25 lexical-zero cases) were
+ * measured with the English-only MiniLM above against a largely KOREAN spec store — a condition
+ * flaw the re-measure exists to isolate. The DEFAULT does not move: absent opts, shipped behavior
+ * is bit-identical. `pipeline` is injectable for tests only — the optional module stays optional.
+ */
+export type PipelineLoader = (task: string, model: string, opts: {
+    quantized: boolean;
+}) => Promise<(text: string, opts: {
+    pooling: string;
+    normalize: boolean;
+}) => Promise<{
+    data: Float32Array;
+}>>;
+export interface DenseOptions {
+    model?: string;
+    pipeline?: PipelineLoader;
+}
+/** Cosine similarity of two equal-length vectors. */
+export declare function cosine(a: readonly number[], b: readonly number[]): number;
+/** The text of a spec as the embedder sees it. Title first: it is the densest statement of subject. */
+export declare function specText(s: Spec): string;
+/**
+ * Build an index over the A-SPECs, or report why it could not be built.
+ *
+ * Never throws: an absent optional dependency is an expected state on most installations.
+ */
+export declare function buildDenseIndex(specs: readonly Spec[], opts?: DenseOptions): Promise<DenseIndex>;

package/dist/holmes/review/dense-retrieval.js

@@ -0,0 +1,97 @@
+"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.cosine = cosine;
+exports.specText = specText;
+exports.buildDenseIndex = buildDenseIndex;
+const MODEL = 'Xenova/all-MiniLM-L6-v2';
+/** Cosine similarity of two equal-length vectors. */
+function cosine(a, b) {
+    if (a.length !== b.length || a.length === 0)
+        return 0;
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    return na === 0 || nb === 0 ? 0 : dot / Math.sqrt(na * nb);
+}
+/** The text of a spec as the embedder sees it. Title first: it is the densest statement of subject. */
+function specText(s) {
+    return `${s.title}. ${Object.values(s.sections).join(' ')}`.slice(0, 2000);
+}
+/**
+ * Build an index over the A-SPECs, or report why it could not be built.
+ *
+ * Never throws: an absent optional dependency is an expected state on most installations.
+ */
+async function buildDenseIndex(specs, opts = {}) {
+    const docs = specs.filter((s) => s.type === 'A-SPEC');
+    let embed = null;
+    let reason = 'module-absent';
+    try {
+        // Dynamic, guarded, AND resolved through a variable specifier. A literal `import('...')` is a
+        // COMPILE-time dependency: removing the package broke `tsc` even though every runtime path
+        // already handled its absence, which is the opposite of optional. Measured by doing it.
+        let loader = opts.pipeline;
+        if (loader === undefined) {
+            const specifier = '@xenova/transformers';
+            const mod = await Promise.resolve(`${specifier}`).then(s => __importStar(require(s)));
+            loader = mod.pipeline;
+        }
+        reason = 'model-unavailable';
+        const pipe = await loader('feature-extraction', opts.model ?? MODEL, { quantized: true });
+        embed = async (text) => Array.from((await pipe(text, { pooling: 'mean', normalize: true })).data);
+    }
+    catch {
+        return { availability: { available: false, reason }, rank: async () => null };
+    }
+    const vectors = [];
+    for (const s of docs)
+        vectors.push({ id: s.id, vector: await embed(specText(s)) });
+    return {
+        availability: { available: true },
+        rank: async (issueText, topK) => {
+            if (issueText.trim().length === 0 || vectors.length === 0)
+                return [];
+            const q = await embed(issueText);
+            return vectors
+                .map((v) => ({ id: v.id, similarity: cosine(q, v.vector) }))
+                .sort((a, b) => b.similarity - a.similarity || a.id.localeCompare(b.id))
+                .slice(0, topK);
+        },
+    };
+}

package/dist/holmes/review/edge-quality.d.ts

@@ -0,0 +1,44 @@
+import type { ScannedFile } from '../cpg/cpg-scanner';
+/**
+ * What a `calls` edge actually is.
+ *
+ * Five mechanisms that walked the call graph made retrieval WORSE — the single hop cost Top-10 recall
+ * 0.770 → 0.547. That has been recorded as the idea failing, and there is a competing explanation
+ * that was never tested: the edges may be wrong. Extraction is syntactic, and a call is bound to its
+ * target BY NAME. A name defined in two files is ambiguous; a name defined nowhere in the scan is
+ * unresolved. If proven calls and name-guesses are mixed into one relation, a walk over them
+ * failing is not a fact about walks.
+ *
+ * The distinction the assessment asks for — CALLS_PROVEN against MAY_CALL against
+ * UNRESOLVED_CALLSITE — starts by counting which of the three the corpus actually contains.
+ */
+export type EdgeResolution = 'unique' | 'ambiguous' | 'unresolved' | 'self';
+export interface EdgeQuality {
+    total: number;
+    unique: number;
+    ambiguous: number;
+    unresolved: number;
+    /** Calls landing in the file they came from — resolvable without any cross-file guess. */
+    self: number;
+    /** null when there are no edges: an unmeasured graph, not a perfect one. */
+    uniqueShare: number | null;
+}
+/**
+ * Classify each call edge by how its target name resolves across the scan.
+ *
+ * Both the qualified name and its last segment are indexed, matching how the walk itself binds — a
+ * classifier stricter than the consumer would report a quality the consumer never had.
+ */
+/**
+ * @implements A-SPEC-393
+ * Resolve an import specifier to a scanned file.
+ *
+ * `imports` edges carry the module path only — `../spec/spec-parser`, not which symbols came with
+ * it. That is still enough to break a tie: among several files declaring the same name, the one this
+ * file actually imports is the one it calls. It is the cheapest form of what the review calls Tier 2
+ * symbol resolution, and the part reachable without a compiler.
+ */
+export declare function resolveImport(fromFile: string, specifier: string, known: ReadonlySet<string>): string | null;
+export declare function callEdgeQuality(scanned: readonly ScannedFile[], opts?: {
+    importAware?: boolean;
+}): EdgeQuality;

package/dist/holmes/review/edge-quality.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveImport = resolveImport;
+exports.callEdgeQuality = callEdgeQuality;
+/**
+ * Classify each call edge by how its target name resolves across the scan.
+ *
+ * Both the qualified name and its last segment are indexed, matching how the walk itself binds — a
+ * classifier stricter than the consumer would report a quality the consumer never had.
+ */
+/**
+ * @implements A-SPEC-393
+ * Resolve an import specifier to a scanned file.
+ *
+ * `imports` edges carry the module path only — `../spec/spec-parser`, not which symbols came with
+ * it. That is still enough to break a tie: among several files declaring the same name, the one this
+ * file actually imports is the one it calls. It is the cheapest form of what the review calls Tier 2
+ * symbol resolution, and the part reachable without a compiler.
+ */
+function resolveImport(fromFile, specifier, known) {
+    const bases = [];
+    if (specifier.startsWith('.') && specifier.includes('/')) {
+        // JS/TS relative form: resolve against the importing file's directory.
+        const dir = fromFile.includes('/') ? fromFile.slice(0, fromFile.lastIndexOf('/')) : '';
+        const stack = [];
+        for (const part of `${dir}/${specifier}`.split('/')) {
+            if (part === '' || part === '.')
+                continue;
+            if (part === '..') {
+                stack.pop();
+                continue;
+            }
+            stack.push(part);
+        }
+        bases.push(stack.join('/'));
+    }
+    else if (specifier.includes('.')) {
+        // Dotted module form (Python): `src.core.llm`. The scan root may already BE the package root, so
+        // the leading segment is tried both ways — measured on the second corpus, where paths are
+        // relative to `src/` and every import names `src.` anyway, so without this the resolver found
+        // nothing and the 1,534 ambiguous edges there did not move at all.
+        const slashed = specifier.split('.').join('/');
+        bases.push(slashed);
+        const withoutFirst = specifier.split('.').slice(1).join('/');
+        if (withoutFirst.length > 0)
+            bases.push(withoutFirst);
+    }
+    else {
+        return null; // a bare package name — nothing in this scan
+    }
+    for (const base of bases) {
+        for (const candidate of [`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}.js`, `${base}.py`, `${base}/__init__.py`]) {
+            if (known.has(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function callEdgeQuality(scanned, opts = {}) {
+    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);
+            }
+        }
+    }
+    const knownPaths = new Set(scanned.map((f) => f.sourcePath));
+    let total = 0, unique = 0, ambiguous = 0, unresolved = 0, self = 0;
+    for (const f of scanned) {
+        // @implements A-SPEC-393 — the modules this file actually imports, resolved to scanned paths.
+        const imported = new Set();
+        if (opts.importAware) {
+            for (const e of f.edges ?? []) {
+                if (e.rel !== 'imports')
+                    continue;
+                const target = resolveImport(f.sourcePath, e.to, knownPaths);
+                if (target)
+                    imported.add(target);
+            }
+        }
+        for (const e of f.edges ?? []) {
+            if (e.rel !== 'calls')
+                continue;
+            total++;
+            const targets = declaredIn.get(e.to);
+            if (!targets || targets.size === 0) {
+                unresolved++;
+                continue;
+            }
+            if (targets.size === 1) {
+                if (targets.has(f.sourcePath))
+                    self++;
+                else
+                    unique++;
+                continue;
+            }
+            // Ambiguous by name — but if exactly one candidate is a module this file imports, the call is
+            // that one. Binding only when exactly one matches: two imported candidates is still a guess,
+            // and a guess dressed as a resolution is worse than a disclosed ambiguity.
+            if (opts.importAware) {
+                const viaImport = [...targets].filter((t) => imported.has(t));
+                if (viaImport.length === 1) {
+                    if (viaImport[0] === f.sourcePath)
+                        self++;
+                    else
+                        unique++;
+                    continue;
+                }
+            }
+            ambiguous++;
+        }
+    }
+    return { total, unique, ambiguous, unresolved, self, uniqueShare: total === 0 ? null : unique / total };
+}

package/dist/holmes/review/evaluation-metrics.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Objective evaluation of a replay corpus (Goal Phase 8).
+ *
+ * The replay numbers used to exist only as a `console.log` in one test, copied into documentation by
+ * hand. That is not a contract: a metric can fall and the suite still passes. It happened during this
+ * work — authoring a single slice moved localization recall from 0.5476 to 0.5060 while every test
+ * stayed green, and only a human comparing two tables noticed.
+ *
+ * So the computation lives here, pure and fixture-checked, and the replay test asserts FLOORS taken
+ * from a real measurement. Raising a floor pins an improvement and is always welcome; lowering one
+ * approves a regression and needs a reason recorded with it.
+ *
+ * `null` rather than `0` for an unmeasured metric, throughout: zero claims "measured, and bad".
+ */
+export declare const TOP_K: readonly [1, 3, 5, 10];
+export interface ReplayOutcome {
+    /** Predicted files, best first. */
+    ranked: string[];
+    /** Files the change actually touched. */
+    truthFiles: string[];
+    selectedTests: string[];
+    truthTests: string[];
+}
+export interface CutMetrics {
+    /** Share of cases where at least one truth file appears in the first K. */
+    hitRate: number | null;
+    recall: number | null;
+    precision: number | null;
+}
+export interface EvaluationMetrics {
+    cases: number;
+    /** Cases that have truth to score against — the denominator recall actually rests on. */
+    scorableCases: number;
+    topK: Record<number, CutMetrics>;
+    testRecall: number | null;
+}
+export declare function evaluationMetrics(outcomes: readonly ReplayOutcome[]): EvaluationMetrics;
+/**
+ * One case of change-driven impact: a file is presented as changed, and the question is which OTHER
+ * files that change reaches. The ground truth is free — a commit's co-changed files are exactly the
+ * answer, recorded by the person who made the change.
+ */
+export interface ImpactCase {
+    /** The file presented as changed. Excluded from both sides of the score. */
+    seed: string;
+    /** The other files the commit really touched. */
+    expected: string[];
+    /** The files the analysis said were impacted. */
+    predicted: string[];
+}
+export interface ImpactEvaluation {
+    cases: number;
+    /** Cases with something to predict. A commit touching ONE file cannot be scored on impact. */
+    scorableCases: number;
+    recall: number | null;
+    precision: number | null;
+}
+/**
+ * Impact had no benchmark until this existed, so an impact regression could not fail anything.
+ * Measured on the replay corpus: 26 of 155 truth files are reached by impact and none of those 26
+ * appear in the ranking — the two paths find different files, and only ranking was ever scored.
+ *
+ * Recall and precision are both reported because they say different things: widening scope buys
+ * recall with precision, and a single number would hide which way a change traded.
+ */
+export declare function impactMetrics(cases: readonly ImpactCase[]): ImpactEvaluation;
+/** One case for the ceiling: what the commit co-changed, and what the graph can reach at all. */
+export interface CeilingCase {
+    expected: string[];
+    /** Files reachable from the seed by ANY relation, in ANY direction, at any depth. */
+    reachable: string[];
+}
+export interface CeilingEvaluation {
+    scorableCases: number;
+    /** Mean share of co-changed files the graph could reach even in principle. */
+    ceiling: number | null;
+}
+/**
+ * How much of the ground truth is reachable at all.
+ *
+ * A measured impact recall of 0.093 says nothing on its own: files land in the same commit for
+ * reasons the graph has no way to represent, so recall 1.0 was never available. The ceiling supplies
+ * the denominator that turns "0.093" into "0.093 of X".
+ *
+ * Computed OPTIMISTICALLY on purpose — no relation filter, no direction, no depth bound. A narrower
+ * definition of reachable would lower the ceiling and flatter the algorithm's achievement rate,
+ * which is bending the ruler toward the thing being measured.
+ */
+export declare function ceilingMetrics(cases: readonly CeilingCase[]): CeilingEvaluation;
+/**
+ * Measured recall as a share of what was reachable. `null` when there is no denominator — dividing
+ * by a zero ceiling would report perfect achievement on a corpus where nothing could be found.
+ */
+export declare function achievementRate(recall: number | null, ceiling: number | null): number | null;
+export interface BoundsCase {
+    /** What the walk refused to expand, and why, as the analysis already records it. */
+    stoppedAt: Array<{
+        id: string;
+        reason: string;
+    }>;
+    /** The files the commit really co-changed. */
+    expected: string[];
+}
+export interface BoundsSummary {
+    cases: number;
+    hubStops: number;
+    depthStops: number;
+    /**
+     * Cases where a stop landed on a file the commit actually changed. Stops are cheap unless the
+     * answer was behind one, so this is the number that decides whether raising a bound would help.
+     */
+    expectedBehindStops: number;
+}
+/**
+ * Aggregate what the traversal bounds cut.
+ *
+ * `impactBounds.stoppedAt` has always recorded this node by node and nothing had ever read it — the
+ * tool was stating its own limits to an empty room. Counting them before changing them is the order
+ * that has repeatedly paid here: the capability table found C++'s zero edges, the resolution report
+ * found the Rust and Go naming defect, and `callerNotNamed` found the contract gap.
+ */
+export declare function boundsImpact(cases: readonly BoundsCase[]): BoundsSummary;
+/**
+ * Which axis found each correct file.
+ *
+ * Measured on the replay corpus: 26 of 155 truth files are reached by impact and none of those
+ * appear in the ranking. The axes are complementary, yet each was scored alone — so the set the user
+ * actually receives, the union, had never been scored at all, and six tuning verdicts were reached
+ * looking at one half.
+ *
+ * Counted over the TRUTH rather than over the predictions: the question is which axis found the
+ * answer, not how much the two happen to agree with each other.
+ */
+export declare function overlapOf(ranked: readonly string[], impacted: readonly string[], truth: readonly string[]): {
+    rankedOnly: number;
+    impactOnly: number;
+    both: number;
+};

package/dist/holmes/review/evaluation-metrics.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOP_K = void 0;
+exports.evaluationMetrics = evaluationMetrics;
+exports.impactMetrics = impactMetrics;
+exports.ceilingMetrics = ceilingMetrics;
+exports.achievementRate = achievementRate;
+exports.boundsImpact = boundsImpact;
+exports.overlapOf = overlapOf;
+// @implements A-SPEC-296
+/**
+ * Objective evaluation of a replay corpus (Goal Phase 8).
+ *
+ * The replay numbers used to exist only as a `console.log` in one test, copied into documentation by
+ * hand. That is not a contract: a metric can fall and the suite still passes. It happened during this
+ * work — authoring a single slice moved localization recall from 0.5476 to 0.5060 while every test
+ * stayed green, and only a human comparing two tables noticed.
+ *
+ * So the computation lives here, pure and fixture-checked, and the replay test asserts FLOORS taken
+ * from a real measurement. Raising a floor pins an improvement and is always welcome; lowering one
+ * approves a regression and needs a reason recorded with it.
+ *
+ * `null` rather than `0` for an unmeasured metric, throughout: zero claims "measured, and bad".
+ */
+exports.TOP_K = [1, 3, 5, 10];
+const mean = (xs) => (xs.length === 0 ? null : xs.reduce((s, x) => s + x, 0) / xs.length);
+function evaluationMetrics(outcomes) {
+    const scorable = outcomes.filter((o) => o.truthFiles.length > 0);
+    const topK = {};
+    for (const k of exports.TOP_K) {
+        const hits = [];
+        const recalls = [];
+        const precisions = [];
+        for (const o of scorable) {
+            const cut = o.ranked.slice(0, k);
+            const found = cut.filter((f) => o.truthFiles.includes(f)).length;
+            hits.push(found > 0 ? 1 : 0);
+            recalls.push(found / o.truthFiles.length);
+            precisions.push(cut.length === 0 ? 0 : found / cut.length);
+        }
+        topK[k] = { hitRate: mean(hits), recall: mean(recalls), precision: mean(precisions) };
+    }
+    const testScorable = outcomes.filter((o) => o.truthTests.length > 0);
+    const testRecall = mean(testScorable.map((o) => o.truthTests.filter((t) => o.selectedTests.includes(t)).length / o.truthTests.length));
+    return { cases: outcomes.length, scorableCases: scorable.length, topK, testRecall };
+}
+/**
+ * Impact had no benchmark until this existed, so an impact regression could not fail anything.
+ * Measured on the replay corpus: 26 of 155 truth files are reached by impact and none of those 26
+ * appear in the ranking — the two paths find different files, and only ranking was ever scored.
+ *
+ * Recall and precision are both reported because they say different things: widening scope buys
+ * recall with precision, and a single number would hide which way a change traded.
+ */
+function impactMetrics(cases) {
+    const recalls = [];
+    const precisions = [];
+    for (const c of cases) {
+        const expected = new Set(c.expected.filter((f) => f !== c.seed));
+        if (expected.size === 0)
+            continue; // nothing to predict: unmeasured, not zero
+        const predicted = new Set(c.predicted.filter((f) => f !== c.seed));
+        let hit = 0;
+        for (const f of predicted)
+            if (expected.has(f))
+                hit++;
+        recalls.push(hit / expected.size);
+        // An empty prediction is not perfect precision. Answering nothing is a failure to answer.
+        precisions.push(predicted.size === 0 ? 0 : hit / predicted.size);
+    }
+    const mean = (xs) => (xs.length === 0 ? null : xs.reduce((a, b) => a + b, 0) / xs.length);
+    return {
+        cases: cases.length,
+        scorableCases: recalls.length,
+        recall: mean(recalls),
+        precision: mean(precisions),
+    };
+}
+/**
+ * How much of the ground truth is reachable at all.
+ *
+ * A measured impact recall of 0.093 says nothing on its own: files land in the same commit for
+ * reasons the graph has no way to represent, so recall 1.0 was never available. The ceiling supplies
+ * the denominator that turns "0.093" into "0.093 of X".
+ *
+ * Computed OPTIMISTICALLY on purpose — no relation filter, no direction, no depth bound. A narrower
+ * definition of reachable would lower the ceiling and flatter the algorithm's achievement rate,
+ * which is bending the ruler toward the thing being measured.
+ */
+function ceilingMetrics(cases) {
+    const shares = [];
+    for (const c of cases) {
+        if (c.expected.length === 0)
+            continue;
+        const reachable = new Set(c.reachable);
+        shares.push(c.expected.filter((f) => reachable.has(f)).length / c.expected.length);
+    }
+    return {
+        scorableCases: shares.length,
+        ceiling: shares.length === 0 ? null : shares.reduce((a, b) => a + b, 0) / shares.length,
+    };
+}
+/**
+ * Measured recall as a share of what was reachable. `null` when there is no denominator — dividing
+ * by a zero ceiling would report perfect achievement on a corpus where nothing could be found.
+ */
+function achievementRate(recall, ceiling) {
+    if (recall === null || ceiling === null || ceiling === 0)
+        return null;
+    return recall / ceiling;
+}
+/**
+ * Aggregate what the traversal bounds cut.
+ *
+ * `impactBounds.stoppedAt` has always recorded this node by node and nothing had ever read it — the
+ * tool was stating its own limits to an empty room. Counting them before changing them is the order
+ * that has repeatedly paid here: the capability table found C++'s zero edges, the resolution report
+ * found the Rust and Go naming defect, and `callerNotNamed` found the contract gap.
+ */
+function boundsImpact(cases) {
+    let hubStops = 0;
+    let depthStops = 0;
+    let expectedBehindStops = 0;
+    for (const c of cases) {
+        const expected = new Set(c.expected);
+        const hitFiles = new Set();
+        for (const stop of c.stoppedAt) {
+            // An unrecognised reason is counted as neither. Folding it into `hub` would turn an unknown
+            // into a confident wrong diagnosis.
+            if (stop.reason === 'hub')
+                hubStops++;
+            else if (stop.reason === 'depth')
+                depthStops++;
+            const at = stop.id.lastIndexOf('@');
+            if (at < 0)
+                continue;
+            const file = stop.id.slice(at + 1);
+            if (expected.has(file))
+                hitFiles.add(file);
+        }
+        expectedBehindStops += hitFiles.size;
+    }
+    return { cases: cases.length, hubStops, depthStops, expectedBehindStops };
+}
+// @implements A-SPEC-312
+/**
+ * Which axis found each correct file.
+ *
+ * Measured on the replay corpus: 26 of 155 truth files are reached by impact and none of those
+ * appear in the ranking. The axes are complementary, yet each was scored alone — so the set the user
+ * actually receives, the union, had never been scored at all, and six tuning verdicts were reached
+ * looking at one half.
+ *
+ * Counted over the TRUTH rather than over the predictions: the question is which axis found the
+ * answer, not how much the two happen to agree with each other.
+ */
+function overlapOf(ranked, impacted, truth) {
+    const inRanked = new Set(ranked);
+    const inImpacted = new Set(impacted);
+    let rankedOnly = 0;
+    let impactOnly = 0;
+    let both = 0;
+    for (const file of new Set(truth)) {
+        const r = inRanked.has(file);
+        const i = inImpacted.has(file);
+        if (r && i)
+            both++;
+        else if (r)
+            rankedOnly++;
+        else if (i)
+            impactOnly++;
+        // Found by neither: counted nowhere. It is a miss, and the recall metrics already say so.
+    }
+    return { rankedOnly, impactOnly, both };
+}

package/dist/holmes/review/graph-verifier.d.ts

@@ -0,0 +1,34 @@
+import type { ScannedFile } from '../cpg/cpg-scanner';
+/**
+ * The graph used to CHECK a candidate rather than to find one.
+ *
+ * Ten mechanisms have been measured and every one used the graph additively — follow a neighbour,
+ * pay a bonus, expand the query. All of them chase recall, all of them were negative, and most of
+ * them cost precision. The other half of the argument is the opposite operation: let the lexical
+ * layer propose, and let the graph decide which proposals it can corroborate.
+ *
+ * Corroboration here is deliberately weak — a call edge either way, or a shared spec anchor, between
+ * a candidate and the top-ranked file. It is a demotion and never a deletion: this graph is
+ * incomplete by construction (its own coverage numbers say so), and removing a file because the
+ * graph fails to connect it would turn a gap in the extractor into a wrong answer.
+ */
+export interface VerifierOptions {
+    /** How much an uncorroborated candidate keeps. 1 is a no-op; 0 would be deletion by another name. */
+    demotion: number;
+}
+/** Files reachable from `seed` by a call edge in either direction, or by a shared spec anchor. */
+export declare function corroborated(seed: string, scanned: readonly ScannedFile[]): Set<string>;
+/**
+ * Demote candidates the graph cannot connect to the top-ranked one.
+ *
+ * The top candidate is taken as the anchor of the answer, which is the assumption that makes this
+ * cheap and also the one that can sink it: if the first hit is wrong, corroboration is measured
+ * against the wrong place. That is why the demotion is partial and the list is never truncated.
+ */
+export declare function verifyByGraph(ranked: readonly {
+    file: string;
+    score: number;
+}[], scanned: readonly ScannedFile[], opts: VerifierOptions): {
+    file: string;
+    score: number;
+}[];