gitnexus 1.6.8-rc.21 → 1.6.8-rc.23

package/dist/core/ingestion/taint/summary-model.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Per-function taint SUMMARY model (#2084 M4 U2).
+ *
+ * A {@link FunctionSummary} is the compact, context-insensitive abstraction of
+ * one function's taint behaviour — the input to the interprocedural fixpoint
+ * (`interproc-solver.ts`). It is the GitNexus analogue of Pysa's `.pysa`
+ * models, Mariana Trench's "propagations", and CodeQL Models-as-Data summary
+ * rows: a function is reduced to how taint enters (params / generated sources),
+ * how it moves through (param→return, param→callee-arg), and where it lands
+ * (param→sink). The fixpoint composes these across resolved `CALLS` edges so a
+ * source in one function reaches a sink in another.
+ *
+ * ## Why summaries (not whole-program IFDS)
+ *
+ * The functional/summary method (Sharir-Pnueli 1981) analyses each function
+ * ONCE and propagates the result over the call graph — the same shape Pysa,
+ * Mariana Trench, and Infer use in production. GitNexus already resolves the
+ * call graph (`CALLS` edges carry final node ids), so the summary IS the only
+ * new artifact; propagation is graph reachability over a finite lattice.
+ *
+ * ## Granularity (first cut)
+ *
+ * WHOLE-PARAMETER. Ports are `param i`, `return`, and `receiver` — no field
+ * access paths (`arg0.field.sub`). Field sensitivity, callback-parameter ports
+ * (`Argument[0].Parameter[0]`), and context sensitivity are deferred (plan
+ * KTD; the largest JS/TS FN class — closures — stays a documented gap).
+ *
+ * ## Plain-data discipline
+ *
+ * A summary is a JSON-plain value type (no functions, class instances, Maps, or
+ * Symbols) so it survives `RunScopeResolutionStats` → `ScopeResolutionOutput`
+ * threading and any future worker/cache boundary unchanged — the same
+ * `Cloneable` constraint the CFG side channel obeys.
+ */
+import type { SinkKind, SourceKind } from './source-sink-config.js';
+/**
+ * Source-relative parameter index (0-based, in declaration order). A
+ * function's first parameter is `0`. Destructured / rest params map each bound
+ * name to the index of the formal parameter that introduced it (so
+ * `function f([a, b]) {}` binds both `a` and `b` to param `0`).
+ */
+export type ParamIndex = number;
+/**
+ * `param i` flows into argument `argIndex` of a call at source line `callLine`.
+ * The interprocedural solver joins this to the caller's outgoing `CALLS` edges
+ * by CALLEE NAME (`calleeName`) — NOT by `callLine` — because line-base parity
+ * between the CFG harvest (1-based) and the resolved reference site is fragile,
+ * while the callee identity is exact. It then applies the callee's summary at
+ * port `param argIndex`. This is the TITO ("taint-in-taint-out") propagation
+ * edge — a param laundered into a callee, the callee's behaviour deciding what
+ * happens next.
+ *
+ * `calleeName` is the site's dotted-callee tail (best-effort); absent when the
+ * callee chain was not statically resolvable, in which case the solver
+ * conservatively matches every outgoing call (sound over-approximation).
+ * `callLine` is the 1-based statement line as harvested (`StatementFacts.line`)
+ * — carried for hop display and as a TIE-BREAKER among several same-named
+ * callees of one caller, never as the primary join key.
+ */
+export interface ParamToCallArg {
+    readonly param: ParamIndex;
+    readonly callLine: number;
+    readonly argIndex: number;
+    readonly calleeName?: string;
+    /**
+     * Sink kinds neutralised on EVERY harvested path from the param to this call
+     * argument (intersection-over-paths, #2084 review P1-2). A sanitizer between
+     * the param and the callee arg (`relay(x){ const y=escape(x); sinkFn(y); }`)
+     * must carry across the boundary so the callee's `paramToSink` of a
+     * neutralised kind does not fire (the cross-function false positive). Absent
+     * means none neutralised.
+     */
+    readonly neutralized?: readonly SinkKind[];
+}
+/**
+ * `param i` flows to the function's return value (a `return <expr>` use).
+ *
+ * RESERVED — not yet consumed by the fixpoint (#2084 review P1-1). The M3
+ * statement-level floor already treats every call as propagate-through, so it
+ * taints a callee's RESULT whenever the caller passes tainted input; param→
+ * return recall is therefore already covered, and consuming `paramToReturn`
+ * would only add PRECISION (avoiding the floor's over-approximation for
+ * functions that don't actually return their param) — a larger refactor
+ * deferred. Harvested + version-stamped so the precision pass can land without
+ * a cache-namespace bump.
+ */
+export interface ParamToReturn {
+    readonly param: ParamIndex;
+    /** Sink kinds neutralised on EVERY path param→return (intersection). */
+    readonly neutralized?: readonly SinkKind[];
+}
+/** `param i` reaches a modelled sink of kind `sinkKind` inside this function. */
+export interface ParamToSink {
+    readonly param: ParamIndex;
+    readonly sinkKind: SinkKind;
+}
+/**
+ * The function itself GENERATES a source (a modelled source read, e.g.
+ * `req.body`) that reaches its return value — calling it yields tainted data
+ * with no tainted input required. The generative analogue of Pysa's
+ * `TaintSource[...]` return model. CONSUMED by the fixpoint via the caller's
+ * {@link CallResult} edges (#2084 review P1-1): a caller that uses such a
+ * function's result composes this into a finding/propagation. This is the
+ * genuinely-additive recall the floor cannot cover (the source is inside the
+ * callee — the caller passes no tainted input for the floor to propagate).
+ */
+export interface SourceToReturn {
+    readonly sourceKind: SourceKind;
+}
+/**
+ * What a user-function call's RESULT flows into, in the CALLER (#2084 review
+ * P1-1). Recorded when a call to a (potentially generative) user function has
+ * its return value used by the caller. The fixpoint composes it with the
+ * callee's {@link SourceToReturn}: if the callee returns a generated source,
+ * the caller's downstream use of the result is tainted.
+ */
+export type CallResultDest = {
+    readonly to: 'sink';
+    readonly sinkKind: SinkKind;
+} | {
+    readonly to: 'return';
+} | {
+    readonly to: 'callArg';
+    readonly toCallee?: string;
+    readonly argIndex: ParamIndex;
+};
+/** The result of a call to `calleeName` flows to `dest` in this function. */
+export interface CallResult {
+    readonly calleeName: string;
+    readonly dest: CallResultDest;
+}
+/**
+ * A modelled source generated in this function flows into argument `argIndex`
+ * of a call at `callLine`. This SEEDS the interprocedural fixpoint: the source
+ * taints the callee's parameter, which the callee's summary then carries to a
+ * sink (one or more hops away). The cross-function analogue of an intra-
+ * procedural `source → sink` partial flow whose sink lives in the callee.
+ */
+export interface SourceToCallArg {
+    readonly sourceKind: SourceKind;
+    /** Carried for hop display + same-name tie-break; NOT the join key (see
+     *  {@link ParamToCallArg} — the solver joins by `calleeName`). */
+    readonly callLine: number;
+    readonly argIndex: number;
+    readonly calleeName?: string;
+    /** Sink kinds neutralised on EVERY path from the generated source to this
+     *  call argument (intersection; #2084 review P1-2 — see {@link ParamToCallArg}). */
+    readonly neutralized?: readonly SinkKind[];
+}
+/**
+ * The compact taint abstraction of one function. All arrays are deterministically
+ * sorted by the harvester and deduped, so two structurally-equal summaries
+ * serialise identically (the {@link summaryVersion} contract).
+ */
+export interface FunctionSummary {
+    /** The resolved `Function`/`Method` graph node id this summary describes. */
+    readonly fnId: string;
+    /** Repo-relative source path (carried for diagnostics + the join debug). */
+    readonly filePath: string;
+    /** 1-based function start line (mirrors `FunctionCfg.functionStartLine`). */
+    readonly startLine: number;
+    /** Number of declared formal parameters (port arity). */
+    readonly paramCount: number;
+    /** param→return TITO edges. */
+    readonly paramToReturn: readonly ParamToReturn[];
+    /** param→callee-arg TITO edges (composed across `CALLS` in the fixpoint). */
+    readonly paramToCallArg: readonly ParamToCallArg[];
+    /** param→sink partial flows (a source reaching this param triggers a finding). */
+    readonly paramToSink: readonly ParamToSink[];
+    /** Generative source→return models. */
+    readonly sourceToReturn: readonly SourceToReturn[];
+    /** Generative source→callee-arg seeds (fixpoint entry points). */
+    readonly sourceToCallArg: readonly SourceToCallArg[];
+    /** Caller-side call-result flows — compose with callee `sourceToReturn`. */
+    readonly callResults: readonly CallResult[];
+    /**
+     * Content version stamp — `hash(own-facts ∪ sorted callee versions)`. The
+     * incremental cache key (Infer's content-keyed summary): equal across two
+     * runs iff the function's own taint facts AND every callee summary it depends
+     * on are unchanged. NOTE (#2084 review P1-1): callee-version composition is
+     * RESERVED — the harvester stamps the own-facts portion only
+     * ({@link ownFactsDigest}); the fixpoint does not yet recompose it.
+     */
+    readonly version: string;
+}
+/**
+ * Deterministic digest of a summary's OWN taint facts (everything except
+ * `version`, which is derived). Order-independent within each edge category —
+ * the harvester already sorts, but the digest re-canonicalises so a reordering
+ * never changes the stamp. Used as the leaf of {@link summaryVersion}.
+ */
+export declare function ownFactsDigest(s: Pick<FunctionSummary, 'paramCount' | 'paramToReturn' | 'paramToCallArg' | 'paramToSink' | 'sourceToReturn' | 'sourceToCallArg' | 'callResults'>): string;
+/**
+ * Content version stamp for a summary: `hash(ownFactsDigest ∪ sorted callee
+ * versions)`. Order-independent over callee versions (sorted). Equal iff the
+ * function's own facts AND every callee dependency are unchanged — this is the
+ * incremental invalidation primitive (a changed callee changes its version,
+ * which changes every transitive caller's version).
+ */
+export declare function summaryVersion(ownDigest: string, calleeVersions: readonly string[]): string;

package/dist/core/ingestion/taint/summary-model.js

@@ -0,0 +1,86 @@
+/**
+ * Per-function taint SUMMARY model (#2084 M4 U2).
+ *
+ * A {@link FunctionSummary} is the compact, context-insensitive abstraction of
+ * one function's taint behaviour — the input to the interprocedural fixpoint
+ * (`interproc-solver.ts`). It is the GitNexus analogue of Pysa's `.pysa`
+ * models, Mariana Trench's "propagations", and CodeQL Models-as-Data summary
+ * rows: a function is reduced to how taint enters (params / generated sources),
+ * how it moves through (param→return, param→callee-arg), and where it lands
+ * (param→sink). The fixpoint composes these across resolved `CALLS` edges so a
+ * source in one function reaches a sink in another.
+ *
+ * ## Why summaries (not whole-program IFDS)
+ *
+ * The functional/summary method (Sharir-Pnueli 1981) analyses each function
+ * ONCE and propagates the result over the call graph — the same shape Pysa,
+ * Mariana Trench, and Infer use in production. GitNexus already resolves the
+ * call graph (`CALLS` edges carry final node ids), so the summary IS the only
+ * new artifact; propagation is graph reachability over a finite lattice.
+ *
+ * ## Granularity (first cut)
+ *
+ * WHOLE-PARAMETER. Ports are `param i`, `return`, and `receiver` — no field
+ * access paths (`arg0.field.sub`). Field sensitivity, callback-parameter ports
+ * (`Argument[0].Parameter[0]`), and context sensitivity are deferred (plan
+ * KTD; the largest JS/TS FN class — closures — stays a documented gap).
+ *
+ * ## Plain-data discipline
+ *
+ * A summary is a JSON-plain value type (no functions, class instances, Maps, or
+ * Symbols) so it survives `RunScopeResolutionStats` → `ScopeResolutionOutput`
+ * threading and any future worker/cache boundary unchanged — the same
+ * `Cloneable` constraint the CFG side channel obeys.
+ */
+/** Stable FNV-1a 32-bit hash → 8-char hex. Pure, deterministic, no deps. */
+function fnv1a(input) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        // 32-bit FNV prime multiply via shifts (avoids BigInt; stays in int32 land).
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * Deterministic digest of a summary's OWN taint facts (everything except
+ * `version`, which is derived). Order-independent within each edge category —
+ * the harvester already sorts, but the digest re-canonicalises so a reordering
+ * never changes the stamp. Used as the leaf of {@link summaryVersion}.
+ */
+export function ownFactsDigest(s) {
+    const parts = [`p${s.paramCount}`];
+    parts.push(...s.paramToReturn
+        .map((r) => `r:${r.param}:${[...(r.neutralized ?? [])].sort().join(',')}`)
+        .sort());
+    parts.push(...s.paramToCallArg
+        .map((c) => `c:${c.param}:${c.callLine}:${c.argIndex}:${c.calleeName ?? ''}:${[...(c.neutralized ?? [])].sort().join(',')}`)
+        .sort());
+    parts.push(...s.paramToSink.map((k) => `k:${k.param}:${k.sinkKind}`).sort());
+    parts.push(...s.sourceToReturn.map((g) => `g:${g.sourceKind}`).sort());
+    parts.push(...s.sourceToCallArg
+        .map((g) => `s:${g.sourceKind}:${g.callLine}:${g.argIndex}:${g.calleeName ?? ''}:${[...(g.neutralized ?? [])].sort().join(',')}`)
+        .sort());
+    parts.push(...s.callResults
+        .map((cr) => {
+        const d = cr.dest;
+        const dest = d.to === 'sink'
+            ? `sink:${d.sinkKind}`
+            : d.to === 'return'
+                ? 'return'
+                : `arg:${d.toCallee ?? ''}:${d.argIndex}`;
+        return `cr:${cr.calleeName}:${dest}`;
+    })
+        .sort());
+    return fnv1a(parts.join('|'));
+}
+/**
+ * Content version stamp for a summary: `hash(ownFactsDigest ∪ sorted callee
+ * versions)`. Order-independent over callee versions (sorted). Equal iff the
+ * function's own facts AND every callee dependency are unchanged — this is the
+ * incremental invalidation primitive (a changed callee changes its version,
+ * which changes every transitive caller's version).
+ */
+export function summaryVersion(ownDigest, calleeVersions) {
+    return fnv1a(`${ownDigest}#${[...calleeVersions].sort().join(',')}`);
+}

