@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/rtm/rtm-builder.js

@@ -1,4 +1,37 @@
 "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.DEFAULT_IMPACT = void 0;
 exports.buildFileSubgraph = buildFileSubgraph;
@@ -6,6 +39,28 @@ exports.buildRtm = buildRtm;
 exports.addCallEdges = addCallEdges;
 exports.impactedBy = impactedBy;
 exports.explainImpact = explainImpact;
+exports.addCommitHistory = addCommitHistory;
+exports.addImportEdges = addImportEdges;
+exports.addDecisionEdges = addDecisionEdges;
+const path = __importStar(require("node:path"));
+const language_capability_1 = require("../cpg/language-capability");
+/**
+ * @implements A-SPEC-281
+ * Build one fact's provenance from the shared observation context plus what this call site knows.
+ * `confidence: null` for an inferred fact is deliberate — see `Provenance` in rtm-graph.ts.
+ */
+function fact(opts, sourceLocation, derivation, confidence, evidenceDigest = null) {
+    return {
+        sourceCommit: opts?.provenance?.sourceCommit ?? null,
+        extractorVersion: opts?.provenance?.extractorVersion ?? null,
+        sourceLocation,
+        confidence,
+        evidenceDigest,
+        observedAt: opts?.provenance?.observedAt ?? null,
+        validUntil: opts?.provenance?.validUntil ?? null,
+        derivation,
+    };
+}
 /**
  * Adds one scanned file's CODE nodes and `implements` edges to the graph,
  * tagged with that file's sourcePath so RtmGraph.removeBySource(f.sourcePath)
@@ -13,16 +68,18 @@ exports.explainImpact = explainImpact;
  * orchestrator — see Task 4).
  */
 // @implements A-SPEC-121.2
