@holmes-lab/holmes-kit 0.3.11 → 0.4.1

package/dist/holmes/rtm/flow-sensitive-taint.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flowSensitiveTaint = flowSensitiveTaint;
+const cfg_1 = require("../cpg/foundation/cfg");
+const sink_matching_1 = require("./sink-matching");
+const lineOf = (source, offset) => source.slice(0, offset).split('\n').length;
+/** The callee's bare last-segment name for a call node, or null when it is not a plain call. */
+function calleeNameOf(ast, kids, call, source) {
+    const fnNode = kids.of(call).find((k) => ast.nodes[k].named);
+    if (fnNode === undefined)
+        return null;
+    const text = source.slice(ast.nodes[fnNode].start, ast.nodes[fnNode].end);
+    const bare = text.split(/[.:]/).pop() ?? text;
+    return /^[A-Za-z_$][\w$]*$/.test(bare) ? bare : null;
+}
+// @implements A-SPEC-512.1
+function flowSensitiveTaint(input) {
+    const { ast, cfg, ddg, source, fnName, config } = input;
+    const kids = (0, cfg_1.childrenIndex)(ast);
+    const text = (i) => source.slice(ast.nodes[i].start, ast.nodes[i].end);
+    const sinks = new Set(config.sinks.map((s) => s.toLowerCase()));
+    const sanitizers = new Set(config.sanitizers.map((s) => s.toLowerCase()));
+    const stmtOfBlock = new Set();
+    for (const b of cfg.blocks)
+        for (const s of b.stmts)
+            stmtOfBlock.add(s);
+    /** Every call node inside a statement, excluding nested function bodies. */
+    const callsIn = (stmt) => {
+        const out = [];
+        const walk = (n) => {
+            const ty = ast.nodes[n].type;
+            if (n !== stmt && stmtOfBlock.has(n))
+                return;
+            if (ty === 'call_expression' || ty === 'call')
+                out.push(n);
+            for (const c of kids.of(n))
+                walk(c);
+        };
+        walk(stmt);
+        return out;
+    };
+    // ── 1/2. Classify each definition statement: tainted (source text) vs sanitized (sanitizer call).
+    const taintedDefs = new Set();
+    for (const [stmt] of ddg.defs) {
+        const t = text(stmt);
+        const isSource = config.sources.some((s) => t.toLowerCase().includes(s.toLowerCase()));
+        if (!isSource)
+            continue;
+        // A definition whose value comes THROUGH a sanitizer is clean even if the source text is
+        // mentioned inside it: `c = escape(req.body.cmd)` reads the source but launders it.
+        const sanitized = callsIn(stmt).some((c) => {
+            const name = calleeNameOf(ast, kids, c, source);
+            return name !== null && sanitizers.has(name.toLowerCase());
+        });
+        if (!sanitized)
+            taintedDefs.add(stmt);
+    }
+    // ── 3/4. For every sink call, ask the DDG which definitions reach the names it consumes.
+    const findings = [];
+    for (const stmt of stmtOfBlock) {
+        for (const call of callsIn(stmt)) {
+            const callee = calleeNameOf(ast, kids, call, source);
+            if (callee === null)
+                continue;
+            // @implements A-SPEC-512.3 — the SAME sink decision the other engine uses, so the two
+            // cannot disagree about what a sink is (a second truth is a drifting truth).
+            const fnNode = kids.of(call).find((k) => ast.nodes[k].named);
+            const calleeText = fnNode === undefined ? callee : text(fnNode);
+            if (!(0, sink_matching_1.isSinkCall)(calleeText, callee, config.sinks))
+                continue;
+            const args = kids.of(call).find((k) => ast.nodes[k].type === 'arguments' || ast.nodes[k].type === 'argument_list');
+            const argNodes = args === undefined ? [] : kids.of(args).filter((k) => ast.nodes[k].named);
+            argNodes.forEach((arg, argIndex) => {
+                // Names this argument reads (identifiers inside the argument expression).
+                const names = new Set();
+                const collect = (n) => {
+                    if (ast.nodes[n].type === 'identifier')
+                        names.add(text(n));
+                    for (const c of kids.of(n))
+                        collect(c);
+                };
+                collect(arg);
+                // An argument that goes through a sanitizer inline is clean: `exec(escape(c))`.
+                const inlineSanitized = callsIn(arg).some((c) => {
+                    const nm = calleeNameOf(ast, kids, c, source);
+                    return nm !== null && sanitizers.has(nm.toLowerCase());
+                });
+                if (inlineSanitized)
+                    return;
+                for (const name of names) {
+                    const reaching = ddg.edges.filter((e) => e.useStmt === stmt && e.name === name);
+                    const tainted = reaching.find((e) => taintedDefs.has(e.defStmt));
+                    if (tainted === undefined)
+                        continue;
+                    findings.push({
+                        fn: fnName,
+                        callee,
+                        line: lineOf(source, ast.nodes[call].start),
+                        argIndex,
+                        argText: text(arg),
+                        taintedDef: text(tainted.defStmt),
+                    });
+                    return; // one finding per argument
+                }
+            });
+        }
+    }
+    return { findings, mode: 'flow-sensitive', taintedDefStmts: [...taintedDefs] };
+}

