@holmes-lab/holmes-kit 0.1.0

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

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IMPACT = void 0;
+exports.buildFileSubgraph = buildFileSubgraph;
+exports.buildRtm = buildRtm;
+exports.addCallEdges = addCallEdges;
+exports.impactedBy = impactedBy;
+exports.explainImpact = explainImpact;
+/**
+ * Adds one scanned file's CODE nodes and `implements` edges to the graph,
+ * tagged with that file's sourcePath so RtmGraph.removeBySource(f.sourcePath)
+ * can later drop exactly this file's contribution (used by the incremental
+ * orchestrator — see Task 4).
+ */
+// @implements A-SPEC-121.2
+function buildFileSubgraph(f, specs, graph) {
+    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);
+        for (const aspec of f.implementsSpecs) {
+            graph.addEdge(codeId, `SPEC:${aspec}`, 'implements', f.sourcePath);
+        }
+    }
+}
+function buildRtm(specs, scanned, graph, opts) {
+    // @implements A-SPEC-139
+    // 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.
+    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);
+            for (const p of s.dependsOn) {
+                graph.addEdge(`SPEC:${s.id}`, `SPEC:${p}`, 'depends_on', sourcePath);
+            }
+        }
+        // Add code nodes and implements edges, one file at a time
+        for (const f of scanned) {
+            buildFileSubgraph(f, specs, graph);
+        }
+        // Call edges last: resolving a callee needs every file's symbols to exist as nodes first.
+        addCallEdges(scanned, graph);
+    });
+}
+/**
+ * Resolve each file's recovered call relations to graph edges.
+ *
+ * A scanner emits `to` as a bare callee name, because a file cannot know where the callee lives.
+ * Resolution therefore happens here, where the whole scan is visible, under a deliberately strict
+ * rule — PRECISION OVER RECALL, per the D-CPG principle:
+ *
+ *   1. same file first — a call resolves to a definition in the calling file if one matches;
+ *   2. otherwise, only if the name is defined in EXACTLY ONE file across the scan;
+ *   3. otherwise nothing is emitted.
+ *
+ * Rule 3 is the important one. A `save()` defined in nine modules is genuinely ambiguous without type
+ * resolution, and guessing produces nine wrong edges that then poison every impact answer traversing
+ * them. A missing edge merely leaves a gap that L6 already surfaces; a wrong edge is silent.
+ *
+ * OWNERSHIP: the edge is tagged with the CALLER's file, which is the file whose text contains the
+ * call. Since both endpoints are `CODE:<qn>@<path>` ids, only the caller's file can ever emit this
+ * 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.
+    const definedIn = new Map();
+    for (const f of scanned) {
+        for (const sym of f.symbols) {
+            const list = definedIn.get(sym.qualifiedName);
+            if (list) {
+                if (!list.includes(f.sourcePath))
+                    list.push(f.sourcePath);
+            }
+            else
+                definedIn.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 f of scanned) {
+        for (const e of f.edges ?? []) {
+            if (e.rel !== 'calls' || !e.from || !e.to || e.from === '<module>')
+                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))
+                continue;
+            let target = null;
+            if (definedIn.has(e.to))
+                target = { qn: e.to, paths: definedIn.get(e.to) };
+            else
+                target = byLastSegment.get(e.to) ?? null;
+            if (!target)
+                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
+            const toId = `CODE:${target.qn}@${path}`;
+            if (toId === fromId)
+                continue; // self-recursion carries no impact information
+            graph.addEdge(fromId, toId, 'calls', f.sourcePath);
+        }
+    }
+}
+exports.DEFAULT_IMPACT = { maxCallDepth: 3, hubInDegree: 12 };
+/**
+ * Impact of changing a set of symbols, as the set of specs that could be affected.
+ *
+ * DIRECTION MATTERS. `implements` runs code -> spec and is followed FORWARD; `calls` runs caller ->
+ * callee and must be followed BACKWARD, because the things at risk when you change `f` are the
+ * things that CALL `f`, not the things `f` calls. Walking calls forward would answer a different
+ * question and quietly return the wrong set.
+ *
+ * Anchor-only impact (no call hops) is a strict subset of this, so the bounded walk can only ever
+ * ADD to what the previous implementation returned.
+ */
+function impactedBy(graph, changedSymbolQNames, opts) {
+    return explainImpact(graph, changedSymbolQNames, opts).specs;
+}
+function explainImpact(graph, changedSymbolQNames, opts) {
+    const { maxCallDepth, hubInDegree } = { ...exports.DEFAULT_IMPACT, ...opts };
+    const seeds = [];
+    for (const qn of changedSymbolQNames)
+        seeds.push(...graph.codeNodeIds(qn));
+    // Backward BFS over `calls`, bounded by depth and stopped at hubs.
+    const seen = new Set(seeds);
+    const reachedByDepth = [seeds.length];
+    const stoppedAt = [];
+    let frontier = seeds;
+    for (let depth = 1; depth <= maxCallDepth && frontier.length > 0; depth++) {
+        const next = [];
+        for (const id of frontier) {
+            // Hub damping applies to nodes REACHED by the walk, never to the seed. Changing a logger must
+            // still report the twenty places that call it — refusing to expand the seed answered "nothing
+            // is affected", which is worse than answering "too much". Adversarial review caught this:
+            // bounded returned 1 spec where unbounded returned 22. Past depth 1 the bound does its job,
+            // stopping the walk from continuing THROUGH a hub into the rest of the codebase.
+            const inDeg = graph.callerCount(id);
+            if (depth > 1 && inDeg > hubInDegree) {
+                stoppedAt.push({ id, reason: 'hub', inDegree: inDeg });
+                continue;
+            }
+            for (const caller of graph.callersOf(id)) {
+                if (seen.has(caller))
+                    continue;
+                seen.add(caller);
+                next.push(caller);
+            }
+        }
+        if (next.length)
+            reachedByDepth.push(next.length);
+        frontier = next;
+    }
+    // Anything still on the frontier was cut by the depth bound, not by a hub.
+    for (const id of frontier)
+        stoppedAt.push({ id, reason: 'depth' });
+    // Every reached CODE node contributes the specs it ANCHORS, plus their parents — via specsOf,
+    // which follows `implements` and `depends_on` only. A generic reachable() here would cross `calls`
+    // forward and collect the specs of everything these symbols call, turning the answer into "what
+    // this depends on" while still labelled "what breaks if I change this".
+    const set = new Set();
+    for (const codeId of seen)
+        for (const id of graph.specsOf(codeId))
+            set.add(id);
+    // A hub SEED is reported rather than damped: its callers really are affected, so the set is right,
+    // but the caller needs to know the change is broad before treating the set as a bundle.
+    const seedCallers = seeds.reduce((max, id) => Math.max(max, graph.callerCount(id)), 0);
+    const seedIsHub = maxCallDepth > 0 && seedCallers > hubInDegree
+        ? { callers: seedCallers, threshold: hubInDegree }
+        : undefined;
+    // Sorted for a deterministic, lexicographically-stable output contract —
+    // `rtm_impact` emits this directly, and determinism is the harness's thesis.
+    return { specs: [...set].sort(), reachedByDepth, stoppedAt, ...(seedIsHub ? { seedIsHub } : {}) };
+}

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

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeBlastRadius = computeBlastRadius;
+exports.rtmCheck = rtmCheck;
+exports.checkImplements = checkImplements;
+const spec_types_1 = require("../spec/spec-types");
+// @implements A-SPEC-121.2
+// @implements A-SPEC-125.3
+// Blast radius of touching spec `targetId`: how many OTHER specs transitively depend on it (the
+// downstream set a change ripples into) and whether the touched node is itself foundational (a REQ
+// root — editing it ripples through its whole subtree). Pure reverse-BFS over depends_on edges; feeds
+// the risk classifier's blast-radius axis so spec edits get graph-aware risk (Tier-2 push-feed).
+// Graceful: an unknown targetId yields { impactedSpecCount: 0, hitsFoundational: false } (axis stays auto).
+function computeBlastRadius(specs, targetId) {
+    const target = specs.find((s) => s.id === targetId);
+    const reached = new Set([targetId]);
+    const dependents = new Set();
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const s of specs) {
+            if (reached.has(s.id))
+                continue;
+            if (s.dependsOn.some((p) => reached.has(p))) {
+                reached.add(s.id);
+                dependents.add(s.id);
+                grew = true;
+            }
+        }
+    }
+    return { impactedSpecCount: dependents.size, hitsFoundational: target?.type === 'REQ' };
+}
+function rtmCheck(specs) {
+    const issues = [];
+    const byId = new Map(specs.map((s) => [s.id, s]));
+    // duplicate-id detection (must run BEFORE/independently of the collapsing map above)
+    const idCounts = new Map();
+    for (const s of specs)
+        idCounts.set(s.id, (idCounts.get(s.id) ?? 0) + 1);
+    for (const [id, count] of idCounts)
+        if (count > 1)
+            issues.push({ kind: 'duplicate-id', id, detail: `duplicate id (${count} occurrences)` });
+    for (const s of specs)
+        for (const p of s.dependsOn)
+            if (!byId.has(p))
+                issues.push({ kind: 'dangling', id: s.id, detail: `depends_on ${p} missing` });
+    // orphan detection: non-root spec types (parents.length > 0) with no depends_on.
+    // Route through specTypeDef (own-property lookup) so a stray/unknown type on an
+    // unfiltered caller yields undefined (skipped) rather than crashing on a
+    // prototype member — consistent with validator.ts (audit Task 3/final review).
+    for (const s of specs) {
+        const def = (0, spec_types_1.specTypeDef)(s.type);
+        if (def && def.parents.length > 0 && s.dependsOn.length === 0)
+            issues.push({ kind: 'orphan', id: s.id, detail: `${s.type} has no parent (empty depends_on)` });
+    }
+    // cycle detection (DFS)
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map(specs.map((s) => [s.id, WHITE]));
+    const visit = (id) => {
+        color.set(id, GRAY);
+        for (const p of byId.get(id)?.dependsOn ?? []) {
+            const c = color.get(p);
+            if (c === GRAY) {
+                issues.push({ kind: 'cycle', id, detail: `cycle via ${p}` });
+                return true;
+            }
+            if (c === WHITE && visit(p))
+                return true;
+        }
+        color.set(id, BLACK);
+        return false;
+    };
+    for (const s of specs)
+        if (color.get(s.id) === WHITE)
+            visit(s.id);
+    return issues;
+}
+function checkImplements(scanned, specs) {
+    const issues = [];
+    const ids = new Set(specs.map((s) => s.id));
+    for (const file of scanned) {
+        for (const id of file.implementsSpecs)
+            if (!ids.has(id))
+                issues.push({ kind: 'dangling-implements', id: file.sourcePath, detail: `@implements ${id} -> no such spec` });
+        for (const id of file.unanchoredImplements)
+            issues.push({ kind: 'wrong-kind-implements', id: file.sourcePath, detail: `@implements ${id} is not an A-SPEC anchor (anchors must be A-SPEC-*)` });
+    }
+    return issues;
+}

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

