@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/rtm/localize.js

@@ -1,7 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.citationsIn = citationsIn;
 exports.significantTerms = significantTerms;
+exports.bigramUnspaced = bigramUnspaced;
 exports.localizeIssue = localizeIssue;
+/**
+ * @implements A-SPEC-273
+ * Explicit spec references inside request text: `A-SPEC-262.1`, `REQ-267`, `T-SPEC-121.2`, and this
+ * repository's `S-<n>` slice shorthand (which names the whole REQ->T-SPEC chain at that number).
+ * The prefix is REQUIRED — a bare `262` in "262 files were rewritten" is a number, not a citation.
+ */
+const CITATION = /\b(?:(A-SPEC|H-SPEC|T-SPEC|C-SPEC|REQ)-(\d+(?:\.\d+)?)|S-(\d+(?:\.\d+)?))\b/gi;
+const CITABLE_KINDS = ['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC', 'C-SPEC'];
+/**
+ * @implements A-SPEC-273
+ * How much a citation is worth, normalized by the file's anchor count exactly as the lexical spec
+ * bonus is (A-SPEC-270). Chosen by measurement on the 12-commit replay corpus, not by taste: see
+ * the sweep recorded in docs/holmes-kit-activation.md.
+ */
+const CITATION_BONUS = 20;
+// @implements A-SPEC-349
+// Exported so the Phase C measurement arm shares this exact path rather than reimplementing it.
+// A second citation extractor would drift from this one, and the drift would show up in the replay
+// as a difference between RANKERS — the one thing the arm exists to measure.
+function citationsIn(text, known) {
+    const cited = new Set();
+    const unknown = new Set();
+    for (const m of text.matchAll(CITATION)) {
+        if (m[1]) {
+            const id = `${m[1].toUpperCase()}-${m[2]}`;
+            (known.has(id) ? cited : unknown).add(id);
+            continue;
+        }
+        // `S-<n>` names a slice, not one document: expand to every kind at that number that EXISTS.
+        const resolved = CITABLE_KINDS.map((kind) => `${kind}-${m[3]}`).filter((id) => known.has(id));
+        if (resolved.length > 0)
+            resolved.forEach((id) => cited.add(id));
+        else
+            unknown.add(`S-${m[3]}`);
+    }
+    return { cited: [...cited].sort(), unknown: [...unknown].sort() };
+}
 const STOP = new Set([
     'the', 'and', 'for', 'with', 'that', 'this', 'when', 'then', 'from', 'into', 'not', 'but', 'are',
     'was', 'were', 'have', 'has', 'had', 'does', 'did', 'should', 'would', 'could', 'will', 'can',
@@ -22,18 +61,113 @@ function significantTerms(text) {
         .replace(/([a-z0-9])([A-Z])/g, '$1 $2') // camelCase -> camel Case
         .toLowerCase()
         .split(/[^\p{L}\p{N}]+/u)
+        .flatMap(bigramUnspaced)
         .filter((t) => {
         const minLen = /[^\x00-\x7f]/.test(t) ? 2 : 3;
         return t.length >= minLen && !STOP.has(t);
     });
     return [...new Set(raw)].slice(0, MAX_TERMS);
 }
+/**
+ * @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.
+ */
+function bigramUnspaced(token) {
+    if (token.length < 2 || !UNSPACED_SCRIPT.test(token))
+        return [token];
+    const out = [];
+    for (let i = 0; i + 1 < token.length; i++)
+        out.push(token.slice(i, i + 2));
+    return out;
+}
+/** Han, Hiragana, Katakana — the scripts in these corpora that carry no word spacing. */
+const UNSPACED_SCRIPT = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u;
 const tokensOf = (s) => new Set(significantTerms(s));
+/**
+ * @implements A-SPEC-350
+ * How much one matching term is worth, given how common it is in THIS corpus.
+ *
+ * Every term used to be worth the same, so a match on `spec` — a token in nearly every file of this
+ * repository — counted exactly as heavily as a match on a name that occurs once. No global stop-list
+ * can fix that: the ubiquitous vocabulary is a property of the corpus, not of the language.
+ *
+ * Rescaled to mean 1, so the lexical term keeps its magnitude relative to the spec-anchor (+4) and
+ * citation (+20) bonuses and only its DISTRIBUTION across terms changes. An unseen term weighs 1:
+ * a word absent from the corpus is not evidence against a file, and mapping it to 0 would delete a
+ * request's most distinctive vocabulary — the words most likely to name something new.
+ *
+ * @implements A-SPEC-361
+ * Memoised on the scanned array's IDENTITY. Measured at 365 files / 2907 symbols: this pass is 5.0ms
+ * of a 9.0ms localize call — 56% — and grows linearly with the corpus (4x corpus, 3.2x time). The
+ * absolute cost is small and the worry that prompted the measurement was not borne out, but over
+ * half a call is worth not repeating when a caller localizes several requests against one scan.
+ *
+ * A WeakMap keyed on the array is chosen over a keyed cache precisely because it CANNOT go stale: a
+ * fresh scan produces a fresh array, so a changed corpus can never hit a previous entry, and there
+ * is no invalidation step for someone to forget. Stale weights would silently reorder results, which
+ * is the failure mode this repository would find hardest to notice.
+ */
+const WEIGHT_CACHE = new WeakMap();
+function termWeights(scanned) {
+    const cached = WEIGHT_CACHE.get(scanned);
+    if (cached)
+        return cached;
+    const computed = computeTermWeights(scanned);
+    WEIGHT_CACHE.set(scanned, computed);
+    return computed;
+}
+function computeTermWeights(scanned) {
+    const df = new Map();
+    for (const f of scanned) {
+        const seen = new Set(tokensOf(f.sourcePath));
+        for (const sym of f.symbols)
+            for (const t of tokensOf(sym.qualifiedName))
+                seen.add(t);
+        for (const t of seen)
+            df.set(t, (df.get(t) ?? 0) + 1);
+    }
+    const n = scanned.length;
+    const raw = new Map();
+    for (const [t, d] of df)
+        raw.set(t, Math.max(Math.log((n + 1) / (d + 1)), 1e-6));
+    const vals = [...raw.values()];
+    if (vals.length === 0)
+        return raw;
+    const mean = vals.reduce((a, b) => a + b, 0) / vals.length;
+    if (mean <= 0)
+        return new Map([...raw.keys()].map((t) => [t, 1]));
+    const out = new Map();
+    for (const [t, v] of raw)
+        out.set(t, v / mean);
+    return out;
+}
 function localizeIssue(issueText, scanned, specs, topN = 10) {
     const terms = significantTerms(issueText);
-    if (terms.length === 0)
-        return { terms: [], hits: [], matchedSpecs: [] };
+    // @implements A-SPEC-273 — citations are recovered BEFORE the lexical gate: `significantTerms`
+    // shreds `S-262.1` into the bare token `262`, so a request that names its spec outright can never
+    // be recovered lexically, however many terms it has.
+    const citations = citationsIn(issueText, new Set(specs.map((s) => s.id)));
+    const citedSet = new Set(citations.cited);
+    if (terms.length === 0 && citations.cited.length === 0) {
+        return { terms: [], hits: [], matchedSpecs: [], unknownCitations: citations.unknown };
+    }
     const termSet = new Set(terms);
+    // @implements A-SPEC-350
+    const weights = termWeights(scanned);
+    const weightOf = (t) => weights.get(t) ?? 1;
     // 1) A-SPECs whose title/section text shares terms with the issue (RTM entry points). Restricted
     //    to A-SPEC: files anchor A-SPECs only, so other spec kinds can never pull a file through the
     //    hop and reporting them overstated what influenced the ranking (review D7). Threshold (review
@@ -45,13 +179,50 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
             continue;
         const specText = `${s.title} ${Object.values(s.sections).join(' ')}`;
         const st = tokensOf(specText);
-        let overlap = 0;
+        // @implements A-SPEC-353
+        // Weighed, not counted. This is the entry point into the knowledge graph, and an admitted spec
+        // pays its bonus to EVERY file anchoring it — so a spec opened by two ubiquitous words promotes
+        // a whole group of unrelated files at once. Threshold 1 means "one term of average rarity, or
+        // several common ones". Measured over both corpora at thresholds 0.5/1/2/3: 1 was the only
+        // setting that improved BOTH (this repository Top-1 0.317 -> 0.333, Top-10 recall 0.754 ->
+        // 0.770; jarvis 0.333 -> 0.367 and 0.662 -> 0.684).
+        let mass = 0;
         for (const t of termSet)
             if (st.has(t))
-                overlap++;
-        if (overlap >= 2 || (overlap === 1 && termSet.size <= 3))
+                mass += weightOf(t);
+        // The short-request escape hatch is unchanged: a three-word request cannot reach a threshold
+        // built for prose, and removing it here would change two things at once.
+        if (mass >= 1 || (mass > 0 && termSet.size <= 3))
             matchedSpecs.push(s.id);
     }
+    // A cited spec is matched by fiat: the request named it, which is stronger evidence than any
+    // amount of word overlap.
+    // @implements A-SPEC-373
+    // A request that names no spec, yet matches a crowd of them, has identified nothing — it was
+    // written in words the corpus uses everywhere. Measured over 60 point-in-time cases: uncited, this
+    // ranker scored Top-10 recall 0.275 against 0.357 for matching the request's words against paths
+    // and symbols alone, and precision 0.067 against 0.122. That is the condition every incoming bug
+    // report is in.
+    //
+    // 26.6 A-SPECs match lexically per case here. A hub file anchoring many of them collects
+    // 4·n/sqrt(n) = 4·sqrt(n), which GROWS with the crowd — twelve matches outrank any lexical hit.
+    // With a citation present its +20 dominates and the crowd is corroborated rather than speculative
+    // (dropping it there cost 0.770 → 0.743), so the cap applies only when nothing was cited. A SMALL
+    // uncited crowd is still evidence: the second corpus matches 0.87 specs per case and gains from
+    // them, and capping it there threw away its only lead.
+    // @implements A-SPEC-399
+    // The cap is gone, and the reason is that A-SPEC-399 removed what it was protecting against.
+    // It existed because a crowd of lexically-matched specs ADMITTED a crowd of files and buried the
+    // lexical ranking. Now a spec cannot admit anything while the request has lexical purchase, so the
+    // crowd can only reorder files that earned their place — and measured, keeping the cap alongside
+    // the admission rule cost Top-1 (0.267 -> 0.222, below the 0.244 baseline) while the arm without
+    // it held 0.267 at the same recovered precision.
+    //
+    // The cap remains correct for what it was measured on and is superseded rather than reverted: its
+    // job is now done by a narrower rule that does not also discard the reordering.
+    for (const id of citations.cited)
+        if (!matchedSpecs.includes(id))
+            matchedSpecs.push(id);
     const matchedSpecSet = new Set(matchedSpecs);
     // Vendored/mirrored trees (review D4): an identical copy under reference/vendor must not outrank —
     // or lexically tie-break above — the live source. Their scores are halved and ties break toward
@@ -59,6 +230,24 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
     const isVendorPath = (p) => /(^|\/)(reference|vendor|vendors|third_party|third-party|external)\//i.test(p);
     // 2) Score each scanned file: symbol-name matches (strong), path matches (weak),
     //    implements-a-matched-spec (graph bonus the lexical layer cannot see).
+    // @implements A-SPEC-399
+    // Does the request get ANY lexical purchase on this corpus? A commit subject shares words with
+    // symbol names and paths; a request written in the project's documentation language — Korean specs
+    // against English symbols here — shares none at all. The difference is visible from the query, and
+    // it is exactly the difference between the two cases that pulled A-SPEC-398 apart.
+    const anyLexicalPurchase = scanned.some((f) => {
+        for (const sym of f.symbols) {
+            const st = tokensOf(sym.qualifiedName);
+            for (const t of termSet)
+                if (st.has(t))
+                    return true;
+        }
+        const pt = tokensOf(f.sourcePath);
+        for (const t of termSet)
+            if (pt.has(t))
+                return true;
+        return false;
+    });
     const hits = [];
     for (const f of scanned) {
         const why = [];
@@ -68,7 +257,12 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
             const symTokens = tokensOf(sym.qualifiedName);
             const hitTerms = [...termSet].filter((t) => symTokens.has(t));
             if (hitTerms.length > 0) {
-                score += 3 * hitTerms.length;
+                // @implements A-SPEC-350 — weighted by rarity; `hitTerms.length` was the flat version.
+                // @implements A-SPEC-430 — saturation was TRIED here and reverted; see review notes. The
+                // flat sum is kept because saturating it cost this repository's clean-slice Top-5 recall
+                // (0.509 -> 0.493) while buying nothing on the corpus it was designed for.
+                for (const t of hitTerms)
+                    score += 3 * weightOf(t);
                 matchedSymbols.push(sym.qualifiedName);
                 why.push(`symbol ${sym.qualifiedName} matches [${hitTerms.join(', ')}]`);
             }
@@ -76,25 +270,89 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
         const pathTokens = tokensOf(f.sourcePath);
         const pathHits = [...termSet].filter((t) => pathTokens.has(t));
         if (pathHits.length > 0) {
-            score += pathHits.length;
+            // @implements A-SPEC-350
+            for (const t of pathHits)
+                score += weightOf(t);
             why.push(`path matches [${pathHits.join(', ')}]`);
         }
         // Dedupe: a file may carry the same @implements anchor many times (once per code section);
         // each spec must count ONCE toward the bonus (live smoke showed 4x inflation otherwise).
-        const viaSpecs = [...new Set(f.implementsSpecs ?? [])].filter((id) => matchedSpecSet.has(id));
+        // @implements A-SPEC-366
+        // RESOLVED anchors only. The denominator used to count every `@implements` marker written in the
+        // file, including ones naming specs that have been retired, renamed or deleted. Such a marker
+        // supplies no evidence and was taxing the evidence its neighbours do supply: measured, three dead
+        // markers alongside one live one halved the live one's bonus from 4 to 2.
+        //
+        // The dilution A-SPEC-270 introduced is untouched — a file implementing many LIVE specs is still
+        // weaker evidence per spec. This removes only the tax paid to specs that no longer exist.
+        const knownSpecIds = new Set(specs.map((spec) => spec.id));
+        const anchors = [...new Set(f.implementsSpecs ?? [])].filter((id) => knownSpecIds.has(id));
+        const viaSpecs = anchors.filter((id) => matchedSpecSet.has(id));
         if (viaSpecs.length > 0) {
-            score += 4 * viaSpecs.length;
-            why.push(`implements matched spec(s) ${viaSpecs.join(', ')}`);
+            // @implements A-SPEC-270
+            // Normalized by how many anchors the file carries. The raw `4 × matched` grew without bound
+            // as anchors accumulated, and anchors only ever accumulate: a file implementing 113 specs
+            // (handlers.ts, measured 2026-08-28) will brush SOME spec for almost any request, so each
+            // individual match there is far weaker evidence than a lone anchor that matched exactly.
+            // Left unnormalized, every slice that touches a hub file made that file a stronger attractor
+            // for unrelated requests — a precision decay produced by the governance process itself
+            // (authoring one slice moved replay localization recall 0.5476 -> 0.5060, no logic changed).
+            //
+            // sqrt, not the raw fraction: a lone matching anchor keeps its original +4 exactly, while a
+            // hub is diluted rather than erased — it must still be FINDABLE when it really is the target.
+            const specificity = 4 * viaSpecs.length / Math.sqrt(anchors.length);
+            score += Math.round(specificity * 100) / 100;
+            why.push(`implements matched spec(s) ${viaSpecs.join(', ')} (${viaSpecs.length}/${anchors.length} anchors)`);
+        }
+        const citedAnchors = anchors.filter((id) => citedSet.has(id));
+        if (citedAnchors.length > 0) {
+            // Normalized by anchor count for the same reason the lexical spec bonus is (A-SPEC-270):
+            // otherwise a hub file would collect this bonus for every citation anyone ever writes.
+            score += Math.round(CITATION_BONUS * citedAnchors.length / Math.sqrt(anchors.length) * 100) / 100;
+            why.push(`request cites spec(s) ${citedAnchors.join(', ')}`);
         }
         if (isVendorPath(f.sourcePath) && score > 0) {
             score = score / 2;
             why.push('vendored path — score halved');
         }
-        if (score > 0)
+        // @implements A-SPEC-398
+        // NOT admitted-only, and the reason is a measurement colliding with a contract.
+        //
+        // Restricting admission to files with lexical evidence recovered every point of precision the
+        // spec layer costs (0.104 -> 0.156) while keeping its Top-1 gain — measured on both corpora, on
+        // clean history. It also broke six approved tests, and one of them names the reason: this
+        // repository's specs are written in Korean and its symbols in English, so a Korean request
+        // matches specs and shares NO term with any file name. Admission via the spec is the only path
+        // it has, and withholding it makes such a request find nothing at all.
+        //
+        // The measurement and the contract are both right about their own query. Commit subjects overlap
+        // symbol names; a report written in the project's documentation language does not. Adopting on
+        // the first would silently disable the second, so the arm stays measured and unadopted, and what
+        // @implements A-SPEC-399
+        // The query-type test A-SPEC-398 said this needed. When the request has lexical purchase
+        // somewhere in the corpus, a spec may REORDER candidates but not admit them — measured to recover
+        // precision 0.104 -> 0.156 and Top-10 recall 0.651 -> 0.668 while keeping Top-1. When the request
+        // has none — the Korean-spec, English-symbol case — spec admission is its only path, and
+        // withholding it makes such a request find nothing at all.
+        //
+        // A cited spec admits regardless: citation is the strongest signal here (Top-10 recall 0.770
+        // against 0.275), and paying for precision with it would break what works to repair what does not.
+        const lexicalEvidence = matchedSymbols.length > 0 || pathHits.length > 0;
+        const admitted = !anyLexicalPurchase || lexicalEvidence || citedAnchors.length > 0;
+        if (score > 0 && admitted)
             hits.push({ file: f.sourcePath, score, matchedSymbols, viaSpecs, why });
     }
-    hits.sort((a, b) => b.score - a.score ||
-        Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) || // ties: live source before vendor
+    // @implements A-SPEC-272
+    // Vendored-ness is the FIRST key, not a tie-break. Halving the score was the old demotion and it
+    // is not enough where most of the tree is vendored: measured 2026-08-28 on this repository, 212 of
+    // 351 scanned files sit under `reference/`, and 27% of the predicted set (22% of the primary tier)
+    // was third-party code — every one a guaranteed false positive, since a change to THIS project
+    // never edits vendored sources. Ordering by vendored-ness first means a vendored file appears only
+    // once the live candidates are exhausted: demoted, never erased, so it is still findable on a
+    // project where the vendored code really is the answer. The score halving stays, so the relative
+    // order WITHIN each group is unchanged.
+    hits.sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) || // live source before vendored
+        b.score - a.score || // then by evidence strength
         a.file.localeCompare(b.file)); // then deterministic path order
