gitnexus 1.6.8-rc.8 → 1.6.8

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

@@ -0,0 +1,125 @@
+/**
+ * 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 ReachingDefsSolver } from '../cfg/reaching-defs.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, solve?: ReachingDefsSolver): TaintEmitResult;

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

@@ -0,0 +1,208 @@
+/**
+ * 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, 
+// U12: shared per-file memoized solver (harvest/taint bucket — no maxBlockVisits).
+// The zero-match fast path below still skips the solve entirely; only MATCHED
+// functions request it, hitting the cache the call-summary harvest warmed.
+solve = computeReachingDefs) {
+    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 = solve(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/interproc-emit.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Interprocedural taint emission (#2084 M4 U4) — materialise `TAINT_PATH`.
+ *
+ * Persists each cross-function {@link InterprocFinding} as ONE `TAINT_PATH`
+ * edge from the source function node to the sink function node, with the
+ * function-level hop chain + sink kind encoded in `reason` via the SHARED
+ * `path-codec` (the same versioned wire format M3's intra-procedural `TAINTED`
+ * edges use — never a second hand-rolled codec). The MCP `explain` tool decodes
+ * it for cross-function path rendering (U7).
+ *
+ * `TAINT_PATH` was reserved at M0 (the RelationshipType + the `CodeRelation`
+ * Function/Method node-pairs already exist), so materialisation needs zero
+ * schema work. Like `TAINTED`, it stays out of `VALID_RELATION_TYPES` and the
+ * web schema — `explain` is the discovery surface.
+ *
+ * Boundedness mirrors the M3 emit driver: dedup-before-cap (the solver already
+ * deduped by `(source, sink, kind)`), a per-run findings cap, and unconditional
+ * truncate-and-warn — never a silent drop.
+ */
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { InterprocFinding } from './interproc-solver.js';
+/** Confidence stamped on interprocedural `TAINT_PATH` edges. Lower than the
+ *  intra-procedural `TAINTED` 1.0 — context-insensitive composition is a
+ *  coarser signal (return/call-site merging). */
+export declare const INTERPROC_TAINT_CONFIDENCE = 0.6;
+/**
+ * Default per-run cap on emitted `TAINT_PATH` edges (#2084 review P1-3).
+ * Resolved into `RepoMeta.pdg` like the other pdg caps; `0` ⇒ unlimited.
+ */
+export declare const DEFAULT_PDG_MAX_INTERPROC_EDGES = 1000;
+export interface InterprocEmitLimits {
+    /** Max `TAINT_PATH` edges per run (post-dedup). `undefined`/0 ⇒ unlimited. */
+    readonly maxEdges?: number;
+}
+export interface InterprocEmitResult {
+    /** TAINT_PATH edges persisted. */
+    edgesEmitted: number;
+    /** Findings dropped by the per-run cap. */
+    edgesDropped: number;
+    /** Findings whose persisted hop path is a truncated prefix. */
+    hopsTruncated: number;
+    /** Findings skipped because an endpoint node was missing from the graph. */
+    skippedMissingEndpoint: number;
+}
+/**
+ * Persist cross-function findings as `TAINT_PATH` edges. `findings` is assumed
+ * deduped + deterministically ordered (the solver's contract). Never throws on
+ * valid input.
+ */
+export declare function emitInterprocTaint(graph: KnowledgeGraph, findings: readonly InterprocFinding[], limits?: InterprocEmitLimits, onWarn?: (message: string) => void): InterprocEmitResult;

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