@@ -0,0 +1,232 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RtmGraph = void 0;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+// @implements A-SPEC-121.2
+/**
+ * The RTM graph. **NOT PERSISTED — read this before assuming otherwise.**
+ *
+ * Every one of the seven handlers that touches a graph (`rtm_impact`, `rtm_reindex`,
+ * `context_bundle`, `review_scope`, `review_prepare`, `risk_check`, `test_run`) constructs
+ * `new RtmGraph()` with no path, so the store is `:memory:`, built from scratch on each call and
+ * discarded when the call returns. Nothing writes `.ax/rtm.sqlite`.
+ *
+ * The surrounding machinery reads as though a persistent graph exists — `applyIncremental`,
+ * `rtm_reindex`, a `.gitignore` entry for `.ax/rtm.sqlite` — and it does not. I misread exactly this
+ * and reasoned from a persistent graph that was never there, so it is stated here rather than left
+ * to be inferred from seven constructor calls.
+ *
+ * This is a DELIBERATE position, not an omission (ADR-011): the graph is a derived index whose four
+ * inputs all come from git-tracked files, so rebuilding is always correct, a past commit's `.md` +
+ * source reconstructs that commit's graph for free, and staleness cannot occur. Persisting is
+ * deferred until graph build exceeds ~1 s per call, at which point ADR-011 lists the safety
+ * machinery that has to land with it.
+ *
+ * CONSEQUENCE FOR `rtm_reindex`: it calls `buildRtm` (a full build at HEAD) and only then
+ * `applyIncremental`, which removes and re-adds the changed files' subgraphs from that same scan.
+ * 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.
+ */
+class RtmGraph {
+    db;
+    // IDENTITY / COLLISION NOTE: node identity is `id` alone; edge identity is
+    // `(src,dst,rel)` alone — `source_path` sits OUTSIDE both keys and is
+    // written under INSERT OR IGNORE, i.e. first-write-wins. Consequence: if
+    // two files emit the same node id (or the same edge), only the FIRST
+    // file's source_path is recorded as owner; a later removeBySource() call
+    // for the *other*, non-owning file will not touch that node/edge at all.
+    //
+    // RESOLVED for CODE nodes (A-SPEC-121.3): `rtm-builder.ts` folds
+    // `source_path` into the CODE node id itself (`CODE:<qualifiedName>@
+    // <sourcePath>`), so same-named symbols in different files no longer
+    // collapse into one node/id — each file gets its own node, and
+    // removeBySource() correctly drops exactly its own contribution even
+    // under a qn collision. Use `codeNodeIds(qn)` to resolve a bare
+    // qualifiedName back to every per-file node id it maps to.
+    //
+    // This collision class otherwise remains for any OTHER node kind whose id
+    // is not source_path-qualified (e.g. SPEC nodes, or a future non-CODE kind
+    // reusing this graph) — those still first-write-win exactly as described
+    // above. This is harmless under the current rtm_reindex flow (the graph
+    // is fully rebuilt at HEAD every call, so collisions self-heal on each
+    // full build). It is NOT safe for a future persisted-graph incremental
+    // reindex (build once, apply diffs across calls) for such a kind unless
+    // it likewise folds a disambiguating key into its node/edge identity (or
+    // adds reference-counting) — otherwise it will silently diverge from a
+    // full rebuild.
+    constructor(dbPath = ':memory:') {
+        this.db = new better_sqlite3_1.default(dbPath);
+        this.db.exec(`CREATE TABLE IF NOT EXISTS nodes (id TEXT PRIMARY KEY, kind TEXT NOT NULL, source_path TEXT);
+      CREATE TABLE IF NOT EXISTS edges (src TEXT NOT NULL, dst TEXT NOT NULL, rel TEXT NOT NULL, source_path TEXT, PRIMARY KEY (src,dst,rel));
+      -- The PK covers src-prefixed lookups; nothing covered dst or source_path, so every reverse
+      -- traversal and every removeBySource was a full table scan. Measured on a 240k-node graph:
+      --   neighbors() x100     655 ms -> 0 ms   (the context bundler's BFS primitive — a hot path)
+      --   removeBySource() x20 307 ms -> 1 ms
+      -- against +408 ms of build cost. Net positive within a single tool call, because the bundler
+      -- performs far more than 100 BFS steps and the graph is rebuilt once per call either way.
+      CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst);
+      CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_path);
+      CREATE INDEX IF NOT EXISTS idx_nodes_source ON nodes(source_path);`);
+    }
+    // @implements A-SPEC-139
+    // Insert statements are compiled ONCE and reused. Measured cause of the graph-build bottleneck:
+    // review_scope cost ~890 ms on an 8,000-file repo even with the scan cache warm, of which buildRtm
+    // was ~620 ms (~70%); a 56,000-insert microbenchmark isolated WHY — re-preparing the same SQL on
+    // every call was 216 ms vs 88 ms cached (-59%), and adding a transaction took it to 52 ms (-76%).
+    // Semantics are unchanged: same signatures, same INSERT OR IGNORE idempotence, same columns.
+    nodeStmt;
+    edgeStmt;
+    addNode(id, kind, sourcePath) {
+        this.nodeStmt ??= this.db.prepare('INSERT OR IGNORE INTO nodes (id,kind,source_path) VALUES (?,?,?)');
+        this.nodeStmt.run(id, kind, sourcePath ?? null);
+    }
+    addEdge(src, dst, rel, sourcePath) {
+        this.edgeStmt ??= this.db.prepare('INSERT OR IGNORE INTO edges (src,dst,rel,source_path) VALUES (?,?,?,?)');
+        this.edgeStmt.run(src, dst, rel, sourcePath ?? null);
+    }
+    /**
+     * @implements A-SPEC-139
+     * Run `fn` inside ONE SQLite transaction, so a build commits once instead of once per insert.
+     * Returns fn's value; on a throw it rolls back and re-throws — a failed build leaves no half-graph
+     * a caller could mistake for a complete one (stricter than the previous partial-insert behavior).
+     * better-sqlite3 nests via savepoints, so calling this inside an outer transaction is safe.
+     */
+    transaction(fn) {
+        return this.db.transaction(fn)();
+    }
+    reachable(fromId) {
+        return this.db.prepare(`WITH RECURSIVE r(id) AS (SELECT dst FROM edges WHERE src=? UNION SELECT e.dst FROM edges e JOIN r ON e.src=r.id) SELECT DISTINCT id FROM r`).all(fromId).map(x => x.id);
+    }
+    incoming(toId) { return this.db.prepare('SELECT DISTINCT src FROM edges WHERE dst=?').all(toId).map(x => x.src); }
+    /**
+     * Callers of a symbol — `calls` edges only, walked backwards. Impact propagation needs exactly
+     * this and not `incoming`, which would also drag in `implements` and `depends_on` and turn a
+     * "who calls me" question into "what is attached to me in any way at all".
+     */
+    callersOf(id) {
+        return this.db.prepare("SELECT DISTINCT src FROM edges WHERE dst=? AND rel='calls' ORDER BY src ASC").all(id).map(x => x.src);
+    }
+    /** How many distinct symbols call this one. The hub signal for bounded propagation (REQ-127). */
+    callerCount(id) {
+        return this.db.prepare("SELECT COUNT(DISTINCT src) AS c FROM edges WHERE dst=? AND rel='calls'").get(id).c;
+    }
+    /**
+     * Specs this code node anchors, plus their transitive `depends_on` ancestors.
+     *
+     * Deliberately NOT `reachable`, which follows every relation. Once call edges exist, a generic
+     * forward walk from a CODE node crosses `calls` too and collects the specs of everything the
+     * symbol CALLS — silently answering "what does this depend on" while claiming to answer "what
+     * breaks if I change this". Adversarial review caught exactly that: changing a caller reported the
+     * callee's spec. Impact walks callers BACKWARD; only anchors are followed forward.
+     */
+    specsOf(codeId) {
+        const direct = this.db.prepare("SELECT DISTINCT dst FROM edges WHERE src=? AND rel='implements'").all(codeId).map(x => x.dst);
+        const out = new Set(direct);
+        // Spec ancestry is spec-only (`depends_on`), so a recursive walk from a SPEC node cannot wander
+        // back into code.
+        const anc = this.db.prepare(`WITH RECURSIVE r(id) AS (SELECT dst FROM edges WHERE src=? AND rel='depends_on'
+        UNION SELECT e.dst FROM edges e JOIN r ON e.src=r.id WHERE e.rel='depends_on') SELECT DISTINCT id FROM r`);
+        for (const s of direct)
+            for (const { id } of anc.all(s))
+                out.add(id);
+        return [...out];
+    }
+    /**
+     * Neighbours with the relation that connects them, so a traversal can price a `calls` hop
+     * differently from a spec-chain hop. Same ordering guarantee as `neighbors`.
+     *
+     * A node reachable by several relations appears once per relation; callers take the cheapest.
+     */
+    neighborsWithRel(id) {
+        return this.db.prepare(`SELECT dst AS n, rel FROM edges WHERE src=? UNION SELECT src AS n, rel FROM edges WHERE dst=? ORDER BY n ASC, rel ASC`).all(id, id).map((r) => ({ id: r.n, rel: r.rel }));
+    }
+    /**
+     * This node's `depends_on` PARENTS — outgoing only, so it climbs the spec chain without descending
+     * into siblings. A shared parent (one REQ under which many slices hang) is a bidirectional hub;
+     * following it in both directions walks from any slice into every other one.
+     */
+    parentsOf(id) {
+        return this.db.prepare("SELECT DISTINCT dst FROM edges WHERE src=? AND rel='depends_on' ORDER BY dst ASC").all(id).map(x => x.dst);
+    }
+    /** Nodes exactly one edge away in EITHER direction, sorted ascending and deduped. */
+    neighbors(id) {
+        return this.db.prepare(`SELECT dst AS n FROM edges WHERE src=? UNION SELECT src AS n FROM edges WHERE dst=? ORDER BY n ASC`).all(id, id).map(x => x.n);
+    }
+    removeBySource(sourcePath) {
+        // Referential integrity, which ownership alone cannot give. A call edge is owned by the CALLER's
+        // file, so deleting the CALLEE's file left the edge behind pointing at a node that no longer
+        // exists — and a full rebuild would never produce such an edge, so the convergence invariant
+        // broke the moment call edges existed. Measured: incremental kept 2 edges where a rebuild had 1.
+        //
+        // Edges into this file's nodes therefore go FIRST, while those nodes still exist to be selected.
+        // That ordering is also what removes any need for scratch state: a first attempt staged the
+        // doomed ids in a TEMP table, which left the database unusable if anything threw between
+        // creating and dropping it — the next call failed with "table removed already exists".
+        //
+        // Scoped to THIS file's nodes, never a general dangling-endpoint sweep. A blanket version was
+        // tried and destroyed diagnostic information: an `implements` edge may legitimately point at a
+        // SPEC node that does not exist — that is code claiming a spec id nobody wrote, exactly what
+        // rtm_check's dangling-implements report is for. Deleting those would silence the finding.
+        this.db.prepare(`DELETE FROM edges WHERE src IN (SELECT id FROM nodes WHERE source_path = ?)
+                            OR dst IN (SELECT id FROM nodes WHERE source_path = ?)`).run(sourcePath, sourcePath);
+        this.db.prepare('DELETE FROM edges WHERE source_path = ?').run(sourcePath);
+        this.db.prepare('DELETE FROM nodes WHERE source_path = ?').run(sourcePath);
+    }
+    // @implements A-SPEC-121.3
+    // Resolve a bare qualifiedName to every per-file CODE node id
+    // (CODE:<qn>@<sourcePath>). Deliberately avoids SQL LIKE (and thus its
+    // `%`/`_` wildcard hazard — `_` is a valid JS identifier char, so a naive
+    // `LIKE 'CODE:'||qn||'@%'` would let e.g. codeNodeIds('my_func') also
+    // match CODE:myXfunc@...) by fetching CODE-kind nodes and filtering in JS
+    // on an exact string prefix. Returns ids sorted ascending.
+    // ASSUMPTION: `qn` contains no literal `@` (the id delimiter). This holds for
+    // the current scanner — CodeSymbol.qualifiedName is built from tree-sitter TS/JS
+    // identifiers (+`.` for method qualification), and the identifier grammar cannot
+    // produce `@`. If a future language's qn could contain `@`, this prefix scheme
+    // would need a non-`@` delimiter or explicit escaping.
+    codeNodeIds(qn) {
+        const prefix = `CODE:${qn}@`;
+        // An exact prefix over a TEXT PRIMARY KEY is a RANGE, so it rides the PK index instead of
+        // dragging every CODE row into JS. impactedBy calls this once per changed symbol; measured on a
+        // 240k-node graph, 50 calls went from 4,428 ms to 0 ms. No index could fix the old shape — the
+        // cost was the full scan itself, not a missing lookup.
+        //
+        // The upper bound is the prefix with its final byte incremented ('@' 0x40 -> 'A' 0x41). SQLite
+        // compares TEXT with BINARY collation by default, so every id carrying this exact prefix sorts
+        // inside [prefix, upper) whatever bytes precede or follow it — including multi-byte UTF-8 in qn.
+        // This also retires the LIKE hazard the previous implementation was written to avoid: a range
+        // has no metacharacters, so `_` and `%` in a qualified name are ordinary bytes.
+        const upper = prefix.slice(0, -1) + String.fromCharCode(prefix.charCodeAt(prefix.length - 1) + 1);
+        // Sorted in JS, NOT by `ORDER BY`. SQLite orders TEXT by UTF-8 bytes while JS orders by UTF-16
+        // code units, and the two DISAGREE above the BMP: an emoji (U+1F600, surrogate pair D83D DE00)
+        // sorts before U+E000 in UTF-16 but after it in UTF-8. Round-2 review caught the substrate swap
+        // silently changing this method's published ordering; a path containing an astral-plane
+        // character is rare but entirely legal. The result set is the ids for ONE qualified name, so the
+        // sort is free — the index still does the work that mattered, which was finding the rows.
+        return this.db.prepare(`SELECT id FROM nodes WHERE id >= ? AND id < ? AND kind='CODE'`)
+            .all(prefix, upper).map(x => x.id).sort();
+    }
+    // @implements A-SPEC-138
+    // Forward transitive closure over `rel='calls'` ONLY — the mirror of callersOf. Taint reachability
+    // follows calls, never `implements`/`depends_on` (which `reachable` would drag in). Used to screen
+    // source→sink call paths.
+    callReachable(fromId) {
+        return this.db.prepare(`WITH RECURSIVE r(id) AS (SELECT dst FROM edges WHERE src=? AND rel='calls'
+        UNION SELECT e.dst FROM edges e JOIN r ON e.src=r.id WHERE e.rel='calls') SELECT DISTINCT id FROM r`).all(fromId).map(x => x.id);
+    }
+    /** @implements A-SPEC-138 — every CODE node id, for the taint pass to match source/sink names against. */
+    allCodeNodeIds() {
+        return this.db.prepare(`SELECT id FROM nodes WHERE kind='CODE' ORDER BY id ASC`).all().map(x => x.id);
+    }
+    /** @implements A-SPEC-138 — direct calls-only callees of a node (one hop), for BFS path assembly. */
+    callees(fromId) {
+        return this.db.prepare("SELECT DISTINCT dst FROM edges WHERE src=? AND rel='calls' ORDER BY dst ASC").all(fromId).map(x => x.dst);
+    }
+    nodeCount() { return this.db.prepare('SELECT COUNT(*) AS c FROM nodes').get().c; }
+    edgeCount() { return this.db.prepare('SELECT COUNT(*) AS c FROM edges').get().c; }
+    close() { this.db.close(); }
+}
+exports.RtmGraph = RtmGraph;