-    return { terms, hits: hits.slice(0, topN), matchedSpecs: matchedSpecs.sort() };
+    return { terms, hits: hits.slice(0, topN), matchedSpecs: matchedSpecs.sort(), unknownCitations: citations.unknown };
 }

package/dist/holmes/rtm/rtm-builder.d.ts

@@ -1,9 +1,55 @@
 import { Spec } from '../spec/spec-parser';
 import { RtmGraph } from './rtm-graph';
 import { ScannedFile } from '../cpg/cpg-scanner';
+/**
+ * @implements A-SPEC-292
+ * What resolution did with every extracted `calls`/`inherits` relation. The graph discards on
+ * purpose — precision over recall — but nothing counted the discards, so an impact answer read as
+ * if the graph were complete.
+ *
+ * `unknownTarget` and `ambiguous` are DIFFERENT facts and are kept apart: an unknown target is
+ * almost always external (a library or runtime call this repository cannot see), while an ambiguous
+ * one names code that IS here and could not be picked. Only the second is a real miss.
+ *
+ * The buckets are produced BY the resolution loop, never by a second copy of the rule — this
+ * codebase has repeatedly paid for the same judgement written twice.
+ */
+export interface ResolutionReport {
+    resolved: number;
+    /** Callee defined in several files: precision-over-recall refused to guess. A real miss. */
+    ambiguous: number;
+    /** Callee defined nowhere in the scan — usually an external package or runtime builtin. */
+    unknownTarget: number;
+    /** Caller name the symbol walk never emitted (see A-SPEC-291). */
+    callerNotNamed: number;
+    selfReference: number;
+    /** `<module>`-scoped relations, which are not symbol-to-symbol. */
+    moduleScoped: number;
+}
 export interface BuildRtmOptions {
     /** Resolve a spec id to its source file path (e.g. its .md file) for provenance tagging. */
     specSourcePath?: (id: string) => string | undefined;
+    /**
+     * @implements A-SPEC-281
+     * The observation context every fact in this build shares: which commit it was read at, which
+     * extractor read it, and WHEN — supplied by the caller, never read from a clock in here, so the
+     * same inputs keep producing the same graph. Per-fact fields (`sourceLocation`, `confidence`,
+     * `derivation`) are decided by the builder, because only it knows whether a fact was declared or
+     * inferred.
+     */
+    provenance?: {
+        sourceCommit?: string;
+        extractorVersion?: string;
+        observedAt?: string;
+        validUntil?: string;
+    };
+    /**
+     * @implements A-SPEC-284
+     * Content digest of a scanned file, supplied by the caller. The builder stays pure — it never
+     * opens a file to compute one — so an absent digest records `null`, the honest mark for "not
+     * recorded", rather than a value nobody measured.
+     */
+    fileDigest?: (sourcePath: string) => string | undefined;
 }
 /**
  * Adds one scanned file's CODE nodes and `implements` edges to the graph,
@@ -11,8 +57,10 @@ export interface BuildRtmOptions {
  * can later drop exactly this file's contribution (used by the incremental
  * orchestrator — see Task 4).
  */