package/dist/holmes/rtm/reaching-def-filter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The COMBINATION S-512.1's real-corpus measurement forced: keep the inter-procedural propagation
+ * (its `arg-param` hops are how real taint actually travels — every one of the ten findings on
+ * this repository crossed a function boundary), and use reaching definitions only to REFUTE a
+ * finding inside the function where the sink sits.
+ *
+ * Direction of the filter, stated once because it is the whole design: it may only REMOVE. A
+ * finding survives unless the DDG positively shows that nothing tainted reaches the sink's use —
+ * an unparseable file, an unsupported function, a name the span walk cannot locate, all keep the
+ * finding. Fail-open is the may-analysis direction: not knowing is not a licence to dismiss.
+ *
+ * What it removes is exactly the shape the benchmark measured: a definition that is dead by the
+ * time the sink runs (overwritten with a constant), or one that every path has replaced with a
+ * sanitized value.
+ */
+import type { PersistedAst } from '../cpg/foundation/ast-store';
+import type { Cfg } from '../cpg/foundation/cfg';
+import type { Ddg } from '../cpg/foundation/ddg';
+import type { DataFlowFinding, DataFlowTaintConfig } from './dataflow-taint';
+export interface FilterInput {
+    ast: PersistedAst;
+    cfg: Cfg;
+    ddg: Ddg;
+    source: string;
+    finding: Pick<DataFlowFinding, 'line' | 'callee' | 'argText'>;
+    config: DataFlowTaintConfig;
+}
+/**
+ * Should this finding survive? True unless reaching definitions positively refute it.
+ */
+export declare function keepsFinding(input: FilterInput): boolean;
+export interface FilterOutcome<T> {
+    kept: T[];
+    /** Findings the reaching-definition evidence positively refuted, with the reason. */
+    removed: Array<{
+        finding: T;
+        reason: string;
+    }>;
+}
+/**
+ * Apply the filter to a file's findings. Everything the substrate cannot analyse is KEPT, so the
+ * result is always a subset of the input and never a superset.
+ */
+export declare function filterFindingsForFile<T extends Pick<DataFlowFinding, 'line' | 'callee' | 'argText' | 'file'>>(root: string, relPath: string, findings: T[], config: DataFlowTaintConfig): Promise<FilterOutcome<T>>;

package/dist/holmes/rtm/reaching-def-filter.js

