@holmes-lab/holmes-kit 0.2.1 → 0.3.0

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

@@ -4,32 +4,39 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RtmGraph = void 0;
+// @implements A-SPEC-293
+// @implements A-SPEC-289
+// @implements A-SPEC-288
+// @implements A-SPEC-283
+// @implements A-SPEC-282
+// @implements A-SPEC-281
+// @implements A-SPEC-280
 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.
- */
+const PROVENANCE_COLUMNS = [
+    'source_commit', 'extractor_version', 'source_location', 'confidence',
+    'evidence_digest', 'observed_at', 'valid_until', 'derivation',
+];
+function provenanceRow(p) {
+    return [
+        p?.sourceCommit ?? null, p?.extractorVersion ?? null, p?.sourceLocation ?? null,
+        p?.confidence ?? null, p?.evidenceDigest ?? null, p?.observedAt ?? null,
+        p?.validUntil ?? null, p?.derivation ?? null,
+    ];
+}
+function provenanceOf(row) {
+    if (!row)
+        return null;
+    return {
+        sourceCommit: row.source_commit ?? null,
+        extractorVersion: row.extractor_version ?? null,
+        sourceLocation: row.source_location ?? null,
+        confidence: row.confidence === null || row.confidence === undefined ? null : Number(row.confidence),
+        evidenceDigest: row.evidence_digest ?? null,
+        observedAt: row.observed_at ?? null,
+        validUntil: row.valid_until ?? null,
+        derivation: row.derivation ?? null,
+    };
+}
 class RtmGraph {
     db;
     // IDENTITY / COLLISION NOTE: node identity is `id` alone; edge identity is
@@ -59,6 +66,15 @@ class RtmGraph {
     // full rebuild.
     constructor(dbPath = ':memory:') {
         this.db = new better_sqlite3_1.default(dbPath);
+        // @implements A-SPEC-283
+        // Only a FILE-backed store can be contended. Several MCP servers can be live at once, and the
+        // hook and the CLI can touch the same project, so a reader must not be blocked by a writer and a
+        // busy file must be waited on rather than thrown at. `:memory:` is private to this process and
+        // cannot use WAL at all — setting it there would be a pragma that cannot apply.
+        if (dbPath !== ':memory:') {
+            this.db.pragma('journal_mode = WAL');
+            this.db.pragma('busy_timeout = 5000');
+        }
         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
@@ -70,6 +86,24 @@ class RtmGraph {
       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-281
+        // `CREATE TABLE IF NOT EXISTS` leaves an EXISTING database on its old schema, so a store written
+        // before provenance existed would silently reject every new insert. Add the missing columns in
+        // place; existing rows keep their data and simply report null provenance, which is the honest
+        // record for a fact nobody annotated.
+        // @implements A-SPEC-282 — a small key/value side table so a persisted graph can carry the basis
+        // it was built on. Kept out of `nodes`/`edges` because it describes the WHOLE graph, not a fact.
+        this.db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
+        for (const table of ['nodes', 'edges']) {
+            const present = new Set(this.db.prepare(`PRAGMA table_info(${table})`).all()
+                .map((c) => c.name));
+            for (const column of PROVENANCE_COLUMNS) {
+                if (present.has(column))
+                    continue;
+                const type = column === 'confidence' ? 'REAL' : 'TEXT';
+                this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+            }
+        }
     }
     // @implements A-SPEC-139
     // Insert statements are compiled ONCE and reused. Measured cause of the graph-build bottleneck:
@@ -79,13 +113,22 @@ class RtmGraph {
     // 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);
+    addNode(id, kind, sourcePath, provenance) {
+        this.nodeStmt ??= this.db.prepare(`INSERT OR IGNORE INTO nodes (id,kind,source_path,${PROVENANCE_COLUMNS.join(',')}) VALUES (?,?,?,?,?,?,?,?,?,?,?)`);
+        this.nodeStmt.run(id, kind, sourcePath ?? null, ...provenanceRow(provenance));
+    }
+    addEdge(src, dst, rel, sourcePath, provenance) {
+        this.edgeStmt ??= this.db.prepare(`INSERT OR IGNORE INTO edges (src,dst,rel,source_path,${PROVENANCE_COLUMNS.join(',')}) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`);
+        this.edgeStmt.run(src, dst, rel, sourcePath ?? null, ...provenanceRow(provenance));
+    }
+    /** @implements A-SPEC-281 — how this node got here, or null if the node is unknown. */
+    provenanceOfNode(id) {
+        return provenanceOf(this.db.prepare('SELECT * FROM nodes WHERE id = ?').get(id));
     }
-    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-281 — how this edge got here, or null if the edge is unknown. */
+    provenanceOfEdge(src, dst, rel) {
+        return provenanceOf(this.db.prepare('SELECT * FROM edges WHERE src=? AND dst=? AND rel=?')
+            .get(src, dst, rel));
     }
     /**
      * @implements A-SPEC-139
@@ -109,6 +152,66 @@ class RtmGraph {
     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);
     }
+    /**
+     * @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) {
+        return this.db.prepare("SELECT DISTINCT src FROM edges WHERE dst=? AND rel IN ('calls','inherits') ORDER BY src ASC")
+            .all(id).map((x) => x.src);
+    }
+    /**
+     * @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, opts) {
+        const limit = opts?.maxCalleeInDegree;
+        const downstream = limit === undefined
+            ? this.callees(id)
+            : this.callees(id).filter((callee) => this.callerCount(callee) <= limit);
+        return [...new Set([...this.impactSourcesOf(id), ...downstream])].sort();
+    }
+    /**
+     * @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) {
+        return this.db.prepare("SELECT DISTINCT src FROM edges WHERE dst=? AND rel='imports' ORDER BY src ASC")
+            .all(`FILE:${sourcePath}`).map((x) => x.src.replace(/^FILE:/, ''));
+    }
+    /**
+     * @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) {
+        if (nodeIds.length === 0)
+            return [];
+        const marks = nodeIds.map(() => '?').join(',');
+        return this.db.prepare(`SELECT DISTINCT dst FROM edges WHERE rel='constrained_by' AND src IN (${marks}) ORDER BY dst ASC`)
+            .all(...nodeIds).map((x) => x.dst.replace(/^DECISION:/, ''));
+    }
     /** 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;
@@ -225,6 +328,66 @@ class RtmGraph {
     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);
     }
+    /**
+     * @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() {
+        // @implements A-SPEC-281 — provenance is part of the value, so a provenance-only divergence
+        // between a full rebuild and an incremental update is caught rather than passing as equal.
+        const cols = PROVENANCE_COLUMNS.join(', ');
+        const prov = (r) => PROVENANCE_COLUMNS.map((c) => (r[c] === null || r[c] === undefined ? '' : String(r[c]))).join('\t');
+        const nodes = this.db.prepare(`SELECT id, kind, source_path, ${cols} FROM nodes ORDER BY id`).all();
+        const edges = this.db.prepare(`SELECT src, dst, rel, source_path, ${cols} FROM edges ORDER BY src, dst, rel`).all();
+        return [
+            ...nodes.map((n) => `N\t${n.id}\t${n.kind}\t${n.source_path ?? ''}\t${prov(n)}`),
+            ...edges.map((e) => `E\t${e.src}\t${e.dst}\t${e.rel}\t${e.source_path ?? ''}\t${prov(e)}`),
+        ].join('\n');
+    }
+    /**
+     * @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) {
+        this.db.prepare('DELETE FROM edges WHERE rel = ?').run(rel);
+    }
+    /** @implements A-SPEC-282 — every stored meta key/value. */
+    readMeta() {
+        const rows = this.db.prepare('SELECT key, value FROM meta').all();
+        return Object.fromEntries(rows.map((r) => [r.key, r.value]));
+    }
+    /** @implements A-SPEC-282 — replace the stored meta wholesale, so a stale key cannot survive. */
+    writeMeta(meta) {
+        this.transaction(() => {
+            this.db.prepare('DELETE FROM meta').run();
+            const stmt = this.db.prepare('INSERT INTO meta (key, value) VALUES (?, ?)');
+            for (const [key, value] of Object.entries(meta))
+                stmt.run(key, value);
+        });
+    }
+    /**
+     * @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() {
+        this.transaction(() => {
+            this.db.prepare('DELETE FROM edges').run();
+            this.db.prepare('DELETE FROM nodes').run();
+            this.db.prepare('DELETE FROM meta').run();
+        });
+    }
+    /** @implements A-SPEC-283 — the journal mode actually in force, so the pragma can be asserted. */
+    journalMode() {
+        return String(this.db.pragma('journal_mode', { simple: true }) ?? '');
+    }
     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(); }

package/dist/holmes/rtm/taint-benchmark.d.ts

@@ -0,0 +1,97 @@
+import { type DataFlowTaintConfig } from './dataflow-taint';
+/**
+ * A labelled corpus for the taint engine, and the reason it exists.
+ *
+ * Goal Phase E asks for CFG. Before that is a decision anyone can judge, this repository needs the
+ * number CFG would improve. The propagation today is sanitizer-aware but FLOW-INSENSITIVE: it knows
+ * which expressions read what, and not the order the statements run in or which branch they sit on.
+ * That has a cost, and the cost is currently unmeasured — so CFG's value is unmeasured with it.
+ *
+ * Every case names the ground truth AND why it is hard, so an error can be attributed to the missing
+ * ordering, the missing branch knowledge, or something else entirely. The count attributable to the
+ * first two IS the ceiling on what CFG can win here. If it is small, CFG has no value on this
+ * corpus — the same verdict Java `inherits` got for having zero edges to work with.
+ */
+export type Difficulty = 
+/** Answerable without any control flow — a straight line. */
+'flow-free'
+/** Needs statement ORDER: the same statements in another order have the opposite answer. */
+ | 'needs-order'
+/** Needs BRANCH knowledge: the answer differs per path, or on the merge of paths. */
+ | 'needs-branch';
+export interface TaintCase {
+    name: string;
+    code: string;
+    /** True when a real source reaches a real sink unsanitised ON SOME EXECUTION PATH. */
+    vulnerable: boolean;
+    difficulty: Difficulty;
+    /** Why this case is what it claims to be — the ground truth's justification, not a restatement. */
+    rationale: string;
+}
+export declare const TAINT_CONFIG: DataFlowTaintConfig;
+export declare const TAINT_CASES: readonly TaintCase[];
+export interface CaseOutcome {
+    name: string;
+    difficulty: Difficulty;
+    expected: boolean;
+    actual: boolean;
+    /** 'tp' | 'tn' | 'fp' | 'fn' — the confusion cell this case landed in. */
+    cell: 'tp' | 'tn' | 'fp' | 'fn';
+}
+export interface TaintBenchmark {
+    outcomes: CaseOutcome[];
+    tp: number;
+    tn: number;
+    fp: number;
+    fn: number;
+    /** null when nothing was predicted positive — unmeasured, not zero. */
+    precision: number | null;
+    recall: number | null;
+    /**
+     * Errors whose case is labelled `needs-order` or `needs-branch`. This is the CEILING on what a
+     * control-flow graph could win on this corpus: an error on a `flow-free` case has some other
+     * cause, and CFG would not touch it.
+     */
+    controlFlowAttributable: number;
+}
+/** Run the current engine over the labelled cases and score it. */
+export declare function runTaintBenchmark(cases?: readonly TaintCase[]): TaintBenchmark;
+export interface RealCorpusTaint {
+    corpus: string;
+    filesScanned: number;
+    /**
+     * Files the propagation actually received facts for.
+     *
+     * When this is 0 the corpus is UNMEASURED, not clean: the data-flow walk exists for a subset of
+     * languages, so a Python/JS repository yields no facts and would otherwise report a confident
+     * `findings: 0`. Measured on jarvis: 145 files scanned, 0 with facts.
+     */
+    filesWithFacts: number;
+    findings: number;
+    /** Distinct (file, callee, line) sinks reached — a run reporting one sink many times is one site. */
+    sites: number;
+    /** Findings whose flow contains a sanitizer call anywhere: the shapes control flow could re-judge. */
+    findingsTouchingSanitizer: number;
+    converged: boolean;
+    truncated: number;
+    /** null when nothing was analysable — the axis is unmeasured, and 0 findings would be a lie. */
+    findingsPerFile: number | null;
+}
+/**
+ * How often the taint analysis fires on REAL code.
+ *
+ * A-SPEC-354 measured what control flow could fix; this measures whether there is anything to fix.
+ * An analysis that produces a handful of findings across an entire repository cannot repay a
+ * control-flow graph however much its precision would improve — the same reasoning that declined
+ * `inherits` edges for a corpus that contained none.
+ *
+ * `findingsTouchingSanitizer` is the honest upper bound on the control-flow-attributable share: a
+ * finding whose derivation never passes a sanitizer cannot be a false positive created by
+ * conditional sanitisation. It is an upper bound and not a count of false positives — deciding
+ * whether each is truly spurious needs a human, and inflating it into a defect count is exactly the
+ * kind of claim this document exists to prevent.
+ */
+export declare function taintOnRealCorpus(corpusName: string, root: string, scan: (root: string) => readonly {
+    sourcePath: string;
+    dataflow?: import('../cpg/language-parser').DataFlowFacts;
+}[], cfg?: DataFlowTaintConfig): RealCorpusTaint;

package/dist/holmes/rtm/taint-benchmark.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAINT_CASES = exports.TAINT_CONFIG = void 0;
+exports.runTaintBenchmark = runTaintBenchmark;
+exports.taintOnRealCorpus = taintOnRealCorpus;
+// @implements A-SPEC-354
+const language_parser_1 = require("../cpg/language-parser");
+const dataflow_taint_1 = require("./dataflow-taint");
+exports.TAINT_CONFIG = {
+    sources: ['req.body', 'req.query', 'process.argv'],
+    sinks: ['exec', 'execSync', 'query'],
+    sanitizers: ['escape', 'sanitize'],
+};
+exports.TAINT_CASES = [
+    {
+        name: 'direct source to sink',
+        vulnerable: true, difficulty: 'flow-free',
+        rationale: 'One assignment, one call. Any engine that finds nothing here is broken, not imprecise.',
+        code: `function h(req) { const c = req.body.cmd; exec(c); }`,
+    },
+    {
+        name: 'sanitised before the sink',
+        vulnerable: false, difficulty: 'flow-free',
+        rationale: 'The kill rule alone settles it; no ordering needed because there is only one order.',
+        code: `function h(req) { const c = escape(req.body.cmd); exec(c); }`,
+    },
+    {
+        name: 'two hops through a helper',
+        vulnerable: true, difficulty: 'flow-free',
+        rationale: 'Tests the arg-param and return rules rather than control flow.',
+        code: `function pass(x) { return x; }\nfunction h(req) { const c = pass(req.body.cmd); exec(c); }`,
+    },
+    {
+        name: 'sanitised AFTER the sink',
+        vulnerable: true, difficulty: 'needs-order',
+        rationale: 'The sink runs on the tainted value; the sanitiser runs afterwards and cannot help it. ' +
+            'A flow-insensitive engine sees a sanitiser applied to the variable and kills the taint, ' +
+            'reporting nothing — a FALSE NEGATIVE that only statement order can distinguish.',
+        code: `function h(req) { let c = req.body.cmd; exec(c); c = escape(c); return c; }`,
+    },
+    {
+        name: 'overwritten with a constant before the sink',
+        vulnerable: false, difficulty: 'needs-order',
+        rationale: 'The variable is tainted, then reassigned to a literal, then used. Without order, the ' +
+            'variable is simply "tainted" and the sink is reported — a FALSE POSITIVE that order kills.',
+        code: `function h(req) { let c = req.body.cmd; c = "ls"; exec(c); }`,
+    },
+    {
+        name: 'sanitised on one branch only',
+        vulnerable: true, difficulty: 'needs-branch',
+        rationale: 'One path sanitises and the other does not, so a vulnerable path exists. Flow-insensitively ' +
+            'the sanitiser is present, which can kill the taint and hide the unsanitised path.',
+        code: `function h(req, safe) { let c = req.body.cmd; if (safe) { c = escape(c); } exec(c); }`,
+    },
+    {
+        name: 'sanitised on every branch',
+        vulnerable: false, difficulty: 'needs-branch',
+        rationale: 'Both paths sanitise, so nothing is vulnerable. Distinguishing this from the case above is ' +
+            'exactly what branch knowledge buys — flow-insensitively the two look identical.',
+        code: `function h(req, safe) { let c = req.body.cmd; if (safe) { c = escape(c); } else { c = escape(c); } exec(c); }`,
+    },
+    {
+        name: 'tainted only on the branch not taken into the sink',
+        vulnerable: false, difficulty: 'needs-branch',
+        rationale: 'The sink consumes a different, clean variable; the tainted one never reaches it.',
+        code: `function h(req, safe) { const dirty = req.body.cmd; const clean = "ls"; if (safe) { exec(clean); } return dirty; }`,
+    },
+    {
+        name: 'no source at all',
+        vulnerable: false, difficulty: 'flow-free',
+        rationale: 'Guards against an engine that reports any sink call regardless of what reaches it.',
+        code: `function h() { const c = "ls -la"; exec(c); }`,
+    },
+    {
+        name: 'source but no sink',
+        vulnerable: false, difficulty: 'flow-free',
+        rationale: 'Guards against reporting taint that never lands anywhere dangerous.',
+        code: `function h(req) { const c = req.body.cmd; return c.length; }`,
+    },
+];
+/** Run the current engine over the labelled cases and score it. */
+function runTaintBenchmark(cases = exports.TAINT_CASES) {
+    const parser = new language_parser_1.TreeSitterTsParser();
+    const outcomes = [];
+    for (const c of cases) {
+        const facts = parser.extractDataFlow(c.code, 'typescript');
+        // No facts is not "clean": it means the case was never analysed. Recording it as a negative
+        // would credit the engine with an answer it did not give.
+        const actual = facts === undefined
+            ? false
+            : (0, dataflow_taint_1.taintDataFlow)([{ file: `${c.name}.ts`, facts }], exports.TAINT_CONFIG).findings.length > 0;
+        const cell = c.vulnerable
+            ? (actual ? 'tp' : 'fn')
+            : (actual ? 'fp' : 'tn');
+        outcomes.push({ name: c.name, difficulty: c.difficulty, expected: c.vulnerable, actual, cell });
+    }
+    const count = (k) => outcomes.filter((o) => o.cell === k).length;
+    const tp = count('tp'), tn = count('tn'), fp = count('fp'), fn = count('fn');
+    return {
+        outcomes, tp, tn, fp, fn,
+        precision: tp + fp === 0 ? null : tp / (tp + fp),
+        recall: tp + fn === 0 ? null : tp / (tp + fn),
+        controlFlowAttributable: outcomes.filter((o) => (o.cell === 'fp' || o.cell === 'fn') && o.difficulty !== 'flow-free').length,
+    };
+}
+/**
+ * How often the taint analysis fires on REAL code.
+ *
+ * A-SPEC-354 measured what control flow could fix; this measures whether there is anything to fix.
+ * An analysis that produces a handful of findings across an entire repository cannot repay a
+ * control-flow graph however much its precision would improve — the same reasoning that declined
+ * `inherits` edges for a corpus that contained none.
+ *
+ * `findingsTouchingSanitizer` is the honest upper bound on the control-flow-attributable share: a
+ * finding whose derivation never passes a sanitizer cannot be a false positive created by
+ * conditional sanitisation. It is an upper bound and not a count of false positives — deciding
+ * whether each is truly spurious needs a human, and inflating it into a defect count is exactly the
+ * kind of claim this document exists to prevent.
+ */
+function taintOnRealCorpus(corpusName, root, scan, cfg = exports.TAINT_CONFIG) {
+    const scanned = scan(root);
+    const withFacts = scanned.filter((f) => f.dataflow !== undefined);
+    const result = (0, dataflow_taint_1.taintDataFlow)(withFacts.map((f) => ({ file: f.sourcePath, facts: f.dataflow })), 
+    // The default 10-iteration bound did NOT converge on this repository, and an unconverged
+    // fixpoint under-reports — quoting its finding count as the corpus rate would understate the
+    // very number this measurement exists to produce.
+    { ...cfg, maxFindings: 10_000, maxIterations: 200 });
+    const sites = new Set(result.findings.map((f) => `${f.file}:${f.callee}:${f.line}`));
+    const touching = result.findings.filter((f) => f.flow.some((s) => cfg.sanitizers.some((san) => s.detail.toLowerCase().includes(san.toLowerCase())))).length;
+    return {
+        corpus: corpusName,
+        filesScanned: scanned.length,
+        filesWithFacts: withFacts.length,
+        findings: result.findings.length,
+        sites: sites.size,
+        findingsTouchingSanitizer: touching,
+        converged: result.converged,
+        truncated: result.truncated,
+        findingsPerFile: withFacts.length === 0 ? null : result.findings.length / withFacts.length,
+    };
+}

package/dist/holmes/rtm/test-scope.js

@@ -263,6 +263,28 @@ function extractAnchors(source) {
     const noStrings = source.replace(STRINGS_RE, '""');
     return [...new Set([...noStrings.matchAll(IMPL_LINE_RE)].map((m) => m[1]))];
 }
+/**
+ * @implements A-SPEC-269
+ * The unresolved list is heterogeneous. Callers push three different kinds of entry through it:
+ * plain changed files that resolved to no lane, `unsupported:<ext>` language markers, and
+ * `impact-truncated:<reason>:<node>` markers from a caller walk that stopped at its bound. A single
+ * template called all three "changed source file(s) resolved to no spec", so the tier was right and
+ * the sentence justifying it described the wrong thing. Naming each axis costs nothing and is the
+ * difference between an operator trusting the reason and having to decode the markers by hand.
+ */
+function describeUnresolved(entries) {
+    const unsupported = entries.filter((e) => e.startsWith('unsupported:'));
+    const truncated = entries.filter((e) => e.startsWith('impact-truncated:'));
+    const changed = entries.filter((e) => !e.startsWith('unsupported:') && !e.startsWith('impact-truncated:'));
+    const parts = [];
+    if (changed.length > 0)
+        parts.push(`${changed.length} changed source file(s) resolved to no spec`);
+    if (unsupported.length > 0)
+        parts.push(`${unsupported.length} unsupported language(s) outside the graph`);
+    if (truncated.length > 0)
+        parts.push(`${truncated.length} truncated impact walk(s)`);
+    return parts.join(', ');
+}
 /**
  * Scan the repo for TEST files and the A-SPEC ids they @implement. Separate from the CPG scan (which
  * excludes tests), so the test↔spec edges actually exist for scoping. Returns repo-relative POSIX
@@ -327,10 +349,11 @@ function computeTestScope(impactedSpecsRaw, testAnchors, specs, coverageGaps = [
     if (unresolvedFiles.length > 0) {
         const shown = unresolvedFiles.slice(0, 5).join(', ');
         const suffix = unresolvedFiles.length > 5 ? ` (${unresolvedFiles.length} unresolved total)` : '';
+        const described = describeUnresolved(unresolvedFiles);
         return {
             tier: 'full', impactedSpecs, impactedTestFiles: selectedTestFiles, blastRadius: 0,
             hitsFoundational: false, coverageGaps: [...coverageGaps], unresolvedFiles, architectureTouched, obligationGaps,
-            reason: `${unresolvedFiles.length} changed source file(s) resolved to no spec — cannot narrow safely, full regression: ${shown}${suffix}`,
+            reason: `${described} — cannot narrow safely, full regression: ${shown}${suffix}`,
         };
     }
     // @implements A-SPEC-233

package/dist/holmes/semantic/credentials.d.ts

@@ -0,0 +1,15 @@
+export type KeySource = 'env' | 'env-compat' | 'keychain' | 'file';
+export interface CredentialOpts {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    platform?: NodeJS.Platform;
+    /** Injected for tests; the default shells out. stdin is used so a secret never rides argv. */
+    exec?: (cmd: string, args: string[], stdin?: string) => string;
+}
+export declare function resolveSemanticKey(opts?: CredentialOpts): {
+    key: string;
+    source: KeySource;
+} | null;
+/** Store via the human's CLI act. Returns where it landed. */
+export declare function storeSemanticKey(key: string, opts?: CredentialOpts): 'keychain' | 'file';
+export declare function removeSemanticKey(opts?: CredentialOpts): void;