package/dist/holmes/rtm/taint.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TAINT_CONFIG = exports.TAINT_LIMITS = void 0;
+exports.taintReachability = taintReachability;
+/** The limits every taint report must disclose — this is reachability, not data-flow. */
+exports.TAINT_LIMITS = ['name-based matching', 'no def-use', 'no sanitizers', 'call-edge-only'];
+/**
+ * A small, conservative default source/sink set. Patterns are case-insensitive substrings on a node's
+ * qualified name. Deliberately narrow (precision over recall) and overridable by config.
+ */
+exports.DEFAULT_TAINT_CONFIG = {
+    sources: ['getenv', 'argv', 'req.body', 'request', 'stdin', 'readfile', 'readinput', 'query.get'],
+    sinks: ['exec', 'eval', 'system', 'query', 'spawn', 'popen', 'deserialize'],
+    maxPaths: 100,
+};
+const DEFAULT_MAX_PATHS = 100;
+const MAX_DEPTH = 20;
+/** The qualified-name portion of a `CODE:<qn>@<path>` id, lowercased for matching. */
+function qnOf(id) {
+    const at = id.lastIndexOf('@');
+    const body = id.startsWith('CODE:') ? id.slice('CODE:'.length, at === -1 ? undefined : at) : id;
+    return body.toLowerCase();
+}
+const matchesAny = (qn, patterns) => patterns.some((p) => p && qn.includes(p.toLowerCase()));
+/**
+ * A representative SHORTEST call path from `source` to `sink` over calls-only edges, or null if none
+ * within `MAX_DEPTH`. BFS gives the shortest; ties are broken by the graph's sorted `callees`, so the
+ * result is deterministic. Pure over the graph's adjacency.
+ */
+function shortestCallPath(graph, source, sink) {
+    if (source === sink)
+        return null; // no zero-length self path
+    const prev = new Map();
+    const seen = new Set([source]);
+    let frontier = [source];
+    for (let depth = 0; depth < MAX_DEPTH && frontier.length > 0; depth++) {
+        const next = [];
+        for (const node of frontier) {
+            for (const callee of graph.callees(node)) {
+                if (seen.has(callee))
+                    continue;
+                seen.add(callee);
+                prev.set(callee, node);
+                if (callee === sink) {
+                    const path = [sink];
+                    let cur = sink;
+                    while (prev.has(cur)) {
+                        cur = prev.get(cur);
+                        path.unshift(cur);
+                    }
+                    return path;
+                }
+                next.push(callee);
+            }
+        }
+        frontier = next;
+    }
+    return null;
+}
+/**
+ * Source→sink call-reachability pairs over the graph. Deterministic: sources and sinks are iterated
+ * in the graph's sorted node order, pairs are deduped by (source, sink) and sorted, and capped at
+ * `maxPaths` with `truncated` reporting the remainder. Pure except the graph read.
+ */
+function taintReachability(graph, cfg) {
+    const maxPaths = cfg.maxPaths ?? DEFAULT_MAX_PATHS;
+    const nodes = graph.allCodeNodeIds(); // already sorted
+    const sinkSet = new Set(nodes.filter((n) => matchesAny(qnOf(n), cfg.sinks)));
+    const sources = nodes.filter((n) => matchesAny(qnOf(n), cfg.sources));
+    const all = [];
+    for (const source of sources) {
+        const reachable = graph.callReachable(source);
+        // A node matching both source and sink is not a source→sink FLOW — skip it here so neither the
+        // shortest-path nor the deep-path fallback can mint a spurious self pair (a self-loop or cycle
+        // puts the node in its own callReachable set, which the depth fallback would otherwise emit).
+        const reachedSinks = reachable.filter((n) => sinkSet.has(n) && n !== source).sort();
+        for (const sink of reachedSinks) {
+            // Reachability was already confirmed by callReachable (unbounded). shortestCallPath bounds the
+            // DISPLAYED path length, not the finding: when a real path is deeper than MAX_DEPTH, still emit
+            // the pair (dropping it would be a silent under-report the envelope does not disclose) with an
+            // explicit depth-bound placeholder so the reviewer knows a path exists but was not walked out.
+            const path = shortestCallPath(graph, source, sink) ?? [source, `…(call path deeper than ${MAX_DEPTH})`, sink];
+            all.push({ source, sink, path });
+        }
+    }
+    all.sort((a, b) => {
+        const ka = `${a.source} ${a.sink}`, kb = `${b.source} ${b.sink}`;
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+    const pairs = all.slice(0, maxPaths);
+    return { pairs, truncated: all.length - pairs.length };
+}