@@ -0,0 +1,167 @@
+"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.keepsFinding = keepsFinding;
+exports.filterFindingsForFile = filterFindingsForFile;
+const cfg_1 = require("../cpg/foundation/cfg");
+const lineOf = (source, offset) => source.slice(0, offset).split('\n').length;
+// @implements A-SPEC-512.2
+/**
+ * Should this finding survive? True unless reaching definitions positively refute it.
+ */
+function keepsFinding(input) {
+    const { ast, cfg, ddg, source, finding, config } = input;
+    const kids = (0, cfg_1.childrenIndex)(ast);
+    const text = (i) => source.slice(ast.nodes[i].start, ast.nodes[i].end);
+    // Locate the sink statement: a statement on the reported line whose text names the callee.
+    const stmts = new Set();
+    for (const b of cfg.blocks)
+        for (const s of b.stmts)
+            stmts.add(s);
+    const sinkStmt = [...stmts].find((s) => lineOf(source, ast.nodes[s].start) === finding.line && text(s).includes(finding.callee));
+    if (sinkStmt === undefined)
+        return true; // cannot locate → keep (fail-open)
+    // The names the reported argument reads. If the argument text is not a bare name chain we can
+    // find in the statement, keep — an argument we cannot resolve is not an argument we can dismiss.
+    const names = new Set();
+    const collect = (n) => {
+        if (ast.nodes[n].type === 'identifier')
+            names.add(text(n));
+        for (const c of kids.of(n))
+            collect(c);
+    };
+    const argNode = (() => {
+        const stack = [sinkStmt];
+        while (stack.length) {
+            const n = stack.pop();
+            if (text(n) === finding.argText)
+                return n;
+            for (const c of kids.of(n))
+                stack.push(c);
+        }
+        return undefined;
+    })();
+    if (argNode === undefined)
+        return true; // argument not found → keep
+    collect(argNode);
+    if (names.size === 0)
+        return true; // a literal argument: not our call
+    const paramPoints = new Set(ddg.params.values());
+    const launders = (t) => config.sanitizers.some((s) => new RegExp(`\\b${s.toLowerCase()}\\s*\\(`).test(t));
+    /**
+     * Can taint arrive at this definition? A BACKWARD walk over REACHING_DEF, not a one-hop look:
+     * `function h(cmd) { const c = cmd; exec(c); }` reaches the sink through an ordinary copy, and
+     * a one-hop filter would refute it — recreating the very under-detection this slice exists to
+     * prevent (measured in S-512.1). The walk stops at a parameter (taint entry), at a source, or
+     * at a laundering definition; `seen` bounds it on cyclic (loop-carried) definitions.
+     */
+    const canCarryTaint = (defStmt, seen) => {
+        if (paramPoints.has(defStmt))
+            return true; // inter-procedural entry point
+        if (seen.has(defStmt))
+            return false;
+        seen.add(defStmt);
+        const t = text(defStmt).toLowerCase();
+        if (launders(t))
+            return false; // value washed here: this path is clean
+        if (config.sources.some((s) => t.includes(s.toLowerCase())))
+            return true;
+        for (const name of ddg.uses.get(defStmt) ?? []) {
+            for (const e of ddg.edges) {
+                if (e.useStmt !== defStmt || e.name !== name)
+                    continue;
+                if (canCarryTaint(e.defStmt, seen))
+                    return true;
+            }
+        }
+        return false;
+    };
+    for (const name of names) {
+        const reaching = ddg.edges.filter((e) => e.useStmt === sinkStmt && e.name === name);
+        if (reaching.length === 0)
+            continue; // no reaching info for this name
+        if (reaching.some((e) => canCarryTaint(e.defStmt, new Set())))
+            return true;
+    }
+    // Every name we could resolve has reaching definitions, and none of them can carry taint.
+    const anyResolved = [...names].some((n) => ddg.edges.some((e) => e.useStmt === sinkStmt && e.name === n));
+    return !anyResolved; // resolved and refuted → drop
+}
+// @implements A-SPEC-512.2
+/**
+ * Apply the filter to a file's findings. Everything the substrate cannot analyse is KEPT, so the
+ * result is always a subset of the input and never a superset.
+ */
+async function filterFindingsForFile(root, relPath, findings, config) {
+    if (findings.length === 0)
+        return { kept: [], removed: [] };
+    const { astOf } = await Promise.resolve().then(() => __importStar(require('../cpg/foundation/ast-store')));
+    const { cfgOf, functionsIn } = await Promise.resolve().then(() => __importStar(require('../cpg/foundation/cfg')));
+    const { ddgOf } = await Promise.resolve().then(() => __importStar(require('../cpg/foundation/ddg')));
+    const fs = await Promise.resolve().then(() => __importStar(require('node:fs')));
+    const path = await Promise.resolve().then(() => __importStar(require('node:path')));
+    let ast = null;
+    let source = '';
+    try {
+        ast = await astOf(root, relPath);
+        source = fs.readFileSync(path.join(root, relPath), 'utf8');
+    }
+    catch { /* unreadable: keep everything */ }
+    if (!ast || ast.errorCount > 0)
+        return { kept: findings, removed: [] };
+    const kept = [];
+    const removed = [];
+    for (const finding of findings) {
+        let verdict = true; // default keep
+        for (const fn of functionsIn(ast)) {
+            const cfg = cfgOf(ast, fn, source);
+            if ('unsupported' in cfg)
+                continue; // unsupported function: no opinion
+            const ddg = ddgOf(ast, cfg, fn, source);
+            if ('unsupported' in ddg)
+                continue;
+            const inThisFn = cfg.blocks.some((b) => b.stmts.some((s) => lineOf(source, ast.nodes[s].start) === finding.line));
+            if (!inThisFn)
+                continue;
+            verdict = keepsFinding({ ast, cfg, ddg, source, finding, config });
+            break; // the function owning the line decides
+        }
+        if (verdict)
+            kept.push(finding);
+        else
+            removed.push({ finding, reason: 'no tainted definition reaches this sink use (reaching-definition refutation)' });
+    }
+    return { kept, removed };
+}

