gitnexus 1.6.8-rc.9 → 1.6.8

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

@@ -0,0 +1,659 @@
+/**
+ * Pure intra-procedural taint propagation engine (#2083 M3 U3).
+ *
+ * Forward taint reachability over one function's reaching-definition facts
+ * (M2 `computeReachingDefs`) and matched taint sites (U2 `matchFunctionSites`)
+ * — sources in, findings + sanitizer kills + coverage status out. PURE AND
+ * DETERMINISTIC, mirroring the reaching-defs contract: no graph, no I/O, no
+ * logger; insertion-ordered worklist; explicitly sorted outputs; snapshot
+ * tests and content-derived edge ids (U4) rely on it.
+ *
+ * PRECONDITIONS: the caller gates the CFG through `hasTaintSafeSites`
+ * (taint/site-safety.ts) and the emit-safety checks before calling — this
+ * module dereferences binding/site/statement indices without re-validating.
+ *
+ * ## The two-rule model (plan HTD)
+ *
+ * - **Rule (b), statement-local:** a matched SOURCE occurrence (member read)
+ *   whose intra-statement occurrence path — the member-read's `parent` chain —
+ *   reaches a matched SINK argument position produces an immediate single-hop
+ *   finding (`exec(req.body)`). The same statement SEEDS taint: every binding
+ *   the statement defines becomes tainted (see the precision floor below).
+ * - **Rule (a), worklist:** for each tainted `(binding, defPoint)`, every
+ *   def→use fact delivers the taint to a use statement, where occurrences of
+ *   the binding in matched sink argument positions produce findings and the
+ *   statement's own defs are tainted onward. The fact graph contains genuine
+ *   cycles (loop back-edges, same-statement self-facts) — the visited-set
+ *   discipline below is load-bearing, not defensive.
+ *
+ * ## Sanitizer semantics — the KIND-SET exclusion model (KTD4, sharpened)
+ *
+ * The plan sketches a binary kill; this module implements the strictly more
+ * precise SOUND refinement: a taint carries a set of *excluded* (neutralized)
+ * `SinkKind`s accumulated through sanitizer hops, and a sink fires unless its
+ * kind is in the taint's exclusion set. A binary kill is the special case
+ * where the sanitizer neutralizes the sink's kind; the kind-set model
+ * additionally keeps `const b = escape(req.body); db.query(b)` a FINDING
+ * (an HTML escaper does not neutralize SQL — un-tainting `b` outright would
+ * be a suppressed live injection, the forbidden false-negative direction)
+ * while still suppressing `res.send(b)` (xss IS neutralized).
+ *
+ * - **Occurrence interposition (KTD4a):** evaluated over the U1 site
+ *   structure. An occurrence reaching a sink arg / def-feeding position
+ *   through a matched sanitizer site accumulates that sanitizer's
+ *   `neutralizes` kinds on that PATH; a direct occurrence contributes the
+ *   empty set. Per-position narrowing (`entry.args`) is respected; receiver
+ *   flow through a sanitizer is NOT neutralized (the receiver is not the
+ *   sanitized payload), and spread/template positions are never neutralized
+ *   (position unprovable) — both sound-direction choices (under-kill).
+ * - **Intersection over paths:** a def fed by several occurrence paths
+ *   excludes a kind only when EVERY path neutralizes it
+ *   (`const c = cond ? escape(b) : b` taints `c` with NO exclusions — the
+ *   direct arm's ∅ intersects everything away). Equally, a taint re-derived
+ *   along a second route keeps the INTERSECTION of the exclusion sets and is
+ *   re-processed whenever the set SHRINKS — a less-neutralized taint is
+ *   strictly more dangerous. Exclusion sets only shrink over a finite
+ *   lattice, so the worklist terminates.
+ * - **Kill locality (KTD4b):** a kill applies to the def the sanitizer
+ *   produces (`SiteRecord.resultDefs`) only; the flowing binding's own taint
+ *   is untouched (`const c = escape(b); exec(b)` still finds `b`'s flow).
+ *   `x = escape(x)` works because taint keys on the DEF POINT: the
+ *   sanitizer statement's def enters the set with the sanitizer's kinds
+ *   excluded, while the seed def keeps flowing wherever the CFG still
+ *   carries it (zero-iteration loops, conditional sanitizers — may-path
+ *   mechanics need no special handling here, kills are absent from facts).
+ *
+ * ## Statement-coalescing precision floor (documented FP)
+ *
+ * Statement facts conflate multi-declarator statements: a statement that
+ * uses tainted `b` and defines `c` taints `c` with NO exclusions even when
+ * the two are textually unrelated (`const a = clean(z), b = g(t)` floor-
+ * taints `a` from `t` — pinned by a test). The per-declarator `resultDefs`
+ * precision narrows the EXCLUSION computation (and powers kills) only — a
+ * def in a call's `resultDefs` is fed exactly through that call, so its
+ * exclusions come from the paths into it; when the tainted input provably
+ * never flows into that call, the floor still taints the def (sound) but
+ * records no kill (a kill requires evidence of flow through the sanitizer).
+ *
+ * ## Propagate-through (KTD5)
+ *
+ * Taint in any argument or in the receiver of an UNMODELED call flows to
+ * the call's result defs, marked `viaCall` on the hop so `explain` can
+ * express lower confidence. An occurrence that reaches the unmodeled call
+ * only through a sanitizer carries the neutralization through
+ * (`const y = unknownFn(escape(b))` excludes the sanitizer's kinds — the
+ * plan's deliberate precision choice over flat-conservative).
+ *
+ * ## Kills output
+ *
+ * `kills` records every sanitizer that ACTUALLY neutralized kinds on a
+ * flowing taint — U4 emits `SANITIZES` edges from them. Two shapes share the
+ * record: result-def kills (`killedDef` = the def the sanitizer produces;
+ * `bindingIdx` = that def's binding) and value-position interposition kills
+ * (`exec(escape(x))` — no def exists; `killedDef` = the sink statement's own
+ * point, `bindingIdx` = the interposed binding). Interposition kills are
+ * recorded only when the (input, sink, position) produced no finding — a
+ * bypassed sanitizer (`exec(x + escape(x))`) killed nothing.
+ */
+import { pointKey } from '../cfg/reaching-defs.js';
+import { SINK_KIND_ORDER as KIND_ORDER, sortSinkKinds as sortKinds, } from './source-sink-config.js';
+/**
+ * Default per-function findings cap (U5 config resolution; cfg/emit.ts
+ * DEFAULT_* pattern). Resolved into the RepoMeta `pdg` stamp by
+ * `resolvePdgConfig` so a cap change trips full writeback; `0` = unlimited
+ * is preserved like the other pdg caps. 200 is generous — a real function
+ * with more deduped source→sink findings is a fixture or a disaster, and
+ * the truncation is deterministic + counted (`droppedFindings`).
+ */
+export const DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION = 200;
+/**
+ * Default per-finding hop cap (U5; joins the RepoMeta `pdg` stamp like the
+ * findings cap). Bounds the persisted `reason` hop encoding (KTD6 pins the
+ * hop cap in config); 32 intra-procedural def→use hops is far beyond any
+ * legible path — overflow keeps the source-side prefix and sets
+ * `hopsTruncated`, parsed downstream as "path incomplete", never an error.
+ */
+export const DEFAULT_PDG_MAX_TAINT_HOPS = 32;
+// Canonical SinkKind order + sort live in source-sink-config.ts (shared with
+// the M4 summary harvest so the deterministic order never drifts); imported
+// above as KIND_ORDER / sortKinds. `kindRank` is the local comparator index.
+const kindRank = new Map(KIND_ORDER.map((k, i) => [k, i]));
+const EMPTY_KINDS = new Set();
+const DIRECT_PATH = { kinds: EMPTY_KINDS, viaCall: false, sanitizers: [] };
+/**
+ * Compute taint flows for one function. See the module doc for the two-rule
+ * model, the kind-set exclusion semantics, and the precision floor.
+ */
+export function computeTaintFlows(cfg, defUse, matches, limits) {
+    if (defUse.status !== 'computed') {
+        return {
+            status: 'coverage-gap',
+            gapReason: defUse.status,
+            findings: [],
+            kills: [],
+            droppedFindings: 0,
+        };
+    }
+    const bindings = defUse.bindings;
+    // ── per-statement context (built lazily; statements revisit often) ────────
+    const matchByPoint = new Map();
+    for (const sm of matches.statements) {
+        matchByPoint.set(`${sm.blockIndex}:${sm.statementIndex}`, sm);
+    }
+    const ctxCache = new Map();
+    const contextAt = (blockIndex, stmtIndex) => {
+        const key = `${blockIndex}:${stmtIndex}`;
+        if (ctxCache.has(key))
+            return ctxCache.get(key);
+        const facts = cfg.blocks[blockIndex]?.statements?.[stmtIndex];
+        let ctx;
+        if (facts) {
+            const sm = matchByPoint.get(key);
+            const sinksBySite = new Map();
+            const sanitizersBySite = new Map();
+            for (const s of sm?.sinks ?? []) {
+                const list = sinksBySite.get(s.siteIndex);
+                if (list)
+                    list.push(s);
+                else
+                    sinksBySite.set(s.siteIndex, [s]);
+            }
+            for (const s of sm?.sanitizers ?? []) {
+                const list = sanitizersBySite.get(s.siteIndex);
+                if (list)
+                    list.push(s);
+                else
+                    sanitizersBySite.set(s.siteIndex, [s]);
+            }
+            const resultDefSites = new Map();
+            facts.sites?.forEach((site, siteIndex) => {
+                for (const d of site.resultDefs ?? []) {
+                    const list = resultDefSites.get(d);
+                    if (list)
+                        list.push(siteIndex);
+                    else
+                        resultDefSites.set(d, [siteIndex]);
+                }
+            });
+            ctx = {
+                point: { blockIndex, stmtIndex, line: facts.line },
+                facts,
+                sites: facts.sites ?? [],
+                sinksBySite,
+                sanitizersBySite,
+                resultDefSites,
+            };
+        }
+        ctxCache.set(key, ctx);
+        return ctx;
+    };
+    /** Kinds the matched sanitizers at `siteIndex` neutralize for input position `argPos`. */
+    const neutralizedAt = (ctx, siteIndex, argPos) => {
+        const sans = ctx.sanitizersBySite.get(siteIndex);
+        if (!sans)
+            return [];
+        const site = ctx.sites[siteIndex];
+        // Spread/template positions are never provably the sanitized argument —
+        // do not neutralize (sound: under-kill). Exact positions check `args`.
+        if (site.template === true || (site.spread !== undefined && argPos >= site.spread))
+            return [];
+        const kinds = [];
+        for (const san of sans) {
+            if (san.entry.args === undefined || san.entry.args.includes(argPos)) {
+                kinds.push(...san.entry.neutralizes);
+            }
+        }
+        return sortKinds(kinds);
+    };
+    /** A call/new site the model does not understand (anything but a matched sanitizer). */
+    const isUnmodeledCall = (ctx, siteIndex) => {
+        const site = ctx.sites[siteIndex];
+        return site.kind !== 'member-read' && !ctx.sanitizersBySite.has(siteIndex);
+    };
+    const emerge = (ctx, siteIndex, argPos, inner) => {
+        const added = neutralizedAt(ctx, siteIndex, argPos);
+        return {
+            kinds: added.length === 0 ? inner.kinds : new Set([...inner.kinds, ...added]),
+            viaCall: inner.viaCall || isUnmodeledCall(ctx, siteIndex),
+            sanitizers: added.length === 0 ? inner.sanitizers : [...inner.sanitizers, { siteIndex, kinds: added }],
+        };
+    };
+    /**
+     * STRICT occurrence paths of binding `b` flowing OUT of site `siteIndex`'s
+     * result — found arg entries and the receiver only, each with the site's
+     * own neutralization/viaCall applied. Empty when `b` provably never flows
+     * in (the caller falls back to the floor and records NO kill). `guard`
+     * breaks corrupted-store via cycles (site-safety checks ranges, not
+     * acyclicity).
+     */
+    const flowsOutOf = (ctx, b, siteIndex, guard) => {
+        if (guard.has(siteIndex))
+            return [];
+        guard.add(siteIndex);
+        const site = ctx.sites[siteIndex];
+        const out = [];
+        site.args?.forEach((entries, argPos) => {
+            for (const e of entries) {
+                if (typeof e === 'number') {
+                    if (e === b)
+                        out.push(emerge(ctx, siteIndex, argPos, DIRECT_PATH));
+                }
+                else if (e[0] === b) {
+                    // Via-tagged: the occurrence reaches this position THROUGH the
+                    // nested site. When the nested site shows no recognized channel
+                    // for `b` (callee-chain occurrences — dynamic subscript keys), the
+                    // via-tag is still evidence of flow: fall back to a direct,
+                    // UN-neutralized path (sound: never a false kill).
+                    const inner = flowsOutOf(ctx, b, e[1], guard);
+                    const paths = inner.length > 0
+                        ? inner
+                        : [{ ...DIRECT_PATH, viaCall: isUnmodeledCall(ctx, e[1]) }];
+                    for (const p of paths)
+                        out.push(emerge(ctx, siteIndex, argPos, p));
+                }
+            }
+        });
+        if (site.receiver === b) {
+            // Receiver TITO (KTD5): the receiver's value flows through the call
+            // into its result — but a sanitizer does not neutralize its receiver.
+            out.push({ ...DIRECT_PATH, viaCall: isUnmodeledCall(ctx, siteIndex) });
+        }
+        guard.delete(siteIndex);
+        return out;
+    };
+    /** Occurrence paths of `b` INTO sink position (s, p) — no emergence from s. */
+    const pathsIntoPosition = (ctx, b, siteIndex, argPos) => {
+        const entries = ctx.sites[siteIndex].args?.[argPos] ?? [];
+        const out = [];
+        for (const e of entries) {
+            if (typeof e === 'number') {
+                if (e === b)
+                    out.push(DIRECT_PATH);
+            }
+            else if (e[0] === b) {
+                const inner = flowsOutOf(ctx, b, e[1], new Set());
+                if (inner.length > 0)
+                    out.push(...inner);
+                else
+                    out.push({ ...DIRECT_PATH, viaCall: isUnmodeledCall(ctx, e[1]) });
+            }
+        }
+        return out;
+    };
+    /**
+     * Walk a SOURCE member-read's `parent` chain. Linear (each site has one
+     * parent); invokes `onPosition` with the accumulated path BEFORE the
+     * ancestor's own emergence (the value flows INTO the ancestor at that
+     * position) — sink checks and stop-at-site joins both hang off it.
+     */
+    const climbSourceChain = (ctx, srcSiteIndex, onPosition) => {
+        const visited = new Set([srcSiteIndex]);
+        let cur = ctx.sites[srcSiteIndex];
+        let sofar = DIRECT_PATH;
+        while (cur.parent) {
+            const [siteIndex, argPos] = cur.parent;
+            if (visited.has(siteIndex))
+                return; // corrupted-store parent cycle
+            visited.add(siteIndex);
+            if (onPosition(siteIndex, argPos, sofar))
+                return;
+            sofar = emerge(ctx, siteIndex, argPos, sofar);
+            cur = ctx.sites[siteIndex];
+        }
+    };
+    /** Source path INTO site `target` (with target's emergence), or undefined. */
+    const sourceFlowsOutOf = (ctx, srcSiteIndex, target) => {
+        let found;
+        climbSourceChain(ctx, srcSiteIndex, (siteIndex, argPos, sofar) => {
+            if (siteIndex !== target)
+                return false;
+            found = emerge(ctx, target, argPos, sofar);
+            return true;
+        });
+        return found;
+    };
+    // ── accumulators ──────────────────────────────────────────────────────────
+    const findingsByIdentity = new Map();
+    const killsByIdentity = new Map();
+    const recordKill = (sanitizer, killedDef, bindingIdx, kinds) => {
+        if (kinds.length === 0)
+            return;
+        const key = `${pointKey(sanitizer)}|${pointKey(killedDef)}|${bindingIdx}`;
+        const existing = killsByIdentity.get(key);
+        if (existing)
+            for (const k of kinds)
+                existing.kinds.add(k);
+        else
+            killsByIdentity.set(key, {
+                kill: { sanitizer, killedDef, bindingIdx },
+                kinds: new Set(kinds),
+            });
+    };
+    // KTD6 statement-level finding identity: source occurrence + sink occurrence
+    // + kind (NOT entryName). Computed standalone so the worklist can dedup-check
+    // BEFORE the cost of chainHops (first write wins; dedup-before-budget).
+    const findingKey = (sinkKind, source, sink) => [
+        sinkKind,
+        pointKey(source.point),
+        source.siteIndex,
+        source.objectBindingIdx,
+        source.property,
+        pointKey(sink.point),
+        sink.siteIndex,
+        sink.argIndex,
+        sink.bindingIdx,
+    ].join('|');
+    const recordFinding = (sinkKind, source, sink, hops, hopsTruncated) => {
+        const key = findingKey(sinkKind, source, sink);
+        if (findingsByIdentity.has(key))
+            return;
+        const maxHops = limits?.maxHops && limits.maxHops > 0 ? limits.maxHops : Infinity;
+        let truncated = hopsTruncated;
+        let kept = hops;
+        if (hops.length > maxHops) {
+            kept = hops.slice(0, maxHops);
+            truncated = true;
+        }
+        findingsByIdentity.set(key, {
+            sinkKind,
+            source,
+            sink,
+            hops: kept,
+            ...(truncated ? { hopsTruncated: true } : {}),
+        });
+    };
+    // ── taint state ───────────────────────────────────────────────────────────
+    const taints = new Map();
+    const queue = [];
+    /** The (binding, def-point) portion of a state key — the def→use fact-table
+     *  lookup key, source-independent. */
+    const defKey = (bindingIdx, point) => `${bindingIdx}:${pointKey(point)}`;
+    /** Full taint-state key: the def-point portion plus a ROOT source-occurrence
+     *  discriminator ({point, siteIndex} — the same source fields recordFinding's
+     *  identity uses, deliberately excluding `kind`). Distinct sources reaching
+     *  one def get distinct states, so a second source is no longer dropped
+     *  (KTD6); same-source multi-path derivations still share a key so their
+     *  exclusion sets intersect (the raw arm soundly wins). */
+    const stateKey = (bindingIdx, point, source) => `${defKey(bindingIdx, point)}#${pointKey(source.point)}:${source.siteIndex}`;
+    const deriveTaint = (bindingIdx, point, exclusions, parentKey, source, viaCall) => {
+        const key = stateKey(bindingIdx, point, source);
+        const existing = taints.get(key);
+        if (!existing) {
+            taints.set(key, {
+                bindingIdx,
+                point,
+                exclusions,
+                parentKey,
+                source,
+                viaCall,
+                processedSize: -1,
+            });
+            queue.push(key);
+            return;
+        }
+        // Monotone shrink: keep the intersection; re-process only when it got
+        // strictly smaller (a less-neutralized derivation is more dangerous).
+        const inter = new Set();
+        for (const k of existing.exclusions)
+            if (exclusions.has(k))
+                inter.add(k);
+        if (inter.size < existing.exclusions.size) {
+            existing.exclusions = inter;
+            existing.parentKey = parentKey;
+            existing.source = source;
+            existing.viaCall = viaCall;
+            queue.push(key);
+        }
+    };
+    /** Taint-chain hops from seed to `key`, with a cycle guard (re-derivation
+     *  can rewire parents into a loop — truncate instead of spinning). */
+    const chainHops = (key) => {
+        const reversed = [];
+        const seen = new Set();
+        let cur = key;
+        let truncated = false;
+        while (cur !== undefined) {
+            if (seen.has(cur)) {
+                truncated = true;
+                break;
+            }
+            seen.add(cur);
+            const t = taints.get(cur);
+            if (!t)
+                break;
+            reversed.push({
+                bindingIdx: t.bindingIdx,
+                name: bindings[t.bindingIdx]?.name ?? `#${t.bindingIdx}`,
+                point: t.point,
+                ...(t.viaCall ? { viaCall: true } : {}),
+            });
+            cur = t.parentKey;
+        }
+        return { hops: reversed.reverse(), truncated };
+    };
+    /** Intersection of path kind-sets; viaCall = any path through a call. */
+    const summarizePaths = (paths) => {
+        let kinds;
+        let viaCall = false;
+        for (const p of paths) {
+            viaCall ||= p.viaCall;
+            if (kinds === undefined) {
+                kinds = p.kinds;
+            }
+            else {
+                const inter = new Set();
+                for (const k of kinds)
+                    if (p.kinds.has(k))
+                        inter.add(k);
+                kinds = inter;
+            }
+        }
+        return { kinds: kinds ?? EMPTY_KINDS, viaCall };
+    };
+    /**
+     * Taint every def of `ctx`'s statement from one input. `pathsInto(c)`
+     * supplies the input's strict occurrence paths into call site `c` —
+     * defining the resultDefs precision and the kill evidence; an empty list
+     * means "no provable flow" and the floor applies (taint with the input's
+     * own exclusions, no kill).
+     */
+    const feedDefs = (ctx, inputExclusions, parentKey, source, pathsInto) => {
+        const defs = [...ctx.facts.defs, ...(ctx.facts.mayDefs ?? [])];
+        if (defs.length === 0)
+            return;
+        const seen = new Set();
+        for (const d of defs) {
+            if (seen.has(d))
+                continue;
+            seen.add(d);
+            const rdSites = ctx.resultDefSites.get(d);
+            let addKinds = EMPTY_KINDS;
+            let viaCall = false;
+            if (rdSites) {
+                const paths = [];
+                for (const c of rdSites)
+                    paths.push(...pathsInto(c));
+                if (paths.length > 0) {
+                    const summary = summarizePaths(paths);
+                    addKinds = summary.kinds;
+                    viaCall = summary.viaCall;
+                    for (const p of paths) {
+                        for (const san of p.sanitizers) {
+                            recordKill(ctx.point, ctx.point, d, san.kinds);
+                        }
+                    }
+                }
+                // else: floor — tainted with no exclusions added, no kill (the input
+                // provably never flows into the producing call; conflation FP pinned).
+            }
+            const exclusions = addKinds.size === 0 ? inputExclusions : new Set([...inputExclusions, ...addKinds]);
+            deriveTaint(d, ctx.point, exclusions, parentKey, source, viaCall);
+        }
+    };
+    // ── rule (b) + seeding: statements with matched sources ───────────────────
+    for (const sm of matches.statements) {
+        if (sm.sources.length === 0)
+            continue;
+        const ctx = contextAt(sm.blockIndex, sm.statementIndex);
+        if (!ctx)
+            continue;
+        for (const src of sm.sources) {
+            const srcSite = ctx.sites[src.siteIndex];
+            if (srcSite?.object === undefined || srcSite.property === undefined)
+                continue;
+            const sourceOcc = {
+                point: ctx.point,
+                siteIndex: src.siteIndex,
+                objectBindingIdx: srcSite.object,
+                property: srcSite.property,
+                kind: src.entry.kind,
+            };
+            // Statement-local sink checks along the member-read's parent chain.
+            climbSourceChain(ctx, src.siteIndex, (siteIndex, argPos, sofar) => {
+                for (const sink of ctx.sinksBySite.get(siteIndex) ?? []) {
+                    if (!sink.argPositions.includes(argPos))
+                        continue;
+                    const kind = sink.entry.kind;
+                    if (!sofar.kinds.has(kind)) {
+                        recordFinding(kind, sourceOcc, {
+                            point: ctx.point,
+                            siteIndex,
+                            argIndex: argPos,
+                            bindingIdx: srcSite.object,
+                            entryName: sink.entry.name,
+                        }, [
+                            {
+                                bindingIdx: srcSite.object,
+                                name: bindings[srcSite.object]?.name ?? `#${srcSite.object}`,
+                                point: ctx.point,
+                                ...(sofar.viaCall ? { viaCall: true } : {}),
+                            },
+                        ], false);
+                    }
+                    else {
+                        for (const san of sofar.sanitizers) {
+                            if (san.kinds.includes(kind)) {
+                                recordKill(ctx.point, ctx.point, srcSite.object, san.kinds);
+                            }
+                        }
+                    }
+                }
+                return false;
+            });
+            // Seed every def of the statement (precision floor + resultDefs kills).
+            feedDefs(ctx, EMPTY_KINDS, undefined, sourceOcc, (c) => {
+                const p = sourceFlowsOutOf(ctx, src.siteIndex, c);
+                return p ? [p] : [];
+            });
+        }
+    }
+    // ── rule (a): worklist over def→use facts ─────────────────────────────────
+    const factsByDef = new Map();
+    for (const f of defUse.facts) {
+        const key = defKey(f.bindingIdx, f.def);
+        const list = factsByDef.get(key);
+        if (list)
+            list.push(f);
+        else
+            factsByDef.set(key, [f]);
+    }
+    // Strict-FIFO worklist via a head cursor (not Array.shift, which is O(N) per
+    // dequeue). FIFO order is load-bearing beyond perf: chainHops reconstructs
+    // hops from the live `taints` map, whose parentKey/source/viaCall are
+    // rewritten order-sensitively on monotone shrink — so hop-content
+    // determinism is contingent on dequeue order matching enqueue order. Do NOT
+    // sort or reprioritize the worklist.
+    let head = 0;
+    while (head < queue.length) {
+        const key = queue[head++];
+        // Reclaim the consumed prefix periodically so the array doesn't grow
+        // unbounded across a long run (order-preserving — pure memory hygiene).
+        if (head > 1024 && head * 2 > queue.length) {
+            queue.splice(0, head);
+            head = 0;
+        }
+        const t = taints.get(key);
+        if (t.processedSize === t.exclusions.size)
+            continue; // no-op requeue
+        t.processedSize = t.exclusions.size;
+        const b = t.bindingIdx;
+        const E = t.exclusions;
+        // Facts are keyed by (binding, def-point) only — look up by the def portion
+        // of this state, not the source-discriminated state key.
+        for (const fact of factsByDef.get(defKey(b, t.point)) ?? []) {
+            const ctx = contextAt(fact.use.blockIndex, fact.use.stmtIndex);
+            if (!ctx)
+                continue;
+            // Sink check: occurrences of `b` at matched sink argument positions.
+            for (const [siteIndex, sinks] of ctx.sinksBySite) {
+                for (const sink of sinks) {
+                    const kind = sink.entry.kind;
+                    for (const argPos of sink.argPositions) {
+                        const paths = pathsIntoPosition(ctx, b, siteIndex, argPos);
+                        if (paths.length === 0)
+                            continue;
+                        if (E.has(kind))
+                            continue; // suppressed at def time; kill already recorded
+                        const justify = paths.find((p) => !p.kinds.has(kind));
+                        if (justify) {
+                            const sinkOcc = {
+                                point: ctx.point,
+                                siteIndex,
+                                argIndex: argPos,
+                                bindingIdx: b,
+                                entryName: sink.entry.name,
+                            };
+                            // Dedup BEFORE chainHops: already-recorded identities discard
+                            // their hop chain anyway (first write wins), so skip the walk.
+                            if (findingsByIdentity.has(findingKey(kind, t.source, sinkOcc)))
+                                continue;
+                            const chain = chainHops(key);
+                            chain.hops.push({
+                                bindingIdx: b,
+                                name: bindings[b]?.name ?? `#${b}`,
+                                point: ctx.point,
+                                ...(justify.viaCall ? { viaCall: true } : {}),
+                            });
+                            recordFinding(kind, t.source, sinkOcc, chain.hops, chain.truncated);
+                        }
+                        else {
+                            // EVERY path interposed — value-position kill(s) held.
+                            for (const p of paths) {
+                                for (const san of p.sanitizers) {
+                                    if (san.kinds.includes(kind))
+                                        recordKill(ctx.point, ctx.point, b, san.kinds);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // Def-feed: the use statement's own defs become tainted.
+            feedDefs(ctx, E, key, t.source, (c) => flowsOutOf(ctx, b, c, new Set()));
+        }
+    }
+    // ── deterministic assembly ────────────────────────────────────────────────
+    const comparePoints = (a, b) => a.blockIndex - b.blockIndex || a.stmtIndex - b.stmtIndex;
+    const findings = [...findingsByIdentity.values()].sort((a, b) => comparePoints(a.source.point, b.source.point) ||
+        a.source.siteIndex - b.source.siteIndex ||
+        comparePoints(a.sink.point, b.sink.point) ||
+        a.sink.siteIndex - b.sink.siteIndex ||
+        a.sink.argIndex - b.sink.argIndex ||
+        a.sink.bindingIdx - b.sink.bindingIdx ||
+        (kindRank.get(a.sinkKind) ?? 99) - (kindRank.get(b.sinkKind) ?? 99));
+    const maxFindings = limits?.maxFindingsPerFunction && limits.maxFindingsPerFunction > 0
+        ? limits.maxFindingsPerFunction
+        : Infinity;
+    const kept = findings.length > maxFindings ? findings.slice(0, maxFindings) : findings;
+    const kills = [...killsByIdentity.values()]
+        .map(({ kill, kinds }) => ({ ...kill, neutralized: sortKinds(kinds) }))
+        .sort((a, b) => comparePoints(a.sanitizer, b.sanitizer) ||
+        comparePoints(a.killedDef, b.killedDef) ||
+        a.bindingIdx - b.bindingIdx);
+    return {
+        status: 'computed',
+        findings: kept,
+        kills,
+        droppedFindings: findings.length - kept.length,
+    };
+}

package/dist/core/ingestion/taint/site-safety.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Taint-site safety validation (#2083 M3 U1, plan KTD2).
+ *
+ * Mirrors `hasEmitSafeFacts` (cfg/emit.ts): an untrusted `cfgSideChannel`
+ * element — possibly from a corrupted durable parsedfile store — must never
+ * crash the taint pass or fabricate matches from out-of-range indices. The
+ * degradation contract is per-FUNCTION and one-directional: a CFG whose sites
+ * fail this check is SKIPPED FOR TAINT ONLY — the BasicBlock/CFG layer and
+ * the REACHING_DEF projection (guarded by their own checks) are unaffected.
+ *
+ * Checked: exactly the indices the taint matcher dereferences — binding
+ * indices (`receiver`/`object`/`resultDefs`/arg occurrences) against the
+ * function's binding table, and intra-statement site references (`parent`
+ * site / via-tags) against the OWNING statement's `sites` array. Site
+ * references are statement-local by construction (each statement's
+ * FactAccumulator starts at index 0); a cross-statement reference is
+ * corruption, not a feature.
+ *
+ * Lives in `taint/` (not cfg/emit.ts): U4's taint emit path is the only
+ * consumer, and the guard must evolve with the matcher that dereferences
+ * these fields.
+ */
+import type { FunctionCfg } from '../cfg/types.js';
+/**
+ * Whether a structurally-valid CFG's M3 `sites` annotations are safe to feed
+ * to the taint matcher/propagator. `true` when no statement carries sites
+ * (pre-M3 channel, or no calls) — absence is the well-formed empty case.
+ */
+export declare const hasTaintSafeSites: (cfg: FunctionCfg) => boolean;