-export declare function buildFileSubgraph(f: ScannedFile, specs: Spec[], graph: RtmGraph): void;
-export declare function buildRtm(specs: Spec[], scanned: ScannedFile[], graph: RtmGraph, opts?: BuildRtmOptions): void;
+export declare function buildFileSubgraph(f: ScannedFile, specs: Spec[], graph: RtmGraph, opts?: BuildRtmOptions): void;
+export declare function buildRtm(specs: Spec[], scanned: ScannedFile[], graph: RtmGraph, opts?: BuildRtmOptions): {
+    resolution: ResolutionReport;
+};
 /**
  * Resolve each file's recovered call relations to graph edges.
  *
@@ -33,7 +81,7 @@ export declare function buildRtm(specs: Spec[], scanned: ScannedFile[], graph: R
  * exact (src,dst,rel) triple — so the first-writer-wins hazard documented on RtmGraph cannot arise
  * for call edges, and `removeBySource(caller)` drops exactly them.
  */
-export declare function addCallEdges(scanned: ScannedFile[], graph: RtmGraph): void;
+export declare function addCallEdges(scanned: ScannedFile[], graph: RtmGraph, opts?: BuildRtmOptions): ResolutionReport;
 /**
  * Bounds on call-edge propagation (REQ-127). Defaults are constants, not laws — a project can tune
  * them, and `explain` reports what each bound actually did.
@@ -99,3 +147,70 @@ export interface ImpactExplanation {
  */
 export declare function impactedBy(graph: RtmGraph, changedSymbolQNames: string[], opts?: ImpactOptions): string[];
 export declare function explainImpact(graph: RtmGraph, changedSymbolQNames: string[], opts?: ImpactOptions): ImpactExplanation;
