@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/review/traceability-benchmark.d.ts

@@ -0,0 +1,81 @@
+import type { Spec } from '../spec/spec-parser';
+import type { ScannedFile } from '../cpg/cpg-scanner';
+/**
+ * The task embeddings are actually claimed to be good at.
+ *
+ * Every benchmark in this work so far asks: given a commit's subject, which files did it change?
+ * Eight semantic mechanisms have been measured against it and all eight were negative. But that is
+ * not the task the semantic-layer argument is about. The argument is about the gap between the words
+ * a requirement is written in and the names the code is written in — a requirement says "erase
+ * personal data on withdrawal", the design says "account deprovisioning", the code says
+ * `revokeCredentials()`. No string matcher crosses that, which is exactly why an embedding might.
+ *
+ * The ground truth for it already exists here: an `@implements` anchor IS a requirement-to-code
+ * link, recorded by the person who wrote the code and verified by the constitution gate.
+ *
+ * **The identifier must be withheld.** A query containing `A-SPEC-350` is answered by the citation
+ * path, which resolves the anchor directly and measures nothing about semantics — it is the same
+ * leak that made the localization numbers look like a retrieval result when they were a commit
+ * convention. The query is the spec's prose with every spec id removed.
+ */
+export interface TraceabilityCase {
+    /** The spec's prose, with every identifier stripped. */
+    query: string;
+    /** Files anchoring this spec — the answer. */
+    truth: string[];
+    /** Kept for reporting only; never given to a ranker. */
+    specId: string;
+}
+/** Strip every spec identifier, so the citation path cannot answer the question. */
+export declare function withholdIdentifiers(text: string): string;
+/**
+ * Cases from a spec store and a scan: one per A-SPEC that at least one file anchors.
+ *
+ * A spec nothing implements has no answer to find, and scoring it would report a failure that no
+ * ranker could have avoided.
+ */
+export declare function traceabilityCases(specs: readonly Spec[], scanned: readonly ScannedFile[]): TraceabilityCase[];
+export interface TraceabilityScore {
+    cases: number;
+    /** Share of cases where any truth file appears in the top K. */
+    hitRate: number | null;
+    /** Mean share of truth files recovered in the top K. */
+    recall: number | null;
+    /** Mean reciprocal rank of the first correct file — how near the top the answer lands. */
+    mrr: number | null;
+}
+export declare function scoreTraceability(cases: readonly TraceabilityCase[], rank: (query: string) => readonly string[], topK: number): TraceabilityScore;
+/**
+ * @implements A-SPEC-383
+ * Which cases a string matcher could possibly answer.
+ *
+ * Dense retrieval lost the traceability benchmark 0.424 to 0.699 — but that average mixes two kinds
+ * of case. Measured over 225 of them, only **9%** of a spec's terms appear anywhere in the names of
+ * the files implementing it, and **24 cases share no term at all**. Where terms do overlap they are
+ * rare ones, and IDF is built to amplify exactly those, so lexical wins. Where NOTHING overlaps, a
+ * string matcher cannot win by any weighting — and that subset is precisely where an embedding is
+ * claimed to be necessary. It has never been scored on its own.
+ *
+ * Splitting the corpus this way is what turns "dense loses on average" into an answerable question:
+ * does it lose everywhere, or does it lose overall while winning where nothing else can reach?
+ */
+export declare function lexicallyReachable(c: TraceabilityCase, fileTerms: (file: string) => ReadonlySet<string>, queryTerms: (text: string) => readonly string[]): boolean;
+/**
+ * @implements A-SPEC-401
+ * Files reached by walking the spec graph from the specs a requirement's prose resembles.
+ *
+ * The Goal is about a NEW or CHANGED requirement being handed to the harness, and every benchmark in
+ * this work has used a commit subject as the query instead. On the requirement task, lexical, BM25
+ * and dense retrieval have all been scored; graph traversal has not.
+ *
+ * The path: requirement prose → the specs whose text it most resembles → their parents and siblings
+ * → the files those anchor. It is the shape the Goal describes, and the shape a person uses when
+ * they say "this is like the thing we did for X, so look where X lives".
+ *
+ * **The target spec is excluded**, without exception. The query IS its prose, so leaving it in the
+ * index returns its own anchors and scores 0.99 — a leak this benchmark has already produced once.
+ */
+export declare function reachThroughSpecGraph(seedSpecIds: readonly string[], specs: readonly {
+    id: string;
+    dependsOn?: string[];
+}[], anchoredFiles: ReadonlyMap<string, readonly string[]>, hops: number): string[];