@@ -0,0 +1,88 @@
+/**
+ * Interprocedural taint emission (#2084 M4 U4) — materialise `TAINT_PATH`.
+ *
+ * Persists each cross-function {@link InterprocFinding} as ONE `TAINT_PATH`
+ * edge from the source function node to the sink function node, with the
+ * function-level hop chain + sink kind encoded in `reason` via the SHARED
+ * `path-codec` (the same versioned wire format M3's intra-procedural `TAINTED`
+ * edges use — never a second hand-rolled codec). The MCP `explain` tool decodes
+ * it for cross-function path rendering (U7).
+ *
+ * `TAINT_PATH` was reserved at M0 (the RelationshipType + the `CodeRelation`
+ * Function/Method node-pairs already exist), so materialisation needs zero
+ * schema work. Like `TAINTED`, it stays out of `VALID_RELATION_TYPES` and the
+ * web schema — `explain` is the discovery surface.
+ *
+ * Boundedness mirrors the M3 emit driver: dedup-before-cap (the solver already
+ * deduped by `(source, sink, kind)`), a per-run findings cap, and unconditional
+ * truncate-and-warn — never a silent drop.
+ */
+import { encodeTaintPath } from './path-codec.js';
+/** Confidence stamped on interprocedural `TAINT_PATH` edges. Lower than the
+ *  intra-procedural `TAINTED` 1.0 — context-insensitive composition is a
+ *  coarser signal (return/call-site merging). */
+export const INTERPROC_TAINT_CONFIDENCE = 0.6;
+/**
+ * Default per-run cap on emitted `TAINT_PATH` edges (#2084 review P1-3).
+ * Resolved into `RepoMeta.pdg` like the other pdg caps; `0` ⇒ unlimited.
+ */
+export const DEFAULT_PDG_MAX_INTERPROC_EDGES = 1000;
+/**
+ * Persist cross-function findings as `TAINT_PATH` edges. `findings` is assumed
+ * deduped + deterministically ordered (the solver's contract). Never throws on
+ * valid input.
+ */
+export function emitInterprocTaint(graph, findings, limits, onWarn) {
+    const result = {
+        edgesEmitted: 0,
+        edgesDropped: 0,
+        hopsTruncated: 0,
+        skippedMissingEndpoint: 0,
+    };
+    const maxEdges = limits?.maxEdges && limits.maxEdges > 0 ? limits.maxEdges : Infinity;
+    const seen = new Set();
+    for (const finding of findings) {
+        if (result.edgesEmitted >= maxEdges) {
+            result.edgesDropped++;
+            continue;
+        }
+        const sourceNode = graph.getNode(finding.sourceFnId);
+        const sinkNode = graph.getNode(finding.sinkFnId);
+        if (!sourceNode || !sinkNode) {
+            result.skippedMissingEndpoint++;
+            continue;
+        }
+        // Map function hops → codec hops. The hop "name" is the function's display
+        // name (identifier charset — codec-safe); the line is its start line.
+        const hops = finding.hops.map((h) => {
+            const node = graph.getNode(h.fnId);
+            const name = typeof node?.properties.name === 'string' ? node.properties.name : 'fn';
+            const line = typeof node?.properties.startLine === 'number' ? node.properties.startLine : 0;
+            return { name, line };
+        });
+        const encoded = encodeTaintPath(hops, {
+            kind: finding.sinkKind,
+            truncated: finding.hopsTruncated,
+        });
+        if (encoded.truncated)
+            result.hopsTruncated++;
+        const id = `rel:TAINT_PATH:${finding.sinkKind}:${finding.sourceFnId}=>${finding.sinkFnId}`;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        graph.addRelationship({
+            id,
+            sourceId: finding.sourceFnId,
+            targetId: finding.sinkFnId,
+            type: 'TAINT_PATH',
+            confidence: INTERPROC_TAINT_CONFIDENCE,
+            reason: encoded.reason,
+        });
+        result.edgesEmitted++;
+    }
+    if (result.edgesDropped > 0) {
+        onWarn?.(`[taint-interproc] ${result.edgesDropped} cross-function finding(s) dropped by the ` +
+            `per-run TAINT_PATH cap (${maxEdges})`);
+    }
+    return result;
+}