package/dist/holmes/rtm/sink-matching.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Sink matching that reads the RECEIVER, not just the name.
+ *
+ * A-SPEC-140 already learned half of this: substring matching made `evaluateStop` an `eval` sink
+ * and `computeExecutedByAspec` an `exec` sink, so matching moved to exact names. Exact names close
+ * that hole and leave the other one open — `RegExp.prototype.exec` is spelled exactly `exec`.
+ * Measured on this repository (2026-09-02): 16 of 19 data-flow findings were `re.exec(...)` style
+ * regex calls; only three were real process execution. The dominant false-positive source was
+ * never the flow analysis, it was this.
+ *
+ * The exclusion is deliberately NARROW and fail-open. Only a receiver that is syntactically,
+ * unmistakably a regular expression suppresses the sink; an ordinary variable (`x.exec(cmd)`)
+ * stays a finding, because without type information calling it a regex would be a guess — and a
+ * guess that hides a command injection is the wrong direction to be wrong in.
+ */
+/**
+ * Is this call's receiver certainly a regular expression? True only for shapes that cannot be
+ * anything else; everything ambiguous returns false so the caller keeps treating it as a sink.
+ */
+export declare function isRegexReceiverCall(calleeText: string): boolean;
+/**
+ * The ONE sink decision both taint engines consume: an exact name match that is not a regex
+ * method call on a regex receiver. `calleeText` is the call's callee as written (`re.exec`,
+ * `child_process.exec`, `exec`); `bareName` is its last segment, the form the config lists.
+ */
+export declare function isSinkCall(calleeText: string, bareName: string, sinks: readonly string[]): boolean;

package/dist/holmes/rtm/sink-matching.js