package/dist/holmes/review/traceability-benchmark.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withholdIdentifiers = withholdIdentifiers;
+exports.traceabilityCases = traceabilityCases;
+exports.scoreTraceability = scoreTraceability;
+exports.lexicallyReachable = lexicallyReachable;
+exports.reachThroughSpecGraph = reachThroughSpecGraph;
+const ID_PATTERN = /\b(?:[AHT]-SPEC|REQ|S)-\d+(?:\.\d+)?\b/gi;
+/** Strip every spec identifier, so the citation path cannot answer the question. */
+function withholdIdentifiers(text) {
+    return text.replace(ID_PATTERN, ' ').replace(/\s{2,}/g, ' ').trim();
+}
+/**
+ * Cases from a spec store and a scan: one per A-SPEC that at least one file anchors.
+ *
+ * A spec nothing implements has no answer to find, and scoring it would report a failure that no
+ * ranker could have avoided.
+ */
+function traceabilityCases(specs, scanned) {
+    const bySpec = new Map();
+    for (const f of scanned) {
+        for (const id of new Set(f.implementsSpecs ?? [])) {
+            (bySpec.get(id) ?? bySpec.set(id, []).get(id)).push(f.sourcePath);
+        }
+    }
+    const cases = [];
+    for (const s of specs) {
+        if (s.type !== 'A-SPEC')
+            continue;
+        const truth = bySpec.get(s.id);
+        if (!truth || truth.length === 0)
+            continue;
+        const query = withholdIdentifiers(`${s.title}. ${Object.values(s.sections).join(' ')}`);
+        if (query.length === 0)
+            continue;
+        cases.push({ query, truth: [...new Set(truth)].sort(), specId: s.id });
+    }
+    return cases.sort((a, b) => a.specId.localeCompare(b.specId));
+}
+function scoreTraceability(cases, rank, topK) {
+    if (cases.length === 0)
+        return { cases: 0, hitRate: null, recall: null, mrr: null };
+    let hits = 0, recallSum = 0, rrSum = 0;
+    for (const c of cases) {
+        const ranked = rank(c.query).slice(0, topK);
+        const truth = new Set(c.truth);
+        const found = ranked.filter((f) => truth.has(f));
+        if (found.length > 0)
+            hits++;
+        recallSum += found.length / c.truth.length;
+        const first = ranked.findIndex((f) => truth.has(f));
+        rrSum += first === -1 ? 0 : 1 / (first + 1);
+    }
+    return {
+        cases: cases.length,
+        hitRate: hits / cases.length,
+        recall: recallSum / cases.length,
+        mrr: rrSum / cases.length,
+    };
+}
+/**
+ * @implements A-SPEC-383
+ * Which cases a string matcher could possibly answer.
+ *
+ * Dense retrieval lost the traceability benchmark 0.424 to 0.699 — but that average mixes two kinds
+ * of case. Measured over 225 of them, only **9%** of a spec's terms appear anywhere in the names of
+ * the files implementing it, and **24 cases share no term at all**. Where terms do overlap they are
+ * rare ones, and IDF is built to amplify exactly those, so lexical wins. Where NOTHING overlaps, a
+ * string matcher cannot win by any weighting — and that subset is precisely where an embedding is
+ * claimed to be necessary. It has never been scored on its own.
+ *
+ * Splitting the corpus this way is what turns "dense loses on average" into an answerable question:
+ * does it lose everywhere, or does it lose overall while winning where nothing else can reach?
+ */
+function lexicallyReachable(c, fileTerms, queryTerms) {
+    const q = queryTerms(c.query);
+    if (q.length === 0)
+        return false;
+    for (const file of c.truth) {
+        const terms = fileTerms(file);
+        for (const t of q)
+            if (terms.has(t))
+                return true;
+    }
+    return false;
+}
+/**
+ * @implements A-SPEC-401
+ * Files reached by walking the spec graph from the specs a requirement's prose resembles.
+ *
+ * The Goal is about a NEW or CHANGED requirement being handed to the harness, and every benchmark in
+ * this work has used a commit subject as the query instead. On the requirement task, lexical, BM25
+ * and dense retrieval have all been scored; graph traversal has not.
+ *
+ * The path: requirement prose → the specs whose text it most resembles → their parents and siblings
+ * → the files those anchor. It is the shape the Goal describes, and the shape a person uses when
+ * they say "this is like the thing we did for X, so look where X lives".
+ *
+ * **The target spec is excluded**, without exception. The query IS its prose, so leaving it in the
+ * index returns its own anchors and scores 0.99 — a leak this benchmark has already produced once.
+ */
+function reachThroughSpecGraph(seedSpecIds, specs, anchoredFiles, hops) {
+    const known = new Set(specs.map((s) => s.id));
+    const adj = new Map();
+    const link = (a, b) => {
+        (adj.get(a) ?? adj.set(a, new Set()).get(a)).add(b);
+        (adj.get(b) ?? adj.set(b, new Set()).get(b)).add(a);
+    };
+    for (const s of specs)
+        for (const parent of s.dependsOn ?? [])
+            if (known.has(parent))
+                link(s.id, parent);
+    const seen = new Set(seedSpecIds.filter((id) => known.has(id)));
+    let wave = [...seen];
+    for (let k = 0; k < hops && wave.length > 0; k++) {
+        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;
+    }
+    // Order is seed-first: a file anchored by a spec the request actually resembles is stronger
+    // evidence than one reached two hops away, and a flat set would throw that away.
+    const out = [];
+    for (const id of [...seedSpecIds, ...seen]) {
+        for (const file of anchoredFiles.get(id) ?? [])
+            if (!out.includes(file))
+                out.push(file);
+    }
+    return out;
+}