package/dist/core/lbug/lbug-adapter.d.ts

@@ -206,6 +206,24 @@ export declare const queryImporters: (targetFilePath: string) => Promise<string[
 export declare const deleteAllCommunitiesAndProcesses: () => Promise<{
     nodesDeleted: number;
 }>;
+/**
+ * Drop every interprocedural `TAINT_PATH` relationship (#2084 M4 U6). Used at
+ * the start of an incremental `--pdg` writeback so the `taintSummaries` phase
+ * re-materialises them from scratch on the FULL recomputed graph.
+ *
+ * TAINT_PATH validity is a WHOLE-PROGRAM property (a flow A→C can be
+ * invalidated by a change to an INTERMEDIATE function whose file is neither A
+ * nor C). The endpoint-writability extract rule (`extractChangedSubgraph`)
+ * cannot see that — an A→C edge between two unchanged files would be skipped
+ * and a stale finding would survive. So, exactly like Community/Process, the
+ * sound move is delete-all-then-rebuild: cheap because TAINT_PATH is sparse
+ * (per-run capped), and the compute side already rebuilds every summary each
+ * run. Relationship-level (TAINT_PATH is an edge type, not a node label), so a
+ * plain DELETE on the typed CodeRelation rows — endpoints are untouched.
+ */
+export declare const deleteAllInterprocTaintPaths: () => Promise<{
+    edgesDeleted: number;
+}>;
 /**
  * Load the FTS extension on the supplied connection (or the singleton
  * writable connection when none is given).

package/dist/core/lbug/lbug-adapter.js

@@ -1629,6 +1629,61 @@ export const deleteAllCommunitiesAndProcesses = async () => {
     }
     return { nodesDeleted };
 };
+/**
+ * Drop every interprocedural `TAINT_PATH` relationship (#2084 M4 U6). Used at
+ * the start of an incremental `--pdg` writeback so the `taintSummaries` phase
+ * re-materialises them from scratch on the FULL recomputed graph.
+ *
+ * TAINT_PATH validity is a WHOLE-PROGRAM property (a flow A→C can be
+ * invalidated by a change to an INTERMEDIATE function whose file is neither A
+ * nor C). The endpoint-writability extract rule (`extractChangedSubgraph`)
+ * cannot see that — an A→C edge between two unchanged files would be skipped
+ * and a stale finding would survive. So, exactly like Community/Process, the
+ * sound move is delete-all-then-rebuild: cheap because TAINT_PATH is sparse
+ * (per-run capped), and the compute side already rebuilds every summary each
+ * run. Relationship-level (TAINT_PATH is an edge type, not a node label), so a
+ * plain DELETE on the typed CodeRelation rows — endpoints are untouched.
+ */
+export const deleteAllInterprocTaintPaths = async () => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initLbug first.');
+    }
+    let edgesDeleted = 0;
+    let countResult;
+    try {
+        countResult = await conn.query(`MATCH ()-[r:CodeRelation]->() WHERE r.type = 'TAINT_PATH' RETURN count(r) AS cnt`);
+        const result = Array.isArray(countResult) ? countResult[0] : countResult;
+        const rows = await result.getAll();
+        const count = Number(rows[0]?.cnt ?? rows[0]?.[0] ?? 0);
+        if (count > 0) {
+            await conn.query(`MATCH ()-[r:CodeRelation]->() WHERE r.type = 'TAINT_PATH' DELETE r`);
+            edgesDeleted = count;
+        }
+    }
+    catch (err) {
+        // A missing table on a freshly-initialized DB is the benign, expected case
+        // (the count query above is what throws) — stay silent. Any OTHER failure
+        // (lock, disk, native error) would leave stale TAINT_PATH rows that the
+        // subsequent re-extract then DUPLICATES (CodeRelation has no PK), so it
+        // must ABORT the writeback (#2084 review P2-5): re-throw so the caller's
+        // crash-recovery dirty flag forces a clean full rebuild on the next run,
+        // rather than silently writing duplicate cross-function findings.
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/no table|not exist|not found|does not exist|Table .* does not exist/i.test(msg)) {
+            if (countResult)
+                await closeQueryResults(countResult);
+            return { edgesDeleted };
+        }
+        if (countResult)
+            await closeQueryResults(countResult);
+        throw new Error(`[taint-interproc] failed to clear existing TAINT_PATH edges before incremental ` +
+            `re-write (${msg}) — aborting to avoid duplicate cross-function findings; ` +
+            `the next run will full-rebuild`);
+    }
+    if (countResult)
+        await closeQueryResults(countResult);
+    return { edgesDeleted };
+};
 // ============================================================================
 // Full-Text Search (FTS) Functions
 // ============================================================================