@@ -0,0 +1,73 @@
+"use strict";
+// @implements A-SPEC-512.3
+/**
+ * Sink matching that reads the RECEIVER, not just the name.
+ *
+ * A-SPEC-140 already learned half of this: substring matching made `evaluateStop` an `eval` sink
+ * and `computeExecutedByAspec` an `exec` sink, so matching moved to exact names. Exact names close
+ * that hole and leave the other one open — `RegExp.prototype.exec` is spelled exactly `exec`.
+ * Measured on this repository (2026-09-02): 16 of 19 data-flow findings were `re.exec(...)` style
+ * regex calls; only three were real process execution. The dominant false-positive source was
+ * never the flow analysis, it was this.
+ *
+ * The exclusion is deliberately NARROW and fail-open. Only a receiver that is syntactically,
+ * unmistakably a regular expression suppresses the sink; an ordinary variable (`x.exec(cmd)`)
+ * stays a finding, because without type information calling it a regex would be a guess — and a
+ * guess that hides a command injection is the wrong direction to be wrong in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRegexReceiverCall = isRegexReceiverCall;
+exports.isSinkCall = isSinkCall;
+/** Sink names that also exist as RegExp methods — the only names the receiver rule applies to. */
+const REGEX_METHODS = new Set(['exec', 'test']);
+/** Conventional lowercase names for a compiled pattern, matched WHOLE (never as a prefix). */
+const REGEX_VAR_NAMES = new Set(['re', 'rx', 'regex', 'regexp', 'pattern', 'pat']);
+// @implements A-SPEC-512.3
+/**
+ * Is this call's receiver certainly a regular expression? True only for shapes that cannot be
+ * anything else; everything ambiguous returns false so the caller keeps treating it as a sink.
+ */
+function isRegexReceiverCall(calleeText) {
+    const text = calleeText.trim();
+    const dot = text.lastIndexOf('.');
+    if (dot <= 0)
+        return false; // a bare call has no receiver
+    const method = text.slice(dot + 1).trim();
+    if (!REGEX_METHODS.has(method.toLowerCase()))
+        return false;
+    const receiver = text.slice(0, dot).trim();
+    // A regex literal, with or without flags: /…/.exec, /…/gi.test
+    if (/^\/.*\/[dgimsuvy]*$/s.test(receiver))
+        return true;
+    // An explicitly constructed one: new RegExp(...).exec
+    if (/^new\s+RegExp\s*\(/.test(receiver))
+        return true;
+    // Conventional names. UPPER_SNAKE ending in _RE / RE is the house style for a module-level
+    // pattern (ANCHOR_RE, IMPL_LINE_RE); the lowercase set is the common local spelling.
+    const last = receiver.split(/[.[\]]/).filter(Boolean).pop() ?? receiver;
+    if (/^[A-Z][A-Z0-9_]*$/.test(last) && (last === 'RE' || last.endsWith('_RE')))
+        return true;
+    if (REGEX_VAR_NAMES.has(last.toLowerCase()))
+        return true;
+    // camelCase pattern names — measured on a vendored corpus (2026-09-02): `filePattern.exec`,
+    // `codeBlockFilePattern.exec`, `funcPattern.exec`, `arrowPattern.exec` were four of the seven
+    // findings left after the first cut. A name ENDING in Pattern/Regex/Re is a compiled pattern by
+    // near-universal convention; `Re` requires the preceding character to be lowercase so that
+    // `Store` or `Compare` cannot match.
+    if (/(?:Pattern|Regex|RegExp|Rx)$/.test(last))
+        return true;
+    if (/[a-z]Re$/.test(last))
+        return true;
+    return false;
+}
+// @implements A-SPEC-512.3
+/**
+ * The ONE sink decision both taint engines consume: an exact name match that is not a regex
+ * method call on a regex receiver. `calleeText` is the call's callee as written (`re.exec`,
+ * `child_process.exec`, `exec`); `bareName` is its last segment, the form the config lists.
+ */
+function isSinkCall(calleeText, bareName, sinks) {
+    if (!sinks.some((s) => s.toLowerCase() === bareName.toLowerCase()))
+        return false;
+    return !isRegexReceiverCall(calleeText);
+}

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

@@ -55,6 +55,19 @@ export interface TaintBenchmark {
     controlFlowAttributable: number;
 }
 /** Run the current engine over the labelled cases and score it. */
+export type TaintEngine = 'flow-insensitive' | 'flow-sensitive';
+/** Score the corpus with EITHER engine — an improvement is reported as a contrast, never alone. */
+export declare function runTaintBenchmarkAsync(cases?: readonly TaintCase[], engine?: TaintEngine): Promise<TaintBenchmark>;
+/** before/after in ONE call — the single truth both the report and its test consume. */
+export declare function compareEngines(cases?: readonly TaintCase[]): Promise<{
+    before: TaintBenchmark;
+    after: TaintBenchmark;
+    moved: Array<{
+        name: string;
+        from: CaseOutcome['cell'];
+        to: CaseOutcome['cell'];
+    }>;
+}>;
 export declare function runTaintBenchmark(cases?: readonly TaintCase[]): TaintBenchmark;
 export interface RealCorpusTaint {
     corpus: string;

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

@@ -1,6 +1,41 @@
 "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.TAINT_CASES = exports.TAINT_CONFIG = void 0;
+exports.runTaintBenchmarkAsync = runTaintBenchmarkAsync;
+exports.compareEngines = compareEngines;
 exports.runTaintBenchmark = runTaintBenchmark;
 exports.taintOnRealCorpus = taintOnRealCorpus;
 // @implements A-SPEC-354
@@ -78,7 +113,67 @@ exports.TAINT_CASES = [
         code: `function h(req) { const c = req.body.cmd; return c.length; }`,
     },
 ];
-/** Run the current engine over the labelled cases and score it. */
+// @implements A-SPEC-512.1
+/**
+ * The flow-SENSITIVE verdict for one case, judged on reaching definitions (the CPG foundation's
+ * first consumer). Async because the wasm substrate parses; `runTaintBenchmarkAsync` is the entry
+ * point that can use it, while the synchronous `runTaintBenchmark` keeps the original engine.
+ */
+async function flowSensitiveVerdict(code) {
+    const { parseAst } = await Promise.resolve().then(() => __importStar(require('../cpg/foundation/ast-store')));
+    const { cfgOf, functionsIn } = await Promise.resolve().then(() => __importStar(require('../cpg/foundation/cfg')));
+    const { ddgOf } = await Promise.resolve().then(() => __importStar(require('../cpg/foundation/ddg')));
+    const { flowSensitiveTaint } = await Promise.resolve().then(() => __importStar(require('./flow-sensitive-taint')));
+    const ast = await parseAst(code, 'case.ts');
+    if (!ast)
+        return false;
+    for (const fn of functionsIn(ast)) {
+        const cfg = cfgOf(ast, fn, code);
+        if ('unsupported' in cfg)
+            continue;
+        const ddg = ddgOf(ast, cfg, fn, code);
+        if ('unsupported' in ddg)
+            continue;
+        if (flowSensitiveTaint({ ast, cfg, ddg, source: code, fnName: 'case', config: exports.TAINT_CONFIG }).findings.length > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+// @implements A-SPEC-512.1
+/** Score the corpus with EITHER engine — an improvement is reported as a contrast, never alone. */
+async function runTaintBenchmarkAsync(cases = exports.TAINT_CASES, engine = 'flow-insensitive') {
+    if (engine === 'flow-insensitive')
+        return runTaintBenchmark(cases);
+    const outcomes = [];
+    for (const c of cases) {
+        const actual = await flowSensitiveVerdict(c.code);
+        const cell = c.vulnerable ? (actual ? 'tp' : 'fn') : (actual ? 'fp' : 'tn');
+        outcomes.push({ name: c.name, difficulty: c.difficulty, expected: c.vulnerable, actual, cell });
+    }
+    return scoreOutcomes(outcomes);
+}
+// @implements A-SPEC-512.1
+/** before/after in ONE call — the single truth both the report and its test consume. */
+async function compareEngines(cases = exports.TAINT_CASES) {
+    const before = await runTaintBenchmarkAsync(cases, 'flow-insensitive');
+    const after = await runTaintBenchmarkAsync(cases, 'flow-sensitive');
+    const moved = after.outcomes
+        .map((a, i) => ({ name: a.name, from: before.outcomes[i].cell, to: a.cell }))
+        .filter((m) => m.from !== m.to);
+    return { before, after, moved };
+}
+/** Cells → metrics. Shared so both engines are scored by exactly the same arithmetic. */
+function scoreOutcomes(outcomes) {
+    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,
+    };
+}
 function runTaintBenchmark(cases = exports.TAINT_CASES) {
     const parser = new language_parser_1.TreeSitterTsParser();
     const outcomes = [];
@@ -94,14 +189,7 @@ function runTaintBenchmark(cases = exports.TAINT_CASES) {
             : (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,
-    };
+    return scoreOutcomes(outcomes);
 }
 /**
  * How often the taint analysis fires on REAL code.

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

@@ -0,0 +1,24 @@
+/**
+ * Taint vocabulary, per language — because "we found nothing" and "we do not speak this language"
+ * are different sentences and the tool was saying the first while meaning the second.
+ *
+ * Measured on jarvis (27,232 Python files) 2026-09-02: the shipped list matched `subprocess.Popen`
+ * and `exec(`, and missed `subprocess.run` (7 files), `os.environ` (5) and `input(` (4) — the three
+ * most common Python spellings. The engine already handled Python (its CFG/DDG landed in S-510.7);
+ * it simply had no Python words to look for.
+ *
+ * The lists are DATA and the judgement is one function: adding a language grows this table, not the
+ * code. And the vocabulary is SELECTED by file language, never unioned — a union would let Python's
+ * `input(` taint an ordinary TypeScript `input` and each language would inherit the other's false
+ * positives.
+ */
+import type { DataFlowTaintConfig } from './dataflow-taint';
+export declare const TAINT_VOCABULARY: Record<'typescript' | 'python', DataFlowTaintConfig>;
+/**
+ * The vocabulary this file should be judged with, or null when the file is outside the analysable
+ * set. Null is deliberate: degrading an unknown language to the TypeScript list would produce
+ * findings in a language whose control flow we cannot even build.
+ */
+export declare function vocabularyFor(relPath: string): DataFlowTaintConfig | null;
+/** Languages this vocabulary table covers — the matrix derives its taint row from this. */
+export declare const TAINT_LANGUAGES: ReadonlySet<string>;

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAINT_LANGUAGES = exports.TAINT_VOCABULARY = void 0;
+exports.vocabularyFor = vocabularyFor;
+/**
+ * TypeScript / JavaScript — value-identical to the shipped list, which is what makes "no regression
+ * for TS" checkable rather than asserted (a test compares the two).
+ */
+const TYPESCRIPT_VOCABULARY = {
+    sources: ['getenv', 'argv', 'req.body', 'request', 'stdin', 'readfile', 'readinput', 'query.get'],
+    sinks: ['exec', 'eval', 'system', 'query', 'spawn', 'popen', 'deserialize'],
+    sanitizers: ['escape', 'sanitize', 'encodeuricomponent'],
+};
+/**
+ * Python. Sinks are matched on the callee's LAST segment, which is why `subprocess.run` appears as
+ * `run` and `pickle.loads` as `loads`. Sources are matched against expression TEXT, so they carry
+ * their qualifier (`os.environ`) — that qualifier is what keeps a local variable named `environ`
+ * from becoming a source.
+ *
+ * `input` is listed with its opening parenthesis on purpose: bare `input` is an extremely common
+ * identifier (a parameter, a field, a React prop in mixed repos), so only the CALL is a source.
+ * That decision closes H-SPEC-513's open question, and it is the same "the act, not the name" rule
+ * the sink matcher follows.
+ */
+const PYTHON_VOCABULARY = {
+    sources: [
+        'os.environ', 'os.getenv', 'sys.argv', 'sys.stdin', 'input(',
+        'request.args', 'request.form', 'request.json', 'request.data', 'request.values',
+    ],
+    sinks: [
+        'run', 'call', 'check_output', 'check_call', // subprocess.*
+        'Popen', 'popen', 'system', // subprocess.Popen / os.popen / os.system
+        'exec', 'eval', 'compile', // built-in code execution
+        'loads', 'load', // pickle / yaml deserialization
+    ],
+    sanitizers: ['quote', 'escape', 'shlex.quote', 're.escape'],
+};
+exports.TAINT_VOCABULARY = {
+    typescript: TYPESCRIPT_VOCABULARY,
+    python: PYTHON_VOCABULARY,
+};
+const TS_EXT = /\.(ts|mts|cts|tsx|js|mjs|cjs|jsx)$/i;
+const PY_EXT = /\.py$/i;
+// @implements A-SPEC-513.1
+/**
+ * The vocabulary this file should be judged with, or null when the file is outside the analysable
+ * set. Null is deliberate: degrading an unknown language to the TypeScript list would produce
+ * findings in a language whose control flow we cannot even build.
+ */
+function vocabularyFor(relPath) {
+    if (TS_EXT.test(relPath))
+        return exports.TAINT_VOCABULARY.typescript;
+    if (PY_EXT.test(relPath))
+        return exports.TAINT_VOCABULARY.python;
+    return null;
+}
+/** Languages this vocabulary table covers — the matrix derives its taint row from this. */
+exports.TAINT_LANGUAGES = new Set(Object.keys(exports.TAINT_VOCABULARY));