package/dist/holmes/review/union-verify.d.ts

@@ -0,0 +1,12 @@
+export declare const DEFAULT_SEM_TAUS: readonly number[];
+export declare function semTauGrid(injected?: readonly number[]): readonly number[];
+/** Keep the top `guard` unconditionally; past the guard, keep exactly what `accept` affirms. */
+export declare function verifyEmission(files: readonly string[], accept: (f: string) => boolean, guard: number): string[];
+/** Cosine-vs-query acceptor, inclusive at tau. Null query → no-op; null doc → keep. */
+export declare function semAcceptor(queryVec: readonly number[] | null, docVecOf: (f: string) => readonly number[] | null, tau: number): (f: string) => boolean;
+/**
+ * IDF-weighted token overlap, normalized by the subject's own mass (0..1). A token the IDF
+ * table has never seen weighs 1.0 — an unknown term is maximally distinctive, not weightless.
+ */
+export declare function lexPoverty(subjectTokens: ReadonlySet<string>, top1Tokens: ReadonlySet<string>, tau: number): boolean;
+export declare function lexScore(subjectTokens: ReadonlySet<string>, fileTokens: ReadonlySet<string>, idf: ReadonlyMap<string, number>): number;

package/dist/holmes/review/union-verify.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SEM_TAUS = void 0;
+exports.semTauGrid = semTauGrid;
+exports.verifyEmission = verifyEmission;
+exports.semAcceptor = semAcceptor;
+exports.lexPoverty = lexPoverty;
+exports.lexScore = lexScore;
+// @implements A-SPEC-479
+/**
+ * Pre-emission candidate verification — the pure half of the S-497 measurement arm.
+ *
+ * The L3 bottleneck is one number: union precision 0.167 against a modeled human ≈0.9±. S-488
+ * proved the ceiling is structural for rank-mass alone (tightening the cut saturates at head
+ * accuracy), so the next lever is an INDEPENDENT verdict per candidate before emission — the
+ * cognitive step the human model locates its precision in.
+ *
+ * Two contracts carry measured lessons:
+ *  - No position budget inside the verdict (budgeted judgments flip with position). The only
+ *    positional device is the explicit head guard, a separate axis of the sweep — the defense
+ *    against the ranker-deletes-its-own-answer failure.
+ *  - Verification unavailable is not rejection: a candidate without a vector is KEPT. Recall is
+ *    spent only where the signal actually spoke.
+ */
+const dense_retrieval_1 = require("./dense-retrieval");
+// @implements A-SPEC-484 — the sem τ grid is injectable because absolute cosines are a MODEL
+// trait (bge-m3 masses below 0.5 where gemini's true matches sit at 0.73–0.78); the default is
+// frozen so an uninjected run reproduces S-497 key-for-key.
+exports.DEFAULT_SEM_TAUS = [0.4, 0.5, 0.6, 0.7];
+function semTauGrid(injected) {
+    return injected ?? exports.DEFAULT_SEM_TAUS;
+}
+/** Keep the top `guard` unconditionally; past the guard, keep exactly what `accept` affirms. */
+function verifyEmission(files, accept, guard) {
+    return files.filter((f, i) => i < guard || accept(f));
+}
+/** Cosine-vs-query acceptor, inclusive at tau. Null query → no-op; null doc → keep. */
+function semAcceptor(queryVec, docVecOf, tau) {
+    return (f) => {
+        if (queryVec === null)
+            return true;
+        const dv = docVecOf(f);
+        if (dv === null)
+            return true;
+        return (0, dense_retrieval_1.cosine)(queryVec, dv) >= tau;
+    };
+}
+/**
+ * IDF-weighted token overlap, normalized by the subject's own mass (0..1). A token the IDF
+ * table has never seen weighs 1.0 — an unknown term is maximally distinctive, not weightless.
+ */
+// @implements A-SPEC-488 — the lexical-poverty predicate for gate simulation: uniform-weight
+// coverage of the subject's terms by the product's TOP-1 candidate, strictly below tau. Uniform
+// (an empty IDF table) on purpose — an absolute threshold must not inherit corpus scale. An
+// empty subject asked nothing lexically, so it is never "poor".
+function lexPoverty(subjectTokens, top1Tokens, tau) {
+    if (subjectTokens.size === 0)
+        return false;
+    return lexScore(subjectTokens, top1Tokens, new Map()) < tau;
+}
+function lexScore(subjectTokens, fileTokens, idf) {
+    let hit = 0, total = 0;
+    for (const t of subjectTokens) {
+        const w = idf.get(t) ?? 1.0;
+        total += w;
+        if (fileTokens.has(t))
+            hit += w;
+    }
+    return total === 0 ? 0 : hit / total;
+}