-function buildFileSubgraph(f, specs, graph) {
+function buildFileSubgraph(f, specs, graph, opts) {
     for (const sym of f.symbols) {
         // A-SPEC-121.3: fold source_path into the node id itself so same-named
         // symbols in different files get distinct CODE nodes instead of
         // colliding on a bare `CODE:<qualifiedName>` id (see RtmGraph's class
         // comment). Resolve a bare qn back to these ids via `graph.codeNodeIds`.
         const codeId = `CODE:${sym.qualifiedName}@${f.sourcePath}`;
-        graph.addNode(codeId, 'CODE', f.sourcePath);
+        const digest = opts?.fileDigest?.(f.sourcePath) ?? null;
+        graph.addNode(codeId, 'CODE', f.sourcePath, fact(opts, `${f.sourcePath}:${sym.startLine}`, 'ast-scan', 1, digest));
         for (const aspec of f.implementsSpecs) {
-            graph.addEdge(codeId, `SPEC:${aspec}`, 'implements', f.sourcePath);
+            // DECLARED by an `@implements` anchor: the fact is stated in the file, not inferred.
+            graph.addEdge(codeId, `SPEC:${aspec}`, 'implements', f.sourcePath, fact(opts, `${f.sourcePath}:${sym.startLine}`, 'anchor', 1, digest));
         }
     }
 }
@@ -31,22 +88,28 @@ function buildRtm(specs, scanned, graph, opts) {
     // ONE transaction for the whole build: measured, per-insert commits were ~20% of the insert cost
     // on a 56k-insert graph (216 ms -> 173 ms with a transaction; 88 -> 52 ms with cached statements).
     // It also makes a failed build atomic — no half-graph that could be mistaken for a complete one.
+    let resolution = {
+        resolved: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
+    };
     graph.transaction(() => {
         // Add spec nodes and dependencies
         for (const s of specs) {
             const sourcePath = opts?.specSourcePath?.(s.id);
-            graph.addNode(`SPEC:${s.id}`, s.type, sourcePath);
+            graph.addNode(`SPEC:${s.id}`, s.type, sourcePath, fact(opts, sourcePath ?? null, 'spec-store', 1));
+            // DECLARED in frontmatter.
             for (const p of s.dependsOn) {
-                graph.addEdge(`SPEC:${s.id}`, `SPEC:${p}`, 'depends_on', sourcePath);
+                graph.addEdge(`SPEC:${s.id}`, `SPEC:${p}`, 'depends_on', sourcePath, fact(opts, sourcePath ?? null, 'frontmatter', 1));
             }
         }
         // Add code nodes and implements edges, one file at a time
         for (const f of scanned) {
-            buildFileSubgraph(f, specs, graph);
+            buildFileSubgraph(f, specs, graph, opts);
         }
         // Call edges last: resolving a callee needs every file's symbols to exist as nodes first.
-        addCallEdges(scanned, graph);
+        resolution = addCallEdges(scanned, graph, opts);
+        addImportEdges(scanned, graph, opts);
     });
+    return { resolution };
 }
 /**
  * Resolve each file's recovered call relations to graph edges.
@@ -68,56 +131,98 @@ function buildRtm(specs, scanned, graph, opts) {
  * 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.
  */
-function addCallEdges(scanned, graph) {
-    // qualified name -> the sourcePaths defining it. Built once; ambiguity is decided from counts.
+function addCallEdges(scanned, graph, opts) {
+    const report = {
+        resolved: 0, ambiguous: 0, unknownTarget: 0, callerNotNamed: 0, selfReference: 0, moduleScoped: 0,
+    };
+    // @implements A-SPEC-300
+    // Indexes are built PER LANGUAGE FAMILY. Resolution used to look across the whole scan, so a Java
+    // call could bind to a Rust definition — measured, and it did. Ambiguity is judged inside the
+    // family too, which is why two same-named functions in Python and Go now each resolve correctly
+    // instead of cancelling each other out: this filter raises precision AND recall here.
+    const familyOf = (sourcePath) => (0, language_capability_1.languageFamilyOf)(path.extname(sourcePath));
     const definedIn = new Map();
     for (const f of scanned) {
+        const family = familyOf(f.sourcePath);
+        let table = definedIn.get(family);
+        if (!table) {
+            table = new Map();
+            definedIn.set(family, table);
+        }
         for (const sym of f.symbols) {
-            const list = definedIn.get(sym.qualifiedName);
+            const list = table.get(sym.qualifiedName);
             if (list) {
                 if (!list.includes(f.sourcePath))
                     list.push(f.sourcePath);
             }
             else
-                definedIn.set(sym.qualifiedName, [f.sourcePath]);
+                table.set(sym.qualifiedName, [f.sourcePath]);
         }
     }
     // A bare callee `m` may correspond to a qualified `Class.m`. Index the last segment too, but only
     // to a UNIQUE owner — a method name shared by several classes stays unresolvable on purpose.
     const byLastSegment = new Map();
-    for (const [qn, paths] of definedIn) {
-        const last = qn.includes('.') ? qn.slice(qn.lastIndexOf('.') + 1) : qn;
-        if (byLastSegment.has(last))
-            byLastSegment.set(last, null); // ambiguous — never resolved
-        else
-            byLastSegment.set(last, { qn, paths });
+    for (const [family, table] of definedIn) {
+        const index = new Map();
+        byLastSegment.set(family, index);
+        for (const [qn, paths] of table) {
+            const last = qn.includes('.') ? qn.slice(qn.lastIndexOf('.') + 1) : qn;
+            if (index.has(last))
+                index.set(last, null); // ambiguous — never resolved
+            else
+                index.set(last, { qn, paths });
+        }
     }
     for (const f of scanned) {
         for (const e of f.edges ?? []) {
-            if (e.rel !== 'calls' || !e.from || !e.to || e.from === '<module>')
+            // @implements A-SPEC-286 — `inherits` resolves by the SAME rule as `calls`: symbol-to-symbol,
+            // and only when the name is defined in exactly one file across the scan. `imports` is excluded
+            // because its target is a module path, not a symbol; resolving that needs module->file
+            // resolution this scanner does not do, and the capability table reports the gap rather than
+            // letting it pass as coverage.
+            if (e.rel !== 'calls' && e.rel !== 'inherits')
                 continue;
+            if (!e.from || !e.to || e.from === '<module>') {
+                report.moduleScoped++;
+                continue;
+            }
             const fromId = `CODE:${e.from}@${f.sourcePath}`;
             // The caller must be a real node in THIS file; otherwise the walk produced a name the symbol
             // extractor never emitted and the edge cannot be trusted.
-            if (!graph.codeNodeIds(e.from).includes(fromId))
+            if (!graph.codeNodeIds(e.from).includes(fromId)) {
+                report.callerNotNamed++;
                 continue;
+            }
+            const family = familyOf(f.sourcePath);
+            const table = definedIn.get(family);
             let target = null;
-            if (definedIn.has(e.to))
-                target = { qn: e.to, paths: definedIn.get(e.to) };
+            if (table?.has(e.to))
+                target = { qn: e.to, paths: table.get(e.to) };
             else
-                target = byLastSegment.get(e.to) ?? null;
-            if (!target)
+                target = byLastSegment.get(family)?.get(e.to) ?? null;
+            if (!target) {
+                report.unknownTarget++;
                 continue;
+            }
             const sameFile = target.paths.includes(f.sourcePath);
             const path = sameFile ? f.sourcePath : (target.paths.length === 1 ? target.paths[0] : null);
-            if (!path)
-                continue; // defined in several files — ambiguous, emit nothing
+            if (!path) {
+                report.ambiguous++;
+                continue;
+            } // defined in several files — emit nothing
             const toId = `CODE:${target.qn}@${path}`;
-            if (toId === fromId)
-                continue; // self-recursion carries no impact information
-            graph.addEdge(fromId, toId, 'calls', f.sourcePath);
+            if (toId === fromId) {
+                report.selfReference++;
+                continue;
+            } // self-recursion carries no impact
+            // INFERRED by name resolution. Its precision has never been measured in this repository, so
+            // the confidence stays null rather than carrying a number nobody can defend — an invented
+            // figure would be indistinguishable from a measured one to every downstream consumer.
+            graph.addEdge(fromId, toId, e.rel, f.sourcePath, fact(opts, `${f.sourcePath}`, 'name-resolution', null));
+            report.resolved++;
         }
     }
+    return report;
 }
 exports.DEFAULT_IMPACT = { maxCallDepth: 3, hubInDegree: 12 };
 /**
@@ -189,3 +294,135 @@ function explainImpact(graph, changedSymbolQNames, opts) {
     // `rtm_impact` emits this directly, and determinism is the harness's thesis.
     return { specs: [...set].sort(), reachedByDepth, stoppedAt, ...(seedIsHub ? { seedIsHub } : {}) };
 }
+/**
+ * @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.
+ */
+function addCommitHistory(history, scanned, graph, opts) {
+    const codeBySource = new Map();
+    for (const f of scanned) {
+        codeBySource.set(f.sourcePath, f.symbols.map((s) => `CODE:${s.qualifiedName}@${f.sourcePath}`));
+    }
+    graph.transaction(() => {
+        for (const record of history) {
+            const commitId = `COMMIT:${record.commit}`;
+            // Git STATES which files a commit touched — a declared fact, not an inference, so confidence 1.
+            graph.addNode(commitId, 'COMMIT', undefined, fact(opts, record.commit, 'git-log', 1));
+            for (const file of record.files) {
+                for (const codeId of codeBySource.get(file) ?? []) {
+                    graph.addEdge(commitId, codeId, 'changed_by', file, fact(opts, `${file}@${record.commit}`, 'git-log', 1));
+                }
+            }
+        }
+    });
+}
+/**
+ * @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.
+ */
+function addImportEdges(scanned, graph, opts) {
+    const known = new Set(scanned.map((f) => f.sourcePath));
+    const EXTENSIONS = ['', '.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs', '.jsx', '.py',
+        '/index.ts', '/index.js', '/__init__.py'];
+    const firstKnown = (base) => EXTENSIONS.map((ext) => `${base}${ext}`).find((candidate) => known.has(candidate)) ?? null;
+    const resolve = (fromFile, spec) => {
+        // @implements A-SPEC-406
+        // A specifier without a leading dot used to be refused outright, on the ground that it names an
+        // external package. That holds for `node:fs` and `js-yaml`; it does NOT hold for Python, which
+        // writes intra-repository modules absolutely — `from src.core.memory_audit import X`. Measured
+        // on the jarvis corpus: 1060 specifiers, 0 relative, 542 naming a file the scan already had, and
+        // 0 import edges in the graph. The whole import layer was missing for that language because the
+        // resolver's shape was JS's.
+        //
+        // The rule the original was written under is unchanged and is what makes this safe: resolve
+        // ONLY to a file the scan actually contains. `os.path` becomes `os/path.py`, which is in no
+        // scan, so it still emits nothing. Nothing is invented; the dotted form is simply also read.
+        if (!spec.startsWith('.')) {
+            if (spec.includes(':'))
+                return null; // `node:fs` and friends are never a repository path
+            return firstKnown(path.posix.normalize(spec.split('.').filter(Boolean).join('/')));
+        }
+        // @implements A-SPEC-289
+        // Python writes a relative import as `.b` / `..pkg.mod`, where the leading dots are LEVELS and
+        // the remaining dots are path separators — not the `./b` form JS uses. Treating `.b` as a path
+        // yields the literal name `.b`, which matches nothing. Detected by the absence of a slash: a
+        // specifier that already contains one is a JS-style path and is left alone.
+        let relative = spec;
+        if (!spec.includes('/')) {
+            const dots = spec.match(/^\.+/)[0].length;
+            const rest = spec.slice(dots).split('.').filter(Boolean).join('/');
+            relative = `${'../'.repeat(Math.max(0, dots - 1)) || './'}${rest}`;
+        }
+        return firstKnown(path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), relative)));
+    };
+    graph.transaction(() => {
+        for (const f of scanned) {
+            for (const e of f.edges ?? []) {
+                if (e.rel !== 'imports')
+                    continue;
+                const target = resolve(f.sourcePath, e.to);
+                if (!target)
+                    continue;
+                // DECLARED: the specifier is written in the source. What is inferred is only WHICH file it
+                // names, and an unresolvable one emits nothing rather than a guess.
+                graph.addNode(`FILE:${f.sourcePath}`, 'FILE', f.sourcePath, fact(opts, f.sourcePath, 'ast-scan', 1));
+                graph.addNode(`FILE:${target}`, 'FILE', target, fact(opts, target, 'ast-scan', 1));
+                graph.addEdge(`FILE:${f.sourcePath}`, `FILE:${target}`, 'imports', f.sourcePath, fact(opts, `${f.sourcePath} -> ${e.to}`, 'import-resolution', 1));
+            }
+        }
+    });
+}
+/**
+ * @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.
+ */
+function addDecisionEdges(decisions, citations, graph, opts) {
+    const known = new Map(decisions.map((d) => [d.id, d]));
+    graph.transaction(() => {
+        for (const d of decisions) {
+            graph.addNode(`DECISION:${d.id}`, 'DECISION', undefined, fact(opts, d.id, 'decision-record', 1));
+        }
+        for (const d of decisions) {
+            if (!d.supersedes || !known.has(d.supersedes))
+                continue;
+            graph.addEdge(`DECISION:${d.id}`, `DECISION:${d.supersedes}`, 'supersedes', undefined, fact(opts, d.id, 'decision-record', 1));
+        }
+        for (const c of citations) {
+            if (!known.has(c.adr))
+                continue;
+            // DECLARED: the citation is written in the file or spec that carries it.
+            graph.addEdge(c.from, `DECISION:${c.adr}`, 'constrained_by', undefined, fact(opts, c.from, 'citation', 1));
+        }
+    });
+}

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