package/dist/core/run-analyze.d.ts

@@ -72,6 +72,12 @@ export interface AnalyzeOptions {
     /** Per-finding taint hop cap (#2083 M3, KTD6). Forwarded to
      *  `PipelineOptions.pdgMaxTaintHops`. No CLI flag or rc key (KTD8). */
     pdgMaxTaintHops?: number;
+    /** Per-run cross-function findings/hops/edges caps (#2084 review P1-3).
+     *  Forwarded to the matching `PipelineOptions.pdgMaxInterproc*`; resolved
+     *  into `RepoMeta.pdg`. No CLI flag or rc key (KTD8). */
+    pdgMaxInterprocFindings?: number;
+    pdgMaxInterprocHops?: number;
+    pdgMaxInterprocEdges?: number;
     /**
      * Default branch threaded into generated AGENTS.md / CLAUDE.md so the
      * regression-compare example uses the configured branch instead of a
@@ -192,7 +198,7 @@ export declare const collectBranchCacheKeys: (storagePath: string, excludeDir?:
  * defaults so an explicit-default run compares equal to a default run
  * (`0` = unlimited is preserved as `0`). Pure + exported for testing.
  */
-type PdgOptions = Pick<AnalyzeOptions, 'pdg' | 'pdgMaxFunctionLines' | 'pdgMaxEdgesPerFunction' | 'pdgMaxReachingDefEdgesPerFunction' | 'pdgMaxTaintFindingsPerFunction' | 'pdgMaxTaintHops'>;
+type PdgOptions = Pick<AnalyzeOptions, 'pdg' | 'pdgMaxFunctionLines' | 'pdgMaxEdgesPerFunction' | 'pdgMaxReachingDefEdgesPerFunction' | 'pdgMaxTaintFindingsPerFunction' | 'pdgMaxTaintHops' | 'pdgMaxInterprocFindings' | 'pdgMaxInterprocHops' | 'pdgMaxInterprocEdges'>;
 export declare const resolvePdgConfig: (options: PdgOptions) => RepoMeta["pdg"];
 /**
  * Whether the requested `--pdg` configuration differs from the one the

package/dist/core/run-analyze.js

@@ -13,7 +13,7 @@ import fs from 'fs/promises';
 import { execFileSync } from 'child_process';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
-import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
+import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
 import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.js';
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
@@ -21,6 +21,8 @@ import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitN
 import { DEFAULT_PDG_MAX_FUNCTION_LINES } from './ingestion/cfg/collect.js';
 import { DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, } from './ingestion/cfg/emit.js';
 import { DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './ingestion/taint/propagate.js';
+import { DEFAULT_MAX_INTERPROC_HOPS, DEFAULT_PDG_MAX_INTERPROC_FINDINGS, } from './ingestion/taint/interproc-solver.js';
+import { DEFAULT_PDG_MAX_INTERPROC_EDGES } from './ingestion/taint/interproc-emit.js';
 import { taintModelVersion } from './ingestion/taint/typescript-model.js';
 import { computeFileHashes, diffFileHashes } from '../storage/file-hash.js';
 import { extractChangedSubgraph, computeEffectiveWriteSet, } from './incremental/subgraph-extract.js';
@@ -144,6 +146,12 @@ export const resolvePdgConfig = (options) => options.pdg === true
         // writeback that populates TAINTED/SANITIZES rows without `--force`.
         maxTaintFindingsPerFunction: options.pdgMaxTaintFindingsPerFunction ?? DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION,
         maxTaintHops: options.pdgMaxTaintHops ?? DEFAULT_PDG_MAX_TAINT_HOPS,
+        // #2084 review P1-3: cross-function caps. Absent on an M3-era stamp →
+        // pdgModeMismatch trips the first run that adds them (key-union),
+        // forcing the full writeback that re-materialises TAINT_PATH bounded.
+        maxInterprocFindings: options.pdgMaxInterprocFindings ?? DEFAULT_PDG_MAX_INTERPROC_FINDINGS,
+        maxInterprocHops: options.pdgMaxInterprocHops ?? DEFAULT_MAX_INTERPROC_HOPS,
+        maxInterprocEdges: options.pdgMaxInterprocEdges ?? DEFAULT_PDG_MAX_INTERPROC_EDGES,
         // Built-in model digest (KTD7/R7): persisted findings must never
         // outlive the model that produced them — ANY model-content change
         // ships as a new digest and repopulates the taint edges.
@@ -501,6 +509,9 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         pdgMaxReachingDefEdgesPerFunction: options.pdgMaxReachingDefEdgesPerFunction,
         pdgMaxTaintFindingsPerFunction: options.pdgMaxTaintFindingsPerFunction,
         pdgMaxTaintHops: options.pdgMaxTaintHops,
+        pdgMaxInterprocFindings: options.pdgMaxInterprocFindings,
+        pdgMaxInterprocHops: options.pdgMaxInterprocHops,
+        pdgMaxInterprocEdges: options.pdgMaxInterprocEdges,
         fetchWrappers: options.fetchWrappers,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
@@ -704,6 +715,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             //    from the fresh pipeline output below. Required for the
             //    "Leiden runs on the FULL graph" correctness invariant.
             await deleteAllCommunitiesAndProcesses();
+            // 2b. Drop interprocedural TAINT_PATH edges (#2084 M4 U6) when pdg is on
+            //     — their validity is a whole-program property (an A→C flow can be
+            //     invalidated by a change to an intermediate function on a third
+            //     file), so endpoint-writability extraction can't refresh them.
+            //     extractChangedSubgraph re-includes all of them from the fresh
+            //     graph (isGraphWideRelType), mirroring Community/Process.
+            if (options.pdg === true) {
+                await deleteAllInterprocTaintPaths();
+            }
             // 3. Extract the changed subgraph from the FULL ctx.graph and write
             //    only that. Unchanged-file rows in the DB stay untouched. Pass
             //    the SAME effectiveWriteSet so the subgraph and the deletes

package/dist/mcp/local/local-backend.js

@@ -2425,16 +2425,81 @@ export class LocalBackend {
             }
         }
         const { rows, totalFindings } = await runAnchoredQuery();
-        if (totalFindings === 0 && pdgStamped === undefined && !target) {
-            // Meta was unreadable and the repo-wide enumerate found nothing — the
-            // count above WAS the existence probe; surface the layer hint.
+        // M4 (#2084 U7): cross-function findings ride TAINT_PATH edges (Function/
+        // Method → Function/Method), separate from the intra-procedural TAINTED
+        // BasicBlock rows above. Enumerate them too so `explain` is the discovery
+        // surface for interprocedural flows (TAINT_PATH stays out of
+        // VALID_RELATION_TYPES + the web schema, like TAINTED). File-anchored:
+        // filter on the source function's file; symbol-anchored: either endpoint
+        // matches the symbol name; anchorless: all (bounded by LIMIT). Computed
+        // BEFORE the no-taint early returns — a repo with ONLY cross-function
+        // findings (no intra-procedural TAINTED rows) must not look empty.
+        const runInterprocQuery = async () => {
+            const where = [`r.type = 'TAINT_PATH'`];
+            const p = {};
+            if (anchor?.symbol) {
+                where.push('(a.name = $ipSym OR b.name = $ipSym)');
+                p.ipSym = anchor.symbol;
+            }
+            else if (anchor?.file) {
+                // Match EITHER endpoint's file — a cross-function flow anchored on the
+                // SINK's file (b) is as relevant as one anchored on the source's (a).
+                where.push('(a.filePath = $ipFile OR a.filePath ENDS WITH $ipSuffix OR ' +
+                    'b.filePath = $ipFile OR b.filePath ENDS WITH $ipSuffix)');
+                p.ipFile = anchor.file;
+                p.ipSuffix = `/${anchor.file}`;
+            }
+            const matchClause = `MATCH (a)-[r:CodeRelation]->(b)\n      WHERE ${where.join(' AND ')}`;
+            // Page query + a separate COUNT (#2084 review P2-4): the page is
+            // LIMIT-capped, so its row count cannot stand in for the true total —
+            // run a COUNT with the same WHERE (no LIMIT) like the intra layer does.
+            const [ipRows, ipCountRows] = await Promise.all([
+                executeParameterized(repo.lbugPath, `${matchClause}
+      RETURN a.filePath AS file, a.name AS sourceFn, a.startLine AS sourceLine,
+             b.name AS sinkFn, b.startLine AS sinkLine, r.reason AS reason
+      ORDER BY sourceFn, sinkFn, reason
+      LIMIT ${limit}`, p),
+                executeParameterized(repo.lbugPath, `${matchClause}\n      RETURN COUNT(*) AS total`, p),
+            ]);
+            const total = Number(ipCountRows[0]?.total ?? ipCountRows[0]?.[0] ?? 0);
+            const findings = ipRows.map((r) => {
+                const decoded = decodeTaintPath(r.reason ?? r[5]);
+                const hops = decoded.ok
+                    ? decoded.hops.map((h) => ({ function: h.variable, line: h.line }))
+                    : [];
+                return {
+                    interprocedural: true,
+                    file: String(r.file ?? r[0] ?? ''),
+                    sinkKind: decoded.ok ? (decoded.kind ?? 'unknown') : 'unknown',
+                    source: { function: String(r.sourceFn ?? r[1] ?? ''), line: r.sourceLine ?? r[2] },
+                    sink: { function: String(r.sinkFn ?? r[3] ?? ''), line: r.sinkLine ?? r[4] },
+                    hops,
+                    ...(decoded.ok && decoded.truncated ? { pathIncomplete: true } : {}),
+                };
+            });
+            return { findings, total };
+        };
+        const { findings: interprocFindings, total: interprocTotal } = await runInterprocQuery();
+        if (totalFindings === 0 &&
+            interprocFindings.length === 0 &&
+            pdgStamped === undefined &&
+            !target) {
+            // Meta was unreadable and the repo-wide enumerate (both layers) found
+            // nothing — the counts above WERE the existence probe; surface the hint.
             return { findings: [], totalFindings: 0, note: NO_TAINT_NOTE };
         }
-        if (totalFindings === 0 && pdgStamped === undefined && target) {
+        if (totalFindings === 0 &&
+            interprocFindings.length === 0 &&
+            pdgStamped === undefined &&
+            target) {
             // Anchored miss with unreadable meta: one extra bounded probe decides
-            // "no findings for this anchor" vs "no taint layer at all".
+            // "no findings for this anchor" vs "no taint layer at all". Probe BOTH
+            // intra (TAINTED) and inter (TAINT_PATH) existence.
             const probe = await executeParameterized(repo.lbugPath, `MATCH (a:BasicBlock)-[r:CodeRelation]->(b:BasicBlock) WHERE r.type = 'TAINTED' RETURN r.reason AS reason LIMIT 1`, {});
-            if (probe.length === 0) {
+            const ipProbe = probe.length === 0
+                ? await executeParameterized(repo.lbugPath, `MATCH (a)-[r:CodeRelation]->(b) WHERE r.type = 'TAINT_PATH' RETURN r.reason AS reason LIMIT 1`, {})
+                : [];
+            if (probe.length === 0 && ipProbe.length === 0) {
                 return { findings: [], totalFindings: 0, note: NO_TAINT_NOTE };
             }
         }
@@ -2479,12 +2544,30 @@ export class LocalBackend {
                 ...(decoded.truncated ? { pathIncomplete: true } : {}),
             };
         });
+        // Combine both layers and re-apply the page LIMIT to the union — each
+        // layer was queried with its own LIMIT, so the union can hold up to 2×;
+        // cap it so `findings.length` honours the caller's `limit`. `truncated`
+        // reflects EITHER layer overflowing OR the union being trimmed here, and
+        // `totalFindings` counts both layers' matched rows (the intra COUNT plus
+        // the interproc rows returned — interproc has no separate COUNT, so a
+        // capped interproc layer is reflected via `truncated`, never undercounted
+        // into a false "complete" signal). Review: code-review #2/#4 (explain
+        // accounting + sink-file anchoring) — both layers now accounted.
+        const combined = [...findings, ...interprocFindings];
+        const pageFindings = combined.length > limit ? combined.slice(0, limit) : combined;
+        // Truncated iff EITHER layer overflowed its own LIMIT (strict `>` — exactly
+        // `limit` rows is not truncated), OR the combined union was trimmed to the
+        // page (#2084 review P2-4). `totalFindings` uses the interproc COUNT, not
+        // the capped slice length, so it never undercounts.
+        const truncated = totalFindings > findings.length ||
+            interprocTotal > interprocFindings.length ||
+            combined.length > pageFindings.length;
         return {
             ...(anchor ? { anchor } : {}),
-            findings,
-            totalFindings,
-            ...(totalFindings > findings.length ? { truncated: true } : {}),
-            note: 'Intra-procedural findings only — cross-function, closure/callback, property/field, and implicit flows are not modeled; absence of a finding is not proof of safety. SANITIZES (kill) edges are queryable via cypher.',
+            findings: pageFindings,
+            totalFindings: totalFindings + interprocTotal,
+            ...(truncated ? { truncated: true } : {}),
+            note: 'Intra-procedural (TAINTED, statement hops) AND cross-function (TAINT_PATH, function hops, `interprocedural: true`) flows are modeled. Closure/callback, property/field, and implicit flows are NOT modeled; absence of a finding is not proof of safety. Cross-function findings are context-insensitive and may over-attribute among same-named callees. SANITIZES (kill) edges are queryable via cypher.',
         };
     }
     /**

package/dist/mcp/tools.js

@@ -473,18 +473,19 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
     },
     {
         name: 'explain',
-        description: `Explain persisted taint findings: intra-procedural source→sink data flows (TAINTED edges) recorded by \`gitnexus analyze --pdg\`.
+        description: `Explain persisted taint findings recorded by \`gitnexus analyze --pdg\`: intra-procedural source→sink data flows (TAINTED edges, statement-level hops) AND cross-function flows (TAINT_PATH edges, function-level hops, marked \`interprocedural: true\`).
 
-Each finding carries the sink category (command-injection, code-injection, path-traversal, sql-injection, xss), the source/sink lines, and the ordered hop path with the variable carried on each hop (decoded from the persisted path encoding).
+Each finding carries the sink category (command-injection, code-injection, path-traversal, sql-injection, xss) and the ordered hop path. Intra-procedural findings carry source/sink lines and the variable on each hop; interprocedural findings carry the source and sink FUNCTION names and the chain of functions the taint crossed (decoded from the persisted path encoding).
 
 WHEN TO USE: Security review — "what taint findings exist in this repo / file / function?". Requires the repo to be indexed with \`gitnexus analyze --pdg\`; without that layer the tool returns a clear "no taint layer" note, not an error.
 
 ANCHORLESS (no "target"): enumerates all persisted findings for the repo — bounded ("limit", deterministic order), with "totalFindings" and a "truncated" flag.
-ANCHORED ("target" = file path or symbol/function name): full hop detail for that anchor. A file-ish target (contains "/" or an extension) filters by file; a symbol name resolves like context() — ambiguous names return ranked candidates, unknown names return not-found. Symbol anchoring is line-range granular (findings whose source block starts inside the symbol's span).
+ANCHORED ("target" = file path or symbol/function name): full hop detail for that anchor. A file-ish target (contains "/" or an extension) filters by file; a symbol name resolves like context() — ambiguous names return ranked candidates, unknown names return not-found. Symbol anchoring is line-range granular for intra-procedural findings; cross-function findings match when the symbol is the source OR sink function.
 
-CONTRACT CAVEATS (intra-procedural M3 scope — absent flows are NOT proof of safety):
-- Cross-function flows are not modeled (a flow through a helper function is invisible).
-- Closure/callback flows are invisible in both directions (e.g. arr.forEach(() => sink(y))).
+CONTRACT CAVEATS (absent flows are NOT proof of safety):
+- Cross-function flows ARE modeled (#2084 M4): a source flowing through helper functions into a sink is found, via summary composition over the call graph (context-insensitive — return/call-site merging is accepted).
+- Cross-function matching is by callee NAME (context-insensitive): when one caller invokes two distinct same-named callees, a flow into one over-attributes to both — a cross-function finding does not prove the taint reached every same-named function (sound over-report, never a missed flow).
+- Closure/callback flows are invisible in both directions (e.g. arr.forEach(() => sink(y))) — the largest false-negative class.
 - Property/field flows are not tracked (obj.x = taint; sink(obj.y) has no chain).
 - Guard-style sanitizers (if (isValid(x))) and implicit/control-dependence flows are not modeled.
 - CommonJS aliasing is partially modeled (require('<literal>') joins resolve; dynamic requires do not).

package/dist/storage/repo-manager.d.ts

@@ -145,6 +145,16 @@ export interface RepoMeta {
          *  bounds the persisted hop-encoded `reason`). Optional for the same
          *  M2-era-stamp upgrade reason as the findings cap. */
         maxTaintHops?: number;
+        /**
+         * Per-run cross-function caps, resolved (0 = unlimited; #2084 M4 review
+         * P1-3). ABSENT on an M3-era stamp — that absence trips `pdgModeMismatch`
+         * on the first run that adds them and forces the full writeback that
+         * re-materialises TAINT_PATH within bounds. Optional for that upgrade
+         * reason; resolved (always present) on every post-fix write.
+         */
+        maxInterprocFindings?: number;
+        maxInterprocHops?: number;
+        maxInterprocEdges?: number;
         /**
          * Digest of the built-in taint model the persisted findings were
          * produced under (#2083 M3 KTD7/R7). Any model-content change ships a