package/dist/holmes/rtm/graph-store.d.ts

@@ -0,0 +1,51 @@
+import { RtmGraph } from './rtm-graph';
+import type { ScannedFile } from '../cpg/cpg-scanner';
+/**
+ * Safe reuse of a persisted graph.
+ *
+ * Measured 2026-08-28 on this repository: the scan cache already makes a warm scan cost 37–46ms
+ * while building the graph costs 161ms, so **81% of the warm path is graph construction** and
+ * reopening a stored graph costs 0ms. Persistence is therefore worth real time — and the whole
+ * difficulty is not the caching, it is the INVALIDATION. A stale graph answering questions is
+ * exactly the failure Goal completion criterion 6 forbids: an incomplete or out-of-date graph must
+ * never be mistaken for "no impact".
+ *
+ * So reuse is allowed only when every field of the basis still matches, and a mismatch names the
+ * field that moved.
+ */
+export interface GraphBasis {
+    /** Bumped whenever the node/edge schema changes, so an old file is never read with new assumptions. */
+    graphSchema: string;
+    extractorVersion: string;
+    sourceCommit: string;
+    specFingerprint: string;
+    /**
+     * Digest of the scan the graph was built from. This is the field that actually protects the cache:
+     * an uncommitted edit does NOT move HEAD, so `sourceCommit` alone would happily reuse a graph
+     * describing content the working tree no longer has — the same trap A-SPEC-277 found one layer up
+     * when HEAD-only drift detection missed a modified target file.
+     */
+    scanDigest: string;
+}
+/**
+ * Content address of a scan: every file's path and its symbols/edges, sorted so the digest depends
+ * on the scan's CONTENT and not on the order the scanner happened to walk the tree in.
+ */
+export declare function scanDigest(scanned: readonly ScannedFile[]): string;
+export interface OpenedGraph {
+    graph: RtmGraph;
+    /** True only when the stored graph's basis matches in every field. */
+    reusable: boolean;
+    /** Why it could not be reused, naming the field that moved. Null when it was reused. */
+    reason: string | null;
+    /** Record the basis for this graph's CURRENT contents. Call after building. */
+    commitBasis(): void;
+}
+/**
+ * Open the graph at `dbPath`, reusing its contents only if `expected` still holds.
+ *
+ * Never throws for a bad cache. An unreadable or corrupt file is a reason to REBUILD, not a reason
+ * to fail: the caller always receives a usable graph, empty when the stored one could not be
+ * trusted, so "the cache is broken" degrades to "this call is slower" rather than to an outage.
+ */
+export declare function openReusableGraph(dbPath: string, expected: GraphBasis): OpenedGraph;