package/dist/core/ingestion/taint/interproc-solver.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Interprocedural taint fixpoint (#2084 M4 U3).
+ *
+ * Composes per-function {@link FunctionSummary} objects over the resolved
+ * `CALLS` graph to find source→sink flows that cross function and file
+ * boundaries. PURE AND DETERMINISTIC (no graph, no I/O, no logger) — the phase
+ * builds the inputs from `ctx.graph` and persists the outputs.
+ *
+ * ## The model — whole-parameter taint reachability
+ *
+ * The unit of taint is `(function, parameter)`. The fixpoint computes the set
+ * of parameters that can hold source-derived data, then fires a finding
+ * whenever a tainted parameter feeds a modelled sink (`paramToSink`).
+ *
+ * - **Seeds** — every `sourceToCallArg` edge: a function generates a source and
+ *   passes it into argument `argIndex` of a call at `callLine`. Resolving that
+ *   call site against the caller's outgoing `CALLS` edges yields the callee;
+ *   the callee's parameter `argIndex` becomes tainted, with the generating
+ *   function recorded as the flow's source.
+ * - **Propagation** — every `paramToCallArg` edge of a function whose parameter
+ *   is ALREADY tainted: `param i → arg j of callee` taints the callee's
+ *   parameter `j` (TITO composition). Iterated to a fixpoint.
+ * - **Findings** — whenever a parameter becomes tainted and the owning
+ *   function's `paramToSink` contains that parameter, a cross-function finding
+ *   is emitted (source function → sink function, with the kind).
+ *
+ * ## Cycle safety (recursion)
+ *
+ * The tainted-parameter set is monotone over a FINITE lattice (`Σ functions ×
+ * params`), so the worklist fixpoint converges: a recursive or mutually
+ * recursive call merely re-proposes an already-tainted parameter, which the
+ * visited-set absorbs — no infinite descent. This is the functional/summary
+ * method's standard termination argument (Sharir-Pnueli; Pysa, Mariana Trench,
+ * and Infer all rely on it). SCC condensation would only refine the PROCESSING
+ * ORDER; correctness and termination do not require it.
+ *
+ * ## Context-insensitivity & the name-join over-approximation
+ *
+ * One summary per function, applied at every call site — return/param merging
+ * is accepted (the security-conservative direction). The call-arg→callee join
+ * is by callee NAME (not line), so when one caller invokes two DISTINCT
+ * same-named callees (`x.handler(src)` and `y.handler(clean)`), a source that
+ * flowed into ONE of them taints BOTH callees' parameter — an extra finding on
+ * the callee the source did not reach. This is sound (over-attribution, never a
+ * missed flow — the conservative direction for a security tool) and is the
+ * documented price of dropping the fragile line-based join; the `explain` tool
+ * surfaces it ("may over-attribute among same-named callees"). Other known
+ * precision losses (call-site conflation, shared dispatch, callbacks) are the
+ * documented M4 trade-offs; refinements are deferred (plan KTD).
+ */
+import type { SinkKind } from './source-sink-config.js';
+import type { FunctionSummary } from './summary-model.js';
+/**
+ * One resolved call edge from the `CALLS` graph. The join to a summary's
+ * call-arg edge is by CALLEE NAME (the callee node's declared name), NOT by
+ * call-site line — line-base parity between the CFG harvest (1-based) and the
+ * reference site is fragile, while the callee identity is exact and the
+ * context-insensitive model tatints the callee's parameter the same way at
+ * every call site to it.
+ */
+export interface InterprocCallEdge {
+    readonly callerId: string;
+    readonly calleeId: string;
+    /** The callee node's declared name (`helper`, `process`) — the join key. */
+    readonly calleeName: string;
+}
+/** One hop of a cross-function flow: the function entered, and how. */
+export interface InterprocHop {
+    readonly fnId: string;
+    /** The call-site line in the PREVIOUS function that entered this one. */
+    readonly callLine?: number;
+    /** Argument position the taint entered through (undefined for the source fn). */
+    readonly argIndex?: number;
+}
+export interface InterprocFinding {
+    readonly sourceFnId: string;
+    readonly sinkFnId: string;
+    readonly sinkKind: SinkKind;
+    /** Ordered source→sink hop chain (functions). A prefix when `truncated`. */
+    readonly hops: readonly InterprocHop[];
+    readonly hopsTruncated: boolean;
+}
+export interface InterprocLimits {
+    /** Max functions in a single flow's hop chain. `undefined`/0 ⇒ default 32. */
+    readonly maxHops?: number;
+    /** Max findings overall (post-dedup). `undefined`/0 ⇒ unlimited. */
+    readonly maxFindings?: number;
+}
+export interface InterprocResult {
+    readonly findings: readonly InterprocFinding[];
+    /** Findings dropped by `maxFindings` (post-dedup). */
+    readonly droppedFindings: number;
+    /** Call edges whose call-site line matched no summary edge (diagnostics). */
+    readonly unmatchedCallSites: number;
+}
+export declare const DEFAULT_MAX_INTERPROC_HOPS = 32;
+/**
+ * Default per-run cap on cross-function findings (#2084 review P1-3). Like the
+ * other pdg caps it is resolved into `RepoMeta.pdg` so `pdgModeMismatch`
+ * stamps it; `0` ⇒ unlimited. 2000 is generous for a real repo — more deduped
+ * `(source, sink, kind)` findings than that is a fixture or a runaway fan-in,
+ * and the overflow is deterministic + counted (`droppedFindings`).
+ */
+export declare const DEFAULT_PDG_MAX_INTERPROC_FINDINGS = 2000;
+/**
+ * Run the interprocedural taint fixpoint. `summaries` is keyed by function node
+ * id; `callEdges` is the resolved `CALLS` graph (caller→callee with call-site
+ * lines). Deterministic: inputs in, sorted findings out.
+ */
+export declare function solveInterprocTaint(summaries: ReadonlyMap<string, FunctionSummary>, callEdges: readonly InterprocCallEdge[], limits?: InterprocLimits): InterprocResult;