gitnexus 1.6.8-rc.20 → 1.6.8-rc.21

package/dist/core/ingestion/scope-resolution/pipeline/run.js

@@ -30,7 +30,10 @@ import { extractParsedFile } from '../../scope-extractor-bridge.js';
 import { finalizeScopeModel } from '../../finalize-orchestrator.js';
 import { resolveReferenceSites } from '../../resolve-references.js';
 import { buildGraphNodeLookup } from '../graph-bridge/node-lookup.js';
-import { emitFileCfgs, emitFileReachingDefs, isEmitSafeCfg, DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, } from '../../cfg/emit.js';
+import { emitFileCfgs, emitFileReachingDefs, isEmitSafeCfg, DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, REACHING_DEF_FACTS_PER_EDGE_CAP, } from '../../cfg/emit.js';
+import { emitFileTaint, DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from '../../taint/emit.js';
+import { registerBuiltinTaintModels } from '../../taint/typescript-model.js';
+import { getSourceSinkConfig } from '../../taint/source-sink-registry.js';
 import { resolveDefGraphId } from '../graph-bridge/ids.js';
 import { buildPopulatedMethodDispatch } from '../graph-bridge/method-dispatch.js';
 import { propagateImportedReturnTypes } from '../passes/imported-return-types.js';
@@ -468,6 +471,11 @@ export function runScopeResolution(input, provider) {
     // pair can't bracket them; without this accumulator the M2 cost would
     // silently disappear into `emit=` and field regressions would be invisible.
     let pdgMs = 0;
+    // M3 (#2083 U4): accumulated taint time (match + taint-side solve +
+    // propagate + TAINTED/SANITIZES emit), a sibling of `pdgMs` for the same
+    // reason — it interleaves per file inside `emit=`, so only an accumulator
+    // can bracket it. Printed as the PROF `taint=` segment.
+    let taintMs = 0;
     if (input.pdg === true) {
         let cfgBlocks = 0;
         let cfgEdges = 0;
@@ -476,6 +484,45 @@ export function runScopeResolution(input, provider) {
         let rdDropped = 0;
         let rdFacts = 0;
         let rdTruncated = 0;
+        // ── M3 taint setup (#2083 U4) ────────────────────────────────────────
+        // Explicit model-registration seam (idempotent, cheap) — the registry
+        // stays empty on non-pdg runs, preserving default-run parity. The
+        // registry is keyed by `SupportedLanguages` enum VALUES ('typescript' /
+        // 'javascript'), and `ScopeResolver.language` IS a `SupportedLanguages`
+        // member registered under those same constants — the join is direct
+        // equality, no mapping table. A language without a registered spec
+        // (python, go, …) skips taint entirely: no work, no warn spam (KTD8).
+        registerBuiltinTaintModels();
+        const taintSpec = getSourceSinkConfig(provider.language);
+        // Taint-side solver fact cap: the SAME derivation emitFileReachingDefs
+        // uses for the RD projection (edge cap × headroom factor, 0 ⇒ unlimited),
+        // so taint coverage and RD coverage truncate together — a function is
+        // never a taint coverage gap while its RD projection computed, and the
+        // RD layer's per-function truncation warn already names it.
+        const rdEdgeCap = input.pdgMaxReachingDefEdgesPerFunction ?? DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION;
+        const taintLimits = {
+            maxFindingsPerFunction: input.pdgMaxTaintFindingsPerFunction ?? DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION,
+            maxHops: input.pdgMaxTaintHops ?? DEFAULT_PDG_MAX_TAINT_HOPS,
+            maxFacts: rdEdgeCap > 0 ? rdEdgeCap * REACHING_DEF_FACTS_PER_EDGE_CAP : 0,
+        };
+        // Cross-file aggregate of EVERY TaintEmitResult counter (the M2 emit
+        // result shipped with two fields dropped on the floor — R4 forbids that
+        // here; gaps/drops feed the unconditional warn below, volume feeds the
+        // per-language debug line).
+        const taintTotals = {
+            analyzed: 0,
+            noMatch: 0,
+            unsafeSites: 0,
+            gapTruncated: 0,
+            gapOverflow: 0,
+            gapNoFacts: 0,
+            findings: 0,
+            kills: 0,
+            dropped: 0,
+            hopsTruncated: 0,
+            gapExamples: [],
+            dropExamples: [],
+        };
         for (const pf of emitParsedFiles) {
             const cfgs = pf.cfgSideChannel;
             // Defensive: cfgSideChannel is opaque (`unknown`) and crosses the cache /
@@ -521,6 +568,34 @@ export function runScopeResolution(input, provider) {
                 rdDropped += rd.droppedEdges;
                 rdFacts += rd.facts;
                 rdTruncated += rd.truncatedFunctions;
+                // M3 (#2083 U4): taint over the SAME validated CFGs, inside the SAME
+                // per-file try (a taint throw costs this file's taint layer only —
+                // its CFG/REACHING_DEF edges above are already in the graph). Skipped
+                // entirely when the language has no registered model.
+                if (taintSpec !== undefined) {
+                    const t1 = PROF ? performance.now() : 0;
+                    const taint = emitFileTaint(graph, wellFormed, pf.parsedImports, taintSpec, taintLimits, (message) => logger.warn(message));
+                    if (PROF)
+                        taintMs += performance.now() - t1;
+                    taintTotals.analyzed += taint.functionsAnalyzed;
+                    taintTotals.noMatch += taint.functionsSkippedNoMatch;
+                    taintTotals.unsafeSites += taint.functionsSkippedUnsafeSites;
+                    taintTotals.gapTruncated += taint.functionsCoverageGap.truncated;
+                    taintTotals.gapOverflow += taint.functionsCoverageGap.overflow;
+                    taintTotals.gapNoFacts += taint.functionsCoverageGap['no-facts'];
+                    taintTotals.findings += taint.findingsEmitted;
+                    taintTotals.kills += taint.killsEmitted;
+                    taintTotals.dropped += taint.findingsDropped;
+                    taintTotals.hopsTruncated += taint.hopsTruncatedFindings;
+                    for (const ex of taint.coverageGapExamples) {
+                        if (taintTotals.gapExamples.length < 5)
+                            taintTotals.gapExamples.push(ex);
+                    }
+                    for (const ex of taint.droppedExamples) {
+                        if (taintTotals.dropExamples.length < 5)
+                            taintTotals.dropExamples.push(ex);
+                    }
+                }
             }
             catch (err) {
                 // Last-resort isolation, mirroring the worker-side per-file try/catch:
@@ -540,7 +615,47 @@ export function runScopeResolution(input, provider) {
                 (cfgDroppedEdges > 0 ? `, ${cfgDroppedEdges} edges dropped (per-function cap)` : '') +
                 `; ${rdEdges} REACHING_DEF edges (${rdFacts} facts)` +
                 (rdDropped > 0 ? `, ${rdDropped} REACHING_DEF edges dropped (per-function cap)` : '') +
-                (rdTruncated > 0 ? `, ${rdTruncated} function(s) hit the fact limit` : ''));
+                (rdTruncated > 0 ? `, ${rdTruncated} function(s) hit the fact limit` : '') +
+                // M3 volume telemetry — only for languages with a registered model.
+                (taintSpec !== undefined
+                    ? `; taint: ${taintTotals.findings} TAINTED, ${taintTotals.kills} SANITIZES ` +
+                        `(${taintTotals.analyzed} function(s) analyzed, ` +
+                        `${taintTotals.noMatch} skipped: no source/sink match` +
+                        (taintTotals.hopsTruncated > 0
+                            ? `, ${taintTotals.hopsTruncated} finding(s) with truncated hop paths`
+                            : '') +
+                        `)`
+                    : ''));
+        }
+        // R4: taint coverage gaps and cap drops surface UNCONDITIONALLY (never
+        // logger.debug, never input.onWarn) at the per-language aggregate, with
+        // counts and up to 5 example functions. Per-function warns above cover
+        // the rare/actionable cases (unsafe sites, cap drops); solver-status gaps
+        // were already per-function-warned by the RD layer (same solver, same
+        // fact cap), so this aggregate is their single taint-side surface.
+        if (taintSpec !== undefined) {
+            const gapCount = taintTotals.unsafeSites +
+                taintTotals.gapTruncated +
+                taintTotals.gapOverflow +
+                taintTotals.gapNoFacts;
+            if (gapCount > 0 || taintTotals.dropped > 0) {
+                const parts = [];
+                if (gapCount > 0) {
+                    parts.push(`${gapCount} function(s) skipped for taint ` +
+                        `(${taintTotals.gapTruncated} fact-limit, ${taintTotals.gapOverflow} overflow, ` +
+                        `${taintTotals.gapNoFacts} no-facts, ${taintTotals.unsafeSites} malformed sites)` +
+                        (taintTotals.gapExamples.length > 0
+                            ? ` — e.g. ${taintTotals.gapExamples.join(', ')}`
+                            : ''));
+                }
+                if (taintTotals.dropped > 0) {
+                    parts.push(`${taintTotals.dropped} finding(s) dropped by the per-function cap` +
+                        (taintTotals.dropExamples.length > 0
+                            ? ` — e.g. ${taintTotals.dropExamples.join(', ')}`
+                            : ''));
+                }
+                logger.warn(`[taint] lang=${provider.language}: ${parts.join('; ')}`);
+            }
         }
     }
     if (PROF) {
@@ -552,7 +667,8 @@ export function runScopeResolution(input, provider) {
             ` resolve=${ns(tPropagate, tResolve).toFixed(0)}ms` +
             ` emit=${ns(tResolve, tEnd).toFixed(0)}ms` +
             // pdg ⊆ emit: the M2 reaching-defs share of the emit bucket (#2082 U4).
-            (input.pdg === true ? ` pdg=${pdgMs.toFixed(0)}ms` : '') +
+            // taint ⊆ emit likewise: the M3 match+solve+propagate+emit share (#2083 U4).
+            (input.pdg === true ? ` pdg=${pdgMs.toFixed(0)}ms taint=${taintMs.toFixed(0)}ms` : '') +
             ` total=${ns(tStart, tEnd).toFixed(0)}ms` +
             ` (${parsedFiles.length} files)`);
     }

package/dist/core/ingestion/taint/emit.d.ts

@@ -0,0 +1,124 @@
+/**
+ * In-phase taint emission (#2083 M3 U4, plan KTD1/KTD6).
+ *
+ * Per-file driver for the M3 taint pass: gate → match → solve → propagate →
+ * persist sparse `TAINTED` + `SANITIZES` edges. Invoked from the pdg window in
+ * scope-resolution (`pipeline/run.ts`), immediately after `emitFileReachingDefs`
+ * inside the SAME per-file try — per-file isolation for free (KTD1). Mirrors
+ * `emitFileReachingDefs` (cfg/emit.ts) for the budget/dedup/warn discipline and
+ * the telemetry-result shape.
+ *
+ * ## Per-function pipeline (ordering is load-bearing)
+ *
+ * 1. `hasTaintSafeSites` — a corrupted-store site annotation degrades to
+ *    SKIP-TAINT-KEEP-RD for this function (counted + warned), never a crash
+ *    (KTD2; the matcher/propagator dereference indices unvalidated).
+ * 2. `matchFunctionSites` against the language spec (the import index is
+ *    built ONCE per file — imports are a file-level fact).
+ * 3. ZERO-MATCH FAST PATH: the solver runs only when the function has at
+ *    least one matched source AND one matched sink. In a typical repo almost
+ *    no function has both; an unconditional second `computeReachingDefs` per
+ *    function would ship a near-2× solve cost to every `--pdg` user.
+ * 4. `computeReachingDefs` with the taint `maxFacts` — by DEFAULT the M2
+ *    derived `DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION` (deliberate
+ *    reuse, not a new constant: the fact-materialization envelope is a
+ *    memory question, O(defs×uses), orthogonal to the findings cap, and M2
+ *    already validated exactly this envelope on the same solver in the same
+ *    window). The run.ts caller derives `limits.maxFacts` from the SAME
+ *    RD-edge-cap formula `emitFileReachingDefs` uses, so taint coverage and
+ *    RD coverage truncate together — a function is never `truncated` for one
+ *    layer and `computed` for the other.
+ * 5. `computeTaintFlows` — a non-`computed` status is a per-function
+ *    COVERAGE GAP (R4: counted by `gapReason`, function skipped entirely,
+ *    never partially analyzed).
+ * 6. Emit one `TAINTED` edge per finding and one `SANITIZES` edge per kill.
+ *    Kills are emitted even when findings are zero — a fully-sanitized
+ *    function's kills are exactly its evidence of safety.
+ *
+ * ## Identity, dedup, budget (KTD6)
+ *
+ * Findings carry STATEMENT-LEVEL identity — function anchor + sink kind +
+ * source occurrence (point/site/object-binding/property) + sink occurrence
+ * (point/site/arg/binding) — NOT the REACHING_DEF block-level key (block-pair
+ * conflation would drop `exec(req.body, req.query)`'s second finding). The
+ * propagation engine dedups by this exact key BEFORE its deterministic cap
+ * (`maxFindingsPerFunction`) and counts the overflow; this module templates
+ * the same coordinates into the edge id (binding identity via the shared
+ * `bindingKey`; the free-text `property` rides LAST so it can never collide
+ * into another component) and warns with the drop count on truncation.
+ *
+ * `reason` carries the versioned hop encoding (`taint/path-codec.ts` — U6's
+ * `explain` decodes the same module) for `TAINTED`, and the killed binding's
+ * plain name for `SANITIZES` (M0/S1 queryability verdict, like REACHING_DEF).
+ *
+ * ## Warn split (R4 vs noise)
+ *
+ * Unsafe-site skips and cap drops warn PER FUNCTION here (rare, actionable —
+ * mirrors `emitFileReachingDefs`' malformed/cap warns). Solver coverage gaps
+ * (`truncated`/`overflow`) do NOT re-warn per function: the RD layer already
+ * warned for the same function with the same solver status (same `maxFacts`
+ * derivation — see step 4), and a duplicate `[taint]` line per mega-function
+ * would be pure spam. They are counted (+ exampled) in the result and the
+ * run.ts caller aggregates them into ONE unconditional `logger.warn` per
+ * language (R4) — never dropped on the floor (the M2 lesson).
+ */
+import type { ParsedImport } from '../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { FunctionCfg } from '../cfg/types.js';
+export { DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './propagate.js';
+import type { SourceSinkSanitizerSpec } from './source-sink-config.js';
+export interface TaintEmitLimits {
+    /** Per-function findings cap (post-dedup). `undefined` ⇒
+     *  {@link DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION}; `0` ⇒ unlimited. */
+    readonly maxFindingsPerFunction?: number;
+    /** Per-finding hop cap (source-side prefix kept). `undefined` ⇒
+     *  {@link DEFAULT_PDG_MAX_TAINT_HOPS}; `0` ⇒ unlimited. */
+    readonly maxHops?: number;
+    /**
+     * Solver fact-materialization cap for the taint-side `computeReachingDefs`
+     * call. `undefined` ⇒ {@link DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION}
+     * (the M2 derived default — see the module doc for why it is REUSED rather
+     * than derived from the findings cap); `0` ⇒ unlimited.
+     */
+    readonly maxFacts?: number;
+}
+/**
+ * Full taint-emit telemetry for one file. EVERY counter is surfaced by the
+ * run.ts aggregate (the M2 emit result had two fields dropped on the floor —
+ * the plan names that mistake; don't repeat it).
+ */
+export interface TaintEmitResult {
+    /** Functions fully propagated (`computeTaintFlows` returned `computed`). */
+    functionsAnalyzed: number;
+    /** Functions skipped by the zero-match fast path (no solver call). */
+    functionsSkippedNoMatch: number;
+    /** Functions whose `sites` failed {@link hasTaintSafeSites} (skip-taint-keep-RD). */
+    functionsSkippedUnsafeSites: number;
+    /** Source+sink functions skipped on a non-`computed` solver status (R4). */
+    functionsCoverageGap: {
+        truncated: number;
+        overflow: number;
+        'no-facts': number;
+    };
+    /** TAINTED edges persisted. */
+    findingsEmitted: number;
+    /** SANITIZES edges persisted (emitted even when findings are zero). */
+    killsEmitted: number;
+    /** Findings dropped by the per-function cap (post-dedup), summed. */
+    findingsDropped: number;
+    /** Findings whose persisted hop path is a truncated prefix (hop/byte cap). */
+    hopsTruncatedFindings: number;
+    /** ≤{@link MAX_EXAMPLES} `file:line` anchors of gap/unsafe-site functions. */
+    coverageGapExamples: string[];
+    /** ≤{@link MAX_EXAMPLES} `file:line` anchors of cap-dropped functions. */
+    droppedExamples: string[];
+}
+/**
+ * Run the taint pass over one file's emit-safe CFGs and persist TAINTED +
+ * SANITIZES edges. `cfgs` MUST already be `isEmitSafeCfg`-filtered (the same
+ * `wellFormed` array the caller fed `emitFileCfgs`/`emitFileReachingDefs`) —
+ * block/edge anchors are trusted here; only the M3 `sites` layer is
+ * re-validated (`hasTaintSafeSites`). Never throws on well-formed input;
+ * the caller's per-file try isolates the rest.
+ */
+export declare function emitFileTaint(graph: KnowledgeGraph, cfgs: readonly FunctionCfg[], parsedImports: readonly ParsedImport[], spec: SourceSinkSanitizerSpec, limits?: TaintEmitLimits, onWarn?: (message: string) => void): TaintEmitResult;

package/dist/core/ingestion/taint/emit.js

@@ -0,0 +1,204 @@
+/**
+ * In-phase taint emission (#2083 M3 U4, plan KTD1/KTD6).
+ *
+ * Per-file driver for the M3 taint pass: gate → match → solve → propagate →
+ * persist sparse `TAINTED` + `SANITIZES` edges. Invoked from the pdg window in
+ * scope-resolution (`pipeline/run.ts`), immediately after `emitFileReachingDefs`
+ * inside the SAME per-file try — per-file isolation for free (KTD1). Mirrors
+ * `emitFileReachingDefs` (cfg/emit.ts) for the budget/dedup/warn discipline and
+ * the telemetry-result shape.
+ *
+ * ## Per-function pipeline (ordering is load-bearing)
+ *
+ * 1. `hasTaintSafeSites` — a corrupted-store site annotation degrades to
+ *    SKIP-TAINT-KEEP-RD for this function (counted + warned), never a crash
+ *    (KTD2; the matcher/propagator dereference indices unvalidated).
+ * 2. `matchFunctionSites` against the language spec (the import index is
+ *    built ONCE per file — imports are a file-level fact).
+ * 3. ZERO-MATCH FAST PATH: the solver runs only when the function has at
+ *    least one matched source AND one matched sink. In a typical repo almost
+ *    no function has both; an unconditional second `computeReachingDefs` per
+ *    function would ship a near-2× solve cost to every `--pdg` user.
+ * 4. `computeReachingDefs` with the taint `maxFacts` — by DEFAULT the M2
+ *    derived `DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION` (deliberate
+ *    reuse, not a new constant: the fact-materialization envelope is a
+ *    memory question, O(defs×uses), orthogonal to the findings cap, and M2
+ *    already validated exactly this envelope on the same solver in the same
+ *    window). The run.ts caller derives `limits.maxFacts` from the SAME
+ *    RD-edge-cap formula `emitFileReachingDefs` uses, so taint coverage and
+ *    RD coverage truncate together — a function is never `truncated` for one
+ *    layer and `computed` for the other.
+ * 5. `computeTaintFlows` — a non-`computed` status is a per-function
+ *    COVERAGE GAP (R4: counted by `gapReason`, function skipped entirely,
+ *    never partially analyzed).
+ * 6. Emit one `TAINTED` edge per finding and one `SANITIZES` edge per kill.
+ *    Kills are emitted even when findings are zero — a fully-sanitized
+ *    function's kills are exactly its evidence of safety.
+ *
+ * ## Identity, dedup, budget (KTD6)
+ *
+ * Findings carry STATEMENT-LEVEL identity — function anchor + sink kind +
+ * source occurrence (point/site/object-binding/property) + sink occurrence
+ * (point/site/arg/binding) — NOT the REACHING_DEF block-level key (block-pair
+ * conflation would drop `exec(req.body, req.query)`'s second finding). The
+ * propagation engine dedups by this exact key BEFORE its deterministic cap
+ * (`maxFindingsPerFunction`) and counts the overflow; this module templates
+ * the same coordinates into the edge id (binding identity via the shared
+ * `bindingKey`; the free-text `property` rides LAST so it can never collide
+ * into another component) and warns with the drop count on truncation.
+ *
+ * `reason` carries the versioned hop encoding (`taint/path-codec.ts` — U6's
+ * `explain` decodes the same module) for `TAINTED`, and the killed binding's
+ * plain name for `SANITIZES` (M0/S1 queryability verdict, like REACHING_DEF).
+ *
+ * ## Warn split (R4 vs noise)
+ *
+ * Unsafe-site skips and cap drops warn PER FUNCTION here (rare, actionable —
+ * mirrors `emitFileReachingDefs`' malformed/cap warns). Solver coverage gaps
+ * (`truncated`/`overflow`) do NOT re-warn per function: the RD layer already
+ * warned for the same function with the same solver status (same `maxFacts`
+ * derivation — see step 4), and a duplicate `[taint]` line per mega-function
+ * would be pure spam. They are counted (+ exampled) in the result and the
+ * run.ts caller aggregates them into ONE unconditional `logger.warn` per
+ * language (R4) — never dropped on the floor (the M2 lesson).
+ */
+import { generateId } from '../../../lib/utils.js';
+import { basicBlockId, bindingKey, DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION, } from '../cfg/emit.js';
+import { computeReachingDefs, pointKey } from '../cfg/reaching-defs.js';
+import { hasTaintSafeSites } from './site-safety.js';
+import { buildTaintImportIndex, matchFunctionSites } from './match.js';
+import { computeTaintFlows, DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './propagate.js';
+// Re-exported so the pipeline (run.ts) sources the taint default caps through
+// this orchestration module rather than reaching into propagate.ts directly.
+export { DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './propagate.js';
+import { encodeTaintPath } from './path-codec.js';
+/** Cap on example anchors carried per result (aggregate-warn material, R4). */
+const MAX_EXAMPLES = 5;
+const pushExample = (list, anchor) => {
+    if (list.length < MAX_EXAMPLES)
+        list.push(anchor);
+};
+/**
+ * Run the taint pass over one file's emit-safe CFGs and persist TAINTED +
+ * SANITIZES edges. `cfgs` MUST already be `isEmitSafeCfg`-filtered (the same
+ * `wellFormed` array the caller fed `emitFileCfgs`/`emitFileReachingDefs`) —
+ * block/edge anchors are trusted here; only the M3 `sites` layer is
+ * re-validated (`hasTaintSafeSites`). Never throws on well-formed input;
+ * the caller's per-file try isolates the rest.
+ */
+export function emitFileTaint(graph, cfgs, parsedImports, spec, limits, onWarn) {
+    const result = {
+        functionsAnalyzed: 0,
+        functionsSkippedNoMatch: 0,
+        functionsSkippedUnsafeSites: 0,
+        functionsCoverageGap: { truncated: 0, overflow: 0, 'no-facts': 0 },
+        findingsEmitted: 0,
+        killsEmitted: 0,
+        findingsDropped: 0,
+        hopsTruncatedFindings: 0,
+        coverageGapExamples: [],
+        droppedExamples: [],
+    };
+    // Imports are a FILE-level fact — build the index once, not per function.
+    const importIndex = buildTaintImportIndex(parsedImports);
+    const maxFindingsPerFunction = limits?.maxFindingsPerFunction ?? DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION;
+    const maxHops = limits?.maxHops ?? DEFAULT_PDG_MAX_TAINT_HOPS;
+    const maxFacts = limits?.maxFacts ?? DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION;
+    // Defensive cross-CFG id guard: finding identity is unique WITHIN a
+    // function by construction (the propagation engine dedups), so a repeat can
+    // only mean two CFGs sharing an anchor — skip, never double-insert.
+    const seenEdgeIds = new Set();
+    for (const cfg of cfgs) {
+        const { filePath, functionStartLine, functionStartColumn } = cfg;
+        const anchor = `${filePath}:${functionStartLine}`;
+        if (!hasTaintSafeSites(cfg)) {
+            result.functionsSkippedUnsafeSites++;
+            pushExample(result.coverageGapExamples, anchor);
+            onWarn?.(`[taint] ${anchor}: malformed site annotations (out-of-range binding/site ` +
+                `indices) — taint skipped for this function; its CFG and REACHING_DEF ` +
+                `layers are unaffected`);
+            continue;
+        }
+        const matches = matchFunctionSites(cfg, spec, importIndex);
+        if (!matches.hasSource || !matches.hasSink) {
+            // Zero-match fast path: no solver call (see module doc step 3).
+            result.functionsSkippedNoMatch++;
+            continue;
+        }
+        const defUse = computeReachingDefs(cfg, { maxFacts });
+        const flows = computeTaintFlows(cfg, defUse, matches, { maxFindingsPerFunction, maxHops });
+        if (flows.status === 'coverage-gap') {
+            // R4: skipped entirely, counted by reason; aggregate-warned by the
+            // caller (the RD layer already per-function-warned this solver status).
+            result.functionsCoverageGap[flows.gapReason ?? 'no-facts']++;
+            pushExample(result.coverageGapExamples, anchor);
+            continue;
+        }
+        result.functionsAnalyzed++;
+        const bindings = cfg.bindings ?? [];
+        const fnAnchor = `${filePath}:${functionStartLine}:${functionStartColumn}`;
+        const blockId = (p) => basicBlockId(filePath, functionStartLine, functionStartColumn, p.blockIndex);
+        const bKey = (idx) => {
+            const b = bindings[idx];
+            return b === undefined ? `#${idx}` : bindingKey(b);
+        };
+        // SANITIZES — one edge per kill, REGARDLESS of findings (kills can and do
+        // exist with zero findings: a fully-sanitized flow IS the kill evidence).
+        for (const kill of flows.kills) {
+            const id = generateId('SANITIZES', `${fnAnchor}:${pointKey(kill.sanitizer)}->${pointKey(kill.killedDef)}:` +
+                bKey(kill.bindingIdx));
+            if (seenEdgeIds.has(id))
+                continue;
+            seenEdgeIds.add(id);
+            graph.addRelationship({
+                id,
+                type: 'SANITIZES',
+                sourceId: blockId(kill.sanitizer),
+                targetId: blockId(kill.killedDef),
+                confidence: 1.0,
+                reason: bindings[kill.bindingIdx]?.name ?? `#${kill.bindingIdx}`,
+            });
+            result.killsEmitted++;
+        }
+        // TAINTED — one edge per finding (already deduped + capped upstream).
+        for (const finding of flows.findings) {
+            const { source, sink } = finding;
+            // KTD6 statement-level identity: function anchor + kind + source
+            // occurrence + sink occurrence + binding keys. The rule-(b) occurrence
+            // coordinates (site index / arg index) distinguish
+            // `exec(req.body, req.query)`'s two findings; `property` is free-text
+            // (string-literal subscripts) and rides LAST so it cannot collide into
+            // another component.
+            const id = generateId('TAINTED', `${fnAnchor}:${finding.sinkKind}:` +
+                `${pointKey(source.point)}.${source.siteIndex}:${bKey(source.objectBindingIdx)}:` +
+                `${pointKey(sink.point)}.${sink.siteIndex}.${sink.argIndex}:${bKey(sink.bindingIdx)}:` +
+                `${sink.entryName}:${source.property}`);
+            if (seenEdgeIds.has(id))
+                continue;
+            seenEdgeIds.add(id);
+            // `kind` rides the reason's `;<kind>` header — the only persisted
+            // channel for the finding's category (the edge id embedding it is not a
+            // stored column; `step` is INT32). U6's `explain` decodes it back.
+            const encoded = encodeTaintPath(finding.hops.map((h) => ({ name: h.name, line: h.point.line, viaCall: h.viaCall })), { truncated: finding.hopsTruncated === true, kind: finding.sinkKind });
+            if (encoded.truncated)
+                result.hopsTruncatedFindings++;
+            graph.addRelationship({
+                id,
+                type: 'TAINTED',
+                sourceId: blockId(source.point),
+                targetId: blockId(sink.point),
+                confidence: 1.0,
+                reason: encoded.reason,
+            });
+            result.findingsEmitted++;
+        }
+        if (flows.droppedFindings > 0) {
+            result.findingsDropped += flows.droppedFindings;
+            pushExample(result.droppedExamples, anchor);
+            onWarn?.(`[taint] ${anchor}: per-function taint findings cap ` +
+                `(${maxFindingsPerFunction}) reached — dropped ${flows.droppedFindings} of ` +
+                `${flows.findings.length + flows.droppedFindings} deduped findings`);
+        }
+    }
+    return result;
+}

package/dist/core/ingestion/taint/match.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Import-aware taint-site matcher (#2083 M3 U2, plan KTD7).
+ *
+ * Classifies a function's harvested {@link SiteRecord}s against a registered
+ * {@link SourceSinkSanitizerSpec}: which member reads are SOURCES, which
+ * call/new sites are SINKS (and at which argument positions), and which are
+ * SANITIZERS. Pure main-thread data work — sites + bindings come from the U1
+ * worker harvest, imports from `ParsedFile.parsedImports`; no AST, no I/O.
+ *
+ * PRECONDITION: the caller must gate the CFG through `hasTaintSafeSites`
+ * (taint/site-safety.ts) first — this module dereferences binding/site
+ * indices without re-validating them.
+ *
+ * ## Callee resolution precedence (bare and member-rooted calls)
+ *
+ * 1. ESM import join — the callee root's local name is resolved through the
+ *    {@link TaintImportIndex} built from `parsedImports` (`named`/`alias`
+ *    members, `namespace`/default-import module handles); `import { exec as
+ *    run } from 'child_process'` makes `run(c)` resolve to
+ *    `child_process.exec`, and `import * as cp …` makes `cp.exec(c)` resolve
+ *    the same way.
+ * 2. require-literal join — a binding whose in-function defining site carries
+ *    `requireArg` resolves like a namespace handle (`const cp =
+ *    require('child_process'); cp.exec(c)`). A BARE call of a require-joined
+ *    binding is matched under BOTH interpretations, `<module>.default` (the
+ *    module/default export invoked directly) and `<module>.<localName>`
+ *    (non-renamed destructured require — the harvest attaches `resultDefs`
+ *    to destructured bindings without recording the property path, and the
+ *    binding name IS the member name in the non-renamed case).
+ * 3. Bare-name fallback — TRUE GLOBALS only (`global: true` entries: `eval`,
+ *    `new Function`, `encodeURIComponent`), and only when the name is neither
+ *    import-bound nor shadowed. Conventional receiver names (`req`/`request`
+ *    member-read sources, `res.send`, `.query`/`.execute`) are matched
+ *    name-based by their own mechanisms, never via the global fallback.
+ *
+ * ## Shadowing rule (exact)
+ *
+ * A name is treated as function-local — blocking import/global resolution —
+ * iff the function's binding table contains a NON-`synthetic` entry with that
+ * name (an in-function `function exec(){}` / `const exec = …`). Synthetic
+ * bindings (kind `module`, `synthetic: true`) are imports, true globals, or
+ * enclosing-scope captures and do not shadow. Member-call roots use the
+ * harvested `receiver` binding index directly (no name scan).
+ *
+ * ## Documented resolution gaps (direction stated, per plan KTD10)
+ *
+ * - MODULE-LEVEL `const cp = require('child_process')`: the binding is
+ *   synthetic inside the function, produces no `ParsedImport`, and its
+ *   defining site lives outside the function's harvested sites — the
+ *   require join cannot see it. Module-mechanism sinks miss (FN) and
+ *   sanitizers don't kill (FP noise — never a false kill, the safe
+ *   direction). Only in-function requires resolve.
+ * - RENAMED destructured require (`const { exec: run } = require(…)`):
+ *   the dual interpretation resolves `run` to `child_process.run` — no
+ *   match (FN). Non-renamed destructures resolve exactly.
+ * - CONSERVATIVE shadow scan for bare calls: ANY non-synthetic binding of
+ *   the callee name anywhere in the function blocks import/global
+ *   resolution, even when the shadow is block-scoped elsewhere and the call
+ *   site actually sees the import (FN; rare; safe for sanitizers).
+ * - MODULE-LEVEL user declarations are indistinguishable from imports in
+ *   the binding table (both synthetic). ESM forbids a module-level
+ *   declaration colliding with an import name, so the import join is
+ *   authoritative when an import exists; a module-level user function
+ *   shadowing a TRUE GLOBAL (e.g. a local `encodeURIComponent`) is not
+ *   detectable and would still match (pathological; accepted).
+ * - Handle COPIES (`const c2 = cp; c2.exec(…)`) are not followed — joins
+ *   are one level deep (binding → import/require), never through
+ *   assignments (FN).
+ * - `this.`/`super.`-rooted and call-rooted callee chains have no
+ *   resolvable root: only the syntactic `anyReceiver`/`receivers`
+ *   mechanisms can match them.
+ * - `reexport`/`wildcard`/`dynamic-*`/`side-effect` imports introduce no
+ *   matcher-visible local binding and are skipped by the index.
+ */
+import type { ParsedImport } from '../../../_shared/index.js';
+import type { FunctionCfg } from '../cfg/types.js';
+import type { SourceSinkSanitizerSpec, TaintMemberSourceEntry, TaintSanitizerEntry, TaintSinkEntry } from './source-sink-config.js';
+/** What a local name imported into the file denotes. */
+export interface TaintImportBinding {
+    /** Normalized module specifier (`node:` scheme stripped). */
+    readonly module: string;
+    /**
+     * Exported member bound by a named/aliased import; `undefined` when the
+     * local name is a MODULE HANDLE (namespace import, or a default import —
+     * CJS interop makes the default export ≈ the module object).
+     */
+    readonly member?: string;
+}
+/** Local name → import provenance for one file. Build once per file (U4). */
+export type TaintImportIndex = ReadonlyMap<string, TaintImportBinding>;
+/** A member-read site matched as a taint source. */
+export interface MatchedSourceRead {
+    /** Index into the owning statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly entry: TaintMemberSourceEntry;
+}
+/** A call/new site matched as a sink. */
+export interface MatchedSinkCall {
+    /** Index into the owning statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly entry: TaintSinkEntry;
+    /**
+     * Positions (indices into `site.args`) that are registered sink positions
+     * AND carry at least one recorded binding occurrence, after the spread
+     * rule (a recorded position ≥ `site.spread` matches when any registered
+     * position ≥ the spread index exists — runtime positions after a spread
+     * are unknowable) and the template rule (`template: true` aggregates all
+     * substitutions at position 0 and matches any-position). Never empty — a
+     * sink whose dangerous positions carry no occurrences cannot produce a
+     * finding and is not reported.
+     */
+    readonly argPositions: readonly number[];
+}
+/** A call site matched as a sanitizer (import-aware/global only — see module doc). */
+export interface MatchedSanitizerCall {
+    /** Index into the owning statement's `sites` array. */
+    readonly siteIndex: number;
+    readonly entry: TaintSanitizerEntry;
+    /**
+     * Bindings the sanitizer's result defines directly (`const b = escape(t)`
+     * ⇒ `b`) — U3's kill targets (KTD4b). Empty for value-position sanitizer
+     * calls (`exec(escape(x))`), whose effect is occurrence INTERPOSITION via
+     * the site's `parent`/via-tag chain, not a def kill.
+     */
+    readonly resultDefs: readonly number[];
+}
+/** All matches within one statement. Emitted only when at least one list is non-empty. */
+export interface StatementMatches {
+    readonly blockIndex: number;
+    readonly statementIndex: number;
+    readonly line: number;
+    readonly sources: readonly MatchedSourceRead[];
+    readonly sinks: readonly MatchedSinkCall[];
+    readonly sanitizers: readonly MatchedSanitizerCall[];
+}
+/** Classified sites for one function, in (block, statement, site, entry) order. */
+export interface FunctionSiteMatches {
+    readonly statements: readonly StatementMatches[];
+    /** Fast-path gates for U4: the solver runs only when both are true. */
+    readonly hasSource: boolean;
+    readonly hasSink: boolean;
+}
+/**
+ * Build the local-name → module/member index from a file's `parsedImports`.
+ * Only `named`/`alias`/`namespace` kinds bind matcher-visible local names;
+ * `importedName === 'default'` collapses to a module handle.
+ */
+export declare function buildTaintImportIndex(imports: readonly ParsedImport[]): TaintImportIndex;
+/**
+ * Classify a function's harvested sites against a language spec. See the
+ * module doc for resolution precedence, the shadowing rule, and gaps.
+ */
+export declare function matchFunctionSites(cfg: FunctionCfg, spec: SourceSinkSanitizerSpec, imports: TaintImportIndex): FunctionSiteMatches;