package/dist/holmes/rtm/graph-store.js

@@ -0,0 +1,122 @@
+"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.scanDigest = scanDigest;
+exports.openReusableGraph = openReusableGraph;
+// @implements A-SPEC-282
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const rtm_graph_1 = require("./rtm-graph");
+const BASIS_FIELDS = [
+    'graphSchema', 'extractorVersion', 'sourceCommit', 'specFingerprint', 'scanDigest',
+];
+/**
+ * Content address of a scan: every file's path and its symbols/edges, sorted so the digest depends
+ * on the scan's CONTENT and not on the order the scanner happened to walk the tree in.
+ */
+function scanDigest(scanned) {
+    const lines = scanned
+        .map((f) => {
+        const symbols = f.symbols.map((s) => `${s.qualifiedName}:${s.startLine}-${s.endLine}`).sort().join(',');
+        const edges = (f.edges ?? []).map((e) => `${e.from}->${e.to}:${e.rel}`).sort().join(',');
+        const implemented = [...(f.implementsSpecs ?? [])].sort().join(',');
+        return `${f.sourcePath}|${implemented}|${symbols}|${edges}`;
+    })
+        .sort();
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(lines.join('\n')).digest('hex')}`;
+}
+function readStoredBasis(graph) {
+    try {
+        const rows = graph.readMeta();
+        return Object.keys(rows).length > 0 ? rows : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Open the graph at `dbPath`, reusing its contents only if `expected` still holds.
+ *
+ * Never throws for a bad cache. An unreadable or corrupt file is a reason to REBUILD, not a reason
+ * to fail: the caller always receives a usable graph, empty when the stored one could not be
+ * trusted, so "the cache is broken" degrades to "this call is slower" rather than to an outage.
+ */
+function openReusableGraph(dbPath, expected) {
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    let graph;
+    let reason = null;
+    try {
+        graph = new rtm_graph_1.RtmGraph(dbPath);
+    }
+    catch {
+        // Corrupt beyond opening: replace the file outright and carry on with an empty graph.
+        try {
+            fs.rmSync(dbPath, { force: true });
+        }
+        catch { /* best effort */ }
+        graph = new rtm_graph_1.RtmGraph(dbPath);
+        reason = 'stored graph was unreadable (corrupt file replaced)';
+    }
+    if (!reason) {
+        let stored;
+        try {
+            stored = readStoredBasis(graph);
+        }
+        catch {
+            stored = null;
+            reason = 'stored graph was unreadable (corrupt metadata)';
+        }
+        if (!reason) {
+            if (!stored)
+                reason = 'no stored basis — nothing to reuse';
+            else {
+                const moved = BASIS_FIELDS.find((field) => stored[field] !== expected[field]);
+                if (moved)
+                    reason = `${moved} changed since the stored graph was built`;
+            }
+        }
+    }
+    const commitBasis = () => {
+        graph.writeMeta(Object.fromEntries(BASIS_FIELDS.map((f) => [f, expected[f]])));
+    };
+    if (reason) {
+        // Not reusable means EMPTY. Handing back a partially-stale graph would be worse than no cache:
+        // the caller would build on top of facts whose basis it has just been told it cannot trust.
+        graph.clear();
+        return { graph, reusable: false, reason, commitBasis };
+    }
+    return { graph, reusable: true, reason: null, commitBasis };
+}

package/dist/holmes/rtm/incremental.d.ts

@@ -1,4 +1,5 @@
 import { RtmGraph } from './rtm-graph';
+import { type BuildRtmOptions } from './rtm-builder';
 import { Spec } from '../spec/spec-parser';
 import { ScannedFile } from '../cpg/cpg-scanner';
 /** Paths are repo-relative POSIX paths. */
@@ -25,6 +26,18 @@ export interface ChangeSet {
  * operation is idempotent: re-applying the same ChangeSet has no net effect
  * beyond the first application.
  *
+ * CALL EDGES (A-SPEC-280). Measured 2026-08-28: without `allScanned` this function produced a graph
+ * that did NOT converge with a full rebuild — `buildFileSubgraph` emits nodes and `implements` edges
+ * only, so every call edge was simply missing, and `rtm_reindex` shipped that. Worse, call
+ * resolution is GLOBAL — a name resolves only when exactly one file across the whole scan defines it
+ * — so adding a file can invalidate a call edge owned by a file that did not change, and deleting
+ * one can make a previously-ambiguous call resolvable. No file-local update can see either.
+ *
+ * So when `allScanned` is supplied the call relation is cleared and re-resolved over the whole scan.
+ * That is honest about the cost: incremental saves the PARSE, not the call resolution. When it is
+ * not supplied the returned `callEdgesResolved: false` says so, because a caller that silently
+ * receives a graph missing a whole edge kind is exactly the failure this slice was written to end.
+ *
  * SPEC-file changes (paths under .ax/specs/) are out of scope here: scanOne
  * returns null for non-code files, so only their removeBySource side (a
  * no-op, since SPEC nodes are keyed on the spec's own sourcePath — see
@@ -35,4 +48,15 @@ export declare function applyIncremental(graph: RtmGraph, changes: ChangeSet, ct
     repoRoot: string;
     specs: Spec[];
     scanOne: (relPath: string) => ScannedFile | null;
-}): void;
+    /** Every file in the current scan. Required for the graph to converge with a full rebuild. */
+    allScanned?: () => ScannedFile[];
+    /**
+     * @implements A-SPEC-281
+     * The SAME build options the full build would use. Provenance is part of the graph's value, so
+     * an incremental update that omits it diverges from a full rebuild in exactly the way
+     * A-SPEC-280's missing call edges did — invisibly, until something compares whole values.
+     */
+    buildOptions?: BuildRtmOptions;
+}): {
+    callEdgesResolved: boolean;
+};

package/dist/holmes/rtm/incremental.js

@@ -16,6 +16,18 @@ const rtm_builder_1 = require("./rtm-builder");
  * operation is idempotent: re-applying the same ChangeSet has no net effect
  * beyond the first application.
  *
+ * CALL EDGES (A-SPEC-280). Measured 2026-08-28: without `allScanned` this function produced a graph
+ * that did NOT converge with a full rebuild — `buildFileSubgraph` emits nodes and `implements` edges
+ * only, so every call edge was simply missing, and `rtm_reindex` shipped that. Worse, call
+ * resolution is GLOBAL — a name resolves only when exactly one file across the whole scan defines it
+ * — so adding a file can invalidate a call edge owned by a file that did not change, and deleting
+ * one can make a previously-ambiguous call resolvable. No file-local update can see either.
+ *
+ * So when `allScanned` is supplied the call relation is cleared and re-resolved over the whole scan.
+ * That is honest about the cost: incremental saves the PARSE, not the call resolution. When it is
+ * not supplied the returned `callEdgesResolved: false` says so, because a caller that silently
+ * receives a graph missing a whole edge kind is exactly the failure this slice was written to end.
+ *
  * SPEC-file changes (paths under .ax/specs/) are out of scope here: scanOne
  * returns null for non-code files, so only their removeBySource side (a
  * no-op, since SPEC nodes are keyed on the spec's own sourcePath — see
@@ -27,7 +39,7 @@ function applyIncremental(graph, changes, ctx) {
         graph.removeBySource(f);
         const sf = ctx.scanOne(f);
         if (sf)
-            (0, rtm_builder_1.buildFileSubgraph)(sf, ctx.specs, graph);
+            (0, rtm_builder_1.buildFileSubgraph)(sf, ctx.specs, graph, ctx.buildOptions);
     };
     for (const f of changes.deleted) {
         graph.removeBySource(f);
@@ -42,4 +54,9 @@ function applyIncremental(graph, changes, ctx) {
     for (const f of changes.modified) {
         replaceFile(f);
     }
+    if (!ctx.allScanned)
+        return { callEdgesResolved: false };
+    graph.removeEdgesByRel('calls');
+    (0, rtm_builder_1.addCallEdges)(ctx.allScanned(), graph, ctx.buildOptions);
+    return { callEdgesResolved: true };
 }

package/dist/holmes/rtm/localize.d.ts

@@ -25,7 +25,17 @@ export interface LocalizationReport {
     terms: string[];
     hits: LocalizationHit[];
     matchedSpecs: string[];
+    /**
+     * @implements A-SPEC-273
+     * Spec ids the request cited that the store does NOT contain. Reported rather than dropped: a
+     * request citing a spec nobody can find is a fact about the request worth surfacing.
+     */
+    unknownCitations: string[];
 }
+export declare function citationsIn(text: string, known: ReadonlySet<string>): {
+    cited: string[];
+    unknown: string[];
+};
 /**
  * Significant tokens of the text, UNICODE-aware (review D2: the old [^a-z0-9] split dropped every
  * non-ASCII codepoint, so Korean issue text — and this repo's Korean spec titles — tokenized to
@@ -33,4 +43,22 @@ export interface LocalizationReport {
  * camelCase/snake are split; Latin tokens need length>=3, non-ASCII (e.g. Korean) length>=2.
  */
 export declare function significantTerms(text: string): string[];
+/**
+ * @implements A-SPEC-400
+ * Character bigrams for scripts that do not space their words.
+ *
+ * Measured before this existed: every script that separates words with spaces tokenized correctly —
+ * Korean 4 tokens, German 7, Spanish 6, Russian 6, Arabic 6, French 5 — while Japanese and Chinese
+ * produced ONE token, the entire sentence, because splitting on non-letters found nothing to split.
+ * A single token matches nothing, so those requests reached no code at all. That is a missing
+ * capability for two major languages rather than a ranking shortfall.
+ *
+ * Bigrams are the standard answer for unsegmented scripts and need no dictionary: `隔離処理` yields
+ * `隔離`, `離処`, `処理`, one of which will overlap a spec that discusses the same subject.
+ *
+ * Scoped by SCRIPT, not by "is it non-ASCII". Korean spaces its words and already tokenized into
+ * meaningful units; bigramming it would shred those into fragments and make six working languages pay
+ * for two broken ones. Han, Hiragana and Katakana only.
+ */
+export declare function bigramUnspaced(token: string): string[];
 export declare function localizeIssue(issueText: string, scanned: ScannedFile[], specs: Spec[], topN?: number): LocalizationReport;