@@ -22,13 +22,41 @@
  * The result is identical to the full build, so the incremental pass is currently redundant work
  * rather than a saving. It becomes meaningful the moment a persisted graph exists.
  */
+/**
+ * @implements A-SPEC-281
+ * What is known about HOW a fact got into the graph.
+ *
+ * `confidence: null` is load-bearing: it means the derivation gave us no measured basis for a
+ * number, and it must stay distinguishable from `1`. A `calls` edge is INFERRED by name resolution
+ * whose precision this repository has never measured, so it records the derivation and leaves the
+ * number empty rather than inventing one — the same rule the ablation follows for an unmeasured
+ * recall. An `implements` or `depends_on` edge is DECLARED (an anchor, a frontmatter field), so it
+ * carries 1: the fact is stated, not guessed.
+ *
+ * `observedAt` is supplied by the CALLER. Reading a clock in here would make the same inputs build a
+ * different graph on every run and break the incremental/full-rebuild convergence A-SPEC-280 proved.
+ */
+export interface Provenance {
+    sourceCommit: string | null;
+    extractorVersion: string | null;
+    sourceLocation: string | null;
+    confidence: number | null;
+    evidenceDigest: string | null;
+    observedAt: string | null;
+    validUntil: string | null;
+    derivation: string | null;
+}
 export declare class RtmGraph {
     private readonly db;
     constructor(dbPath?: string);
     private nodeStmt?;
     private edgeStmt?;
-    addNode(id: string, kind: string, sourcePath?: string): void;
-    addEdge(src: string, dst: string, rel: string, sourcePath?: string): void;
+    addNode(id: string, kind: string, sourcePath?: string, provenance?: Provenance): void;
+    addEdge(src: string, dst: string, rel: string, sourcePath?: string, provenance?: Provenance): void;
+    /** @implements A-SPEC-281 — how this node got here, or null if the node is unknown. */
+    provenanceOfNode(id: string): Provenance | null;
+    /** @implements A-SPEC-281 — how this edge got here, or null if the edge is unknown. */
+    provenanceOfEdge(src: string, dst: string, rel: string): Provenance | null;
     /**
      * @implements A-SPEC-139
      * Run `fn` inside ONE SQLite transaction, so a build commits once instead of once per insert.
@@ -45,6 +73,64 @@ export declare class RtmGraph {
      * "who calls me" question into "what is attached to me in any way at all".
      */
     callersOf(id: string): string[];
+    /**
+     * @implements A-SPEC-288
+     * Everything a change to this symbol can reach: its callers PLUS its subclasses. Changing a base
+     * method affects a subclass that never calls it, so impact must follow inheritance.
+     *
+     * Deliberately SEPARATE from `callersOf`, which stays calls-only. Taint follows data flow and hub
+     * detection counts call sites; folding inheritance into either would change what those two words
+     * mean rather than making them more complete.
+     *
+     * @implements A-SPEC-304
+     * A `references` relation (a type-position use of a contract) was built, wired in here, and
+     * measured: 586 correct edges on this repository, and EVERY replay metric identical with the
+     * relation on and off — including the impact-reach count, 26 truth files either way. The reason is
+     * now understood and is not about the edges: the replay enters from a REQUEST STRING, so impact is
+     * never seeded from contract nodes at all. What this feature improves, nothing measures yet.
+     */
+    impactSourcesOf(id: string): string[];
+    /**
+     * @implements A-SPEC-309
+     * Both directions of impact: who reaches this symbol, and what this symbol reaches.
+     *
+     * Goal Phase 5 asks for upstream callers AND downstream dependencies, and only the upstream half
+     * existed. Changing a function usually means changing what it calls, so the callee side is not a
+     * refinement — it is half the question.
+     *
+     * Kept as its own name rather than widening `impactSourcesOf`, for the same reason A-SPEC-288 split
+     * `impactSourcesOf` off `callersOf`: once one function answers two questions, both get blurred.
+     */
+    impactNeighborsOf(id: string, opts?: {
+        /**
+         * @implements A-SPEC-311
+         * Drop callees with more callers than this. A function everything calls is a shared tool, not a
+         * thing that changes when you change one of its callers — changing a logger does not change
+         * every caller, and calling a logger does not change the logger.
+         *
+         * The same number means different things in the two directions, which is why the upstream side
+         * applies it past depth 1 and this applies at depth 1: upstream, a high in-degree node is one
+         * many things depend ON and the damping stops the walk spreading THROUGH it; downstream, a high
+         * in-degree node is a utility and is not a signal at all.
+         *
+         * Optional, and off by default: silently filtering would change what this method means for
+         * every other caller of it.
+         */
+        maxCalleeInDegree?: number;
+    }): string[];
+    /**
+     * @implements A-SPEC-289
+     * Repo-relative paths of the files that import this one, via resolved FILE->FILE `imports` edges.
+     * A coarser dependency than a call, and the only one that reaches a file which depends on another
+     * without calling any symbol the resolver could pin down.
+     */
+    importersOf(sourcePath: string): string[];
+    /**
+     * @implements A-SPEC-293
+     * The decisions constraining any of the given node ids (`FILE:<path>` / `SPEC:<id>`), by ADR id.
+     * What a change must not break, rather than what it touches.
+     */
+    decisionsConstraining(nodeIds: readonly string[]): string[];
     /** How many distinct symbols call this one. The hub signal for bounded propagation (REQ-127). */
     callerCount(id: string): number;
     /**
@@ -82,6 +168,35 @@ export declare class RtmGraph {
     allCodeNodeIds(): string[];
     /** @implements A-SPEC-138 — direct calls-only callees of a node (one hop), for BFS path assembly. */
     callees(fromId: string): string[];
+    /**
+     * @implements A-SPEC-280
+     * A canonical, order-independent dump of the whole graph: sorted nodes then sorted edges. Exists
+     * so two graphs built by different routes (a full rebuild vs. an incremental update) can be
+     * compared as VALUES rather than by spot-checking a few lookups — the only way the convergence
+     * property Goal completion criterion 5 asks for can actually be evidence.
+     */
+    dumpCanonical(): string;
+    /**
+     * @implements A-SPEC-280
+     * Drop every edge of one relation. Needed because call resolution is GLOBAL: whether `B.two`
+     * resolves depends on how many files define it across the whole scan, so a file-local update
+     * cannot repair a call edge owned by a file that did not change. Clearing the relation and
+     * re-resolving is the only way an incremental update lands on the full-rebuild answer.
+     */
+    removeEdgesByRel(rel: string): void;
+    /** @implements A-SPEC-282 — every stored meta key/value. */
+    readMeta(): Record<string, string>;
+    /** @implements A-SPEC-282 — replace the stored meta wholesale, so a stale key cannot survive. */
+    writeMeta(meta: Record<string, string>): void;
+    /**
+     * @implements A-SPEC-282
+     * Empty the graph, keeping the file. Used when a stored graph's basis no longer holds: the caller
+     * has just been told it cannot trust these facts, so leaving any of them behind to be built on top
+     * of would be worse than having had no cache at all.
+     */
+    clear(): void;
+    /** @implements A-SPEC-283 — the journal mode actually in force, so the pragma can be asserted. */
+    journalMode(): string;
     nodeCount(): number;
     edgeCount(): number;
     close(): void;