+/** @implements A-SPEC-284 — one commit as git reports it. */
+export interface CommitRecord {
+    commit: string;
+    date: string;
+    subject: string;
+    files: readonly string[];
+}
+/**
+ * @implements A-SPEC-284
+ * The graph's first temporal layer: `COMMIT:<sha>` nodes and `changed_by` edges to the code they
+ * touched.
+ *
+ * Kept as a SEPARATE ingestion rather than folded into the per-file subgraph. Commit history is not
+ * a product of scanning a file, and entangling it with the incremental path would put the
+ * incremental/full-rebuild convergence A-SPEC-280 proved at risk for no benefit — the code layer
+ * must come out identical whether or not history was ever ingested.
+ *
+ * An edge is emitted ONLY when the changed file is present in the scan. Precision over recall, the
+ * same rule call resolution follows: an edge pointing at a node that does not exist poisons every
+ * traversal that walks it, while a missing edge merely leaves a gap. Commits touching files nobody
+ * scanned are still recorded as nodes — they happened.
+ */
+export declare function addCommitHistory(history: readonly CommitRecord[], scanned: readonly ScannedFile[], graph: RtmGraph, opts?: BuildRtmOptions): void;
+/**
+ * @implements A-SPEC-289
+ * FILE nodes and resolved `imports` edges.
+ *
+ * Import relations were extracted and then dropped, because their endpoints are a file and a module
+ * path while the graph knew only symbols and specs — measured on this repository, 1,892 extracted
+ * and 0 in the graph. `File` is a node kind Goal Phase 3 names, so it becomes one.
+ *
+ * ONLY relative specifiers are resolved, and only to a file the scan actually contains. A bare
+ * specifier (`node:fs`, `js-yaml`) is an external package with no node to point at, and inventing
+ * one would be a guess — the same precision-over-recall rule call resolution follows. Measured: 441
+ * of 1,892 specifiers (23%) resolve inside the repository, and the rest failing to resolve is a
+ * fact about the imports, not a defect in the resolver.
+ */
+export declare function addImportEdges(scanned: readonly ScannedFile[], graph: RtmGraph, opts?: BuildRtmOptions): void;
+/** @implements A-SPEC-293 — one architecture decision as its record states it. */
+export interface DecisionRecord {
+    id: string;
+    title: string;
+    status: string;
+    /** The decision this one replaces, as declared in its frontmatter, or null. */
+    supersedes: string | null;
+}
+/** @implements A-SPEC-293 — "this file/spec cites that ADR", read from the text that cites it. */
+export interface DecisionCitation {
+    /** `FILE:<repo-relative path>` or `SPEC:<id>`. */
+    from: string;
+    adr: string;
+}
+/**
+ * @implements A-SPEC-293
+ * DECISION nodes and the `constrained_by` / `supersedes` edges around them.
+ *
+ * Citation is the link, chosen by measurement rather than by taste: on this repository `governs`
+ * resolves only 9 of its 65 names to symbols (the rest are free-form design concepts), while 37
+ * source files and 71 spec files cite an ADR outright — and a citation sits exactly where the
+ * decision actually bears on the work.
+ *
+ * A citation naming a decision that does not exist creates neither node nor edge: an edge to a node
+ * nobody can open is a guess, the same rule import and call resolution follow. `supersedes` is
+ * declared in frontmatter and linked only when both decisions exist; this repository currently has
+ * none, and the edge kind is supported anyway rather than waiting for the first one.
+ */
+export declare function addDecisionEdges(decisions: readonly DecisionRecord[], citations: readonly DecisionCitation[], graph: RtmGraph, opts?: BuildRtmOptions): void;