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

package/hooks/antigravity/gitnexus-antigravity-hook.cjs

@@ -24,7 +24,10 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.cjs');
-const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
+const {
+  hasGitNexusDbLockedByGitNexusServer,
+  resolveUnixGuardTimeout,
+} = require('./hook-db-lock-probe.cjs');
 const { formatAnalyzeCommand } = require('./resolve-analyze-cmd.cjs');
 
 function readInput() {
@@ -198,10 +201,73 @@ function resolveCliPath() {
   return cliPath;
 }
 
+// Debounce for the unguarded-CLI diagnostic below (#2163 follow-up review):
+// at most one line per (short-lived) hook process, even if a future change
+// runs the CLI more than once.
+let unguardedCliWarned = false;
+
+/**
+ * Unix orphan containment (#2163 follow-up): the augment CLI is the
+ * longest-lived hook child (inner spawnSync timeout 7s locally, 12s via
+ * npx), so on Unix it gets the same SIGKILL-surviving coreutils `timeout`
+ * wrapper as the probe's lsof/ps. The wrapper budget is ceil(inner/1000)+1
+ * seconds — STRICTLY greater than the inner spawnSync timeout, so on the
+ * supervised path Node's SIGTERM always fires first and the existing
+ * error/status contract is untouched. Once the hook itself has been
+ * SIGKILLed (exactly the orphan case the wrapper exists for), the guard
+ * semantics differ per branch:
+ *   - direct exec (the CLI is the guard's CHILD): `-k 1` TERM-first — a
+ *     SIGTERM-immune CLI can hold the guard ~1s past the inner timeout
+ *     before the `-k` SIGKILL escalation reaps it.
+ *   - npx (the CLI is a GRANDCHILD: guard → npx → CLI): `-s KILL` — the
+ *     budget expiry SIGKILLs the whole process group outright. TERM-first
+ *     would kill only the obedient npx parent, making `timeout` reap it and
+ *     return before the `-k` escalation ever fires, stranding a
+ *     SIGTERM-immune CLI grandchild unbounded (reproduced on coreutils
+ *     9.x). `-k 1` is retained alongside `-s KILL` as a harmless belt: with
+ *     `-s KILL` the `-k` escalation signal is also KILL. Two residual gaps
+ *     on this branch, both bounded by "no worse than pre-fix" (where the
+ *     grandchild received no signal at all): the group-wide SIGKILL is
+ *     coreutils semantics — a busybox `timeout` passes the self-test (it
+ *     has `-k` and propagates exit status) but signals only its direct
+ *     child, so a busybox guard cannot reach the grandchild; and on the
+ *     SUPERVISED path (hook alive, inner spawnSync timeout SIGTERMs the
+ *     guard) coreutils forwards TERM rather than the `-s` signal, npx dies,
+ *     and the guard exits before any KILL fires — so a SIGTERM-immune CLI
+ *     grandchild still escapes in those two cases.
+ * If the sibling probe predates the resolveUnixGuardTimeout export (version
+ * skew), the adapter degrades to the unwrapped invocation instead of
+ * throwing. Windows is deliberately NOT wrapped — there is no coreutils
+ * timeout to resolve there and the resolver's self-test spawns /bin/sh — so
+ * on win32 (the npx.cmd path) and whenever the guard resolves to null (e.g.
+ * macOS without Homebrew coreutils — reported once under GITNEXUS_DEBUG)
+ * the argv stays byte-identical to the pre-wrap invocation.
+ */
 function runGitNexusCli(cliPath, args, cwd, timeout) {
   const isWin = process.platform === 'win32';
+  // Version-skew guard (#2163 follow-up review): an older sibling probe
+  // without the resolveUnixGuardTimeout export must degrade to the unwrapped
+  // invocation — a TypeError here would be swallowed by the caller's catch
+  // and silently kill the augment.
+  const guard =
+    isWin || typeof resolveUnixGuardTimeout !== 'function' ? null : resolveUnixGuardTimeout();
+  if (!isWin && !guard && !unguardedCliWarned && isDebugEnabled()) {
+    // Diagnose the "stays unwrapped" Unix paths once per hook process: no
+    // usable coreutils timeout/gtimeout (e.g. macOS without Homebrew
+    // coreutils), GITNEXUS_HOOK_TIMEOUT_PATH=disabled, or probe skew above.
+    unguardedCliWarned = true;
+    process.stderr.write(
+      '[GitNexus hook] no usable timeout/gtimeout guard; augment CLI child runs unguarded\n',
+    );
+  }
   if (cliPath) {
-    return spawnSync(process.execPath, [cliPath, ...args], {
+    const [cmd, cmdArgs] = guard
+      ? [
+          guard,
+          ['-k', '1', String(Math.ceil(timeout / 1000) + 1), process.execPath, cliPath, ...args],
+        ]
+      : [process.execPath, [cliPath, ...args]];
+    return spawnSync(cmd, cmdArgs, {
       encoding: 'utf-8',
       timeout,
       cwd,
@@ -209,7 +275,27 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
       windowsHide: true,
     });
   }
-  return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], {
+  // A non-null guard implies non-Windows, so the wrapped arm can hardcode
+  // plain `npx`. The wrapped arm leads with `-s KILL` (NOT TERM-first like
+  // the direct branch above): the CLI here is a grandchild behind npx — see
+  // the docblock.
+  const [cmd, cmdArgs] = guard
+    ? [
+        guard,
+        [
+          '-s',
+          'KILL',
+          '-k',
+          '1',
+          String(Math.ceil((timeout + 5000) / 1000) + 1),
+          'npx',
+          '-y',
+          'gitnexus',
+          ...args,
+        ],
+      ]
+    : [isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args]];
+  return spawnSync(cmd, cmdArgs, {
     encoding: 'utf-8',
     timeout: timeout + 5000,
     cwd,

package/hooks/claude/gitnexus-hook.cjs

@@ -15,7 +15,10 @@ const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { acquireHookSlot } = require('./hook-lock.cjs');
-const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs');
+const {
+  hasGitNexusDbLockedByGitNexusServer,
+  resolveUnixGuardTimeout,
+} = require('./hook-db-lock-probe.cjs');
 const { formatAnalyzeCommand } = require('./resolve-analyze-cmd.cjs');
 
 /**
@@ -218,14 +221,76 @@ function resolveCliPath() {
   return cliPath;
 }
 
+// Debounce for the unguarded-CLI diagnostic below (#2163 follow-up review):
+// at most one line per (short-lived) hook process, even if a future change
+// runs the CLI more than once.
+let unguardedCliWarned = false;
+
 /**
  * Spawn a gitnexus CLI command synchronously.
  * Returns the stderr output (KuzuDB captures stdout at OS level).
+ *
+ * Unix orphan containment (#2163 follow-up): the augment CLI is the
+ * longest-lived hook child (inner spawnSync timeout 7s locally, 12s via
+ * npx), so on Unix it gets the same SIGKILL-surviving coreutils `timeout`
+ * wrapper as the probe's lsof/ps. The wrapper budget is ceil(inner/1000)+1
+ * seconds — STRICTLY greater than the inner spawnSync timeout, so on the
+ * supervised path Node's SIGTERM always fires first and the existing
+ * error/status contract is untouched. Once the hook itself has been
+ * SIGKILLed (exactly the orphan case the wrapper exists for), the guard
+ * semantics differ per branch:
+ *   - direct exec (the CLI is the guard's CHILD): `-k 1` TERM-first — a
+ *     SIGTERM-immune CLI can hold the guard ~1s past the inner timeout
+ *     before the `-k` SIGKILL escalation reaps it.
+ *   - npx (the CLI is a GRANDCHILD: guard → npx → CLI): `-s KILL` — the
+ *     budget expiry SIGKILLs the whole process group outright. TERM-first
+ *     would kill only the obedient npx parent, making `timeout` reap it and
+ *     return before the `-k` escalation ever fires, stranding a
+ *     SIGTERM-immune CLI grandchild unbounded (reproduced on coreutils
+ *     9.x). `-k 1` is retained alongside `-s KILL` as a harmless belt: with
+ *     `-s KILL` the `-k` escalation signal is also KILL. Two residual gaps
+ *     on this branch, both bounded by "no worse than pre-fix" (where the
+ *     grandchild received no signal at all): the group-wide SIGKILL is
+ *     coreutils semantics — a busybox `timeout` passes the self-test (it
+ *     has `-k` and propagates exit status) but signals only its direct
+ *     child, so a busybox guard cannot reach the grandchild; and on the
+ *     SUPERVISED path (hook alive, inner spawnSync timeout SIGTERMs the
+ *     guard) coreutils forwards TERM rather than the `-s` signal, npx dies,
+ *     and the guard exits before any KILL fires — so a SIGTERM-immune CLI
+ *     grandchild still escapes in those two cases.
+ * If the sibling probe predates the resolveUnixGuardTimeout export (version
+ * skew), the adapter degrades to the unwrapped invocation instead of
+ * throwing. Windows is deliberately NOT wrapped — there is no coreutils
+ * timeout to resolve there and the resolver's self-test spawns /bin/sh — so
+ * on win32 (the npx.cmd path) and whenever the guard resolves to null (e.g.
+ * macOS without Homebrew coreutils — reported once under GITNEXUS_DEBUG)
+ * the argv stays byte-identical to the pre-wrap invocation.
  */
 function runGitNexusCli(cliPath, args, cwd, timeout) {
   const isWin = process.platform === 'win32';
+  // Version-skew guard (#2163 follow-up review): an older sibling probe
+  // without the resolveUnixGuardTimeout export must degrade to the unwrapped
+  // invocation — a TypeError here would be swallowed by the caller's catch
+  // and silently kill the augment.
+  const guard =
+    isWin || typeof resolveUnixGuardTimeout !== 'function' ? null : resolveUnixGuardTimeout();
+  if (!isWin && !guard && !unguardedCliWarned && isDebugEnabled()) {
+    // Diagnose the "stays unwrapped" Unix paths once per hook process: no
+    // usable coreutils timeout/gtimeout (e.g. macOS without Homebrew
+    // coreutils), GITNEXUS_HOOK_TIMEOUT_PATH=disabled, or probe skew above.
+    unguardedCliWarned = true;
+    process.stderr.write(
+      '[GitNexus hook] no usable timeout/gtimeout guard; augment CLI child runs unguarded\n',
+    );
+  }
   if (cliPath) {
-    return spawnSync(process.execPath, [cliPath, ...args], {
+    const [cmd, cmdArgs] = guard
+      ? [
+          guard,
+          ['-k', '1', String(Math.ceil(timeout / 1000) + 1), process.execPath, cliPath, ...args],
+        ]
+      : [process.execPath, [cliPath, ...args]];
+    return spawnSync(cmd, cmdArgs, {
       encoding: 'utf-8',
       timeout,
       cwd,
@@ -233,8 +298,27 @@ function runGitNexusCli(cliPath, args, cwd, timeout) {
       windowsHide: true,
     });
   }
-  // On Windows, invoke npx.cmd directly (no shell needed)
-  return spawnSync(isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args], {
+  // On Windows, invoke npx.cmd directly (no shell needed). A non-null guard
+  // implies non-Windows, so the wrapped arm can hardcode plain `npx`. The
+  // wrapped arm leads with `-s KILL` (NOT TERM-first like the direct branch
+  // above): the CLI here is a grandchild behind npx — see the docblock.
+  const [cmd, cmdArgs] = guard
+    ? [
+        guard,
+        [
+          '-s',
+          'KILL',
+          '-k',
+          '1',
+          String(Math.ceil((timeout + 5000) / 1000) + 1),
+          'npx',
+          '-y',
+          'gitnexus',
+          ...args,
+        ],
+      ]
+    : [isWin ? 'npx.cmd' : 'npx', ['-y', 'gitnexus', ...args]];
+  return spawnSync(cmd, cmdArgs, {
     encoding: 'utf-8',
     timeout: timeout + 5000,
     cwd,

package/hooks/claude/hook-db-lock-probe.cjs

@@ -20,13 +20,18 @@
  *   it 1s later — orphan lifetime is bounded at ~3s instead of unbounded.
  * - GITNEXUS_HOOK_TIMEOUT_PATH: the sentinel value `disabled` switches the
  *   wrapper off deterministically; any other value is adopted only when it
- *   exists AND passes a one-shot `-k` self-test — otherwise resolution FALLS
- *   THROUGH to the built-in candidate list (first self-test pass wins), so
- *   no malformed value of any shape can silently disable orphan containment.
+ *   exists AND passes a one-shot `-k` exit-propagation self-test — otherwise
+ *   resolution FALLS THROUGH to the built-in candidate list (first self-test
+ *   pass wins), so no malformed value of any shape can silently disable
+ *   orphan containment.
  * - The gitnexus server is lazy-open + sticky-hold: an idle MCP server holds
  *   ZERO lbug fds until the repo's first MCP query, then keeps the fd open.
  *   A probe before that first query is therefore always false — a known,
  *   pre-existing race, not a bug in this probe.
+ * - resolveUnixGuardTimeout is exported so the hook adapters can wrap the
+ *   `gitnexus augment` CLI child — the longest-lived hook subprocess (7s
+ *   local / 12s npx inner budgets) — in the same guard; see runGitNexusCli
+ *   in the adapters (#2163 follow-up).
  */
 
 const fs = require('fs');
@@ -70,38 +75,53 @@ let unixGuardTimeoutCache;
 
 /**
  * Resolve a coreutils `timeout`/`gtimeout` binary to wrap lsof/ps with
- * (#2163). Dead code on Windows (the win32 dispatch returns earlier).
+ * (#2163). Unix-only by contract: the probe's win32 dispatch returns before
+ * reaching it, and the exported callers (the adapters' runGitNexusCli,
+ * #2163 follow-up) must check the platform first — the self-test below
+ * spawns /bin/sh. The memoized result is module-wide, so probe and adapter
+ * share one lazy self-test per hook process.
  *
  * GITNEXUS_HOOK_TIMEOUT_PATH semantics: the sentinel `disabled` turns the
  * wrapper off; any other value is only a CANDIDATE — an existing file path
- * is tried first, but it must pass the `-k` self-test to be adopted. On any
- * failure (non-existent path, directory, non-executable file, wrapper
- * without `-k` support, …) resolution falls through to the built-in
- * candidates below, tried in order, first self-test pass wins. This is
- * strictly stronger than the sibling GITNEXUS_HOOK_LSOF_PATH /
- * GITNEXUS_HOOK_PS_PATH overrides (which only check existence): no bad env
- * value of ANY shape can silently disable orphan containment.
+ * is tried first, but it must pass the `-k` exit-propagation self-test to
+ * be adopted. On any failure (non-existent path, directory, non-executable
+ * file, wrapper without `-k` support, always-exit-0 stub, …) resolution
+ * falls through to the built-in candidates below, tried in order, first
+ * self-test pass wins. This is strictly stronger than the sibling
+ * GITNEXUS_HOOK_LSOF_PATH / GITNEXUS_HOOK_PS_PATH overrides (which only
+ * check existence): no bad env value of ANY shape can silently disable
+ * orphan containment.
  *
  * Lazy self-test: candidates are probed only when the lsof/ps fallback is
  * first reached, and the result is memoized. A candidate is adopted only
- * when `timeout -k 1 1 /bin/sh -c :` exits 0. This rejects wrappers that do
- * not support the coreutils `-k` flag — busybox <1.34, toybox, broken
- * symlinks — which would otherwise exit with a usage error without ever
- * running lsof, silently converting the lsof-ETIMEDOUT fail-closed contract
- * into fail-open (#1492 regression). Only when EVERY candidate fails does
- * the probe fall back to the unwrapped status quo (memoized null).
- * busybox ≥1.34 passes the test and is fully usable (capability, not
- * identity, decides).
+ * when `timeout -k 1 1 /bin/sh -c 'exit 42'` exits 42 — i.e. it must RUN
+ * the wrapped command AND PROPAGATE its exit status. This rejects two
+ * failure shapes: wrappers without the coreutils `-k` flag — busybox <1.34,
+ * toybox, broken symlinks — which would exit with a usage error without
+ * ever running lsof, silently converting the lsof-ETIMEDOUT fail-closed
+ * contract into fail-open (#1492 regression); and always-exit-0 stubs
+ * (/bin/true shapes), which would otherwise be adopted and "succeed" every
+ * wrapped spawn instantly without running it — a constant no-owner probe
+ * answer and, worse, a silently dead augment (status 0, empty stderr passes
+ * the adapters' success check with no context; #2163 follow-up review).
+ * Only when EVERY candidate fails does the probe fall back to the unwrapped
+ * status quo (memoized null). busybox ≥1.34 passes the test and is fully
+ * usable for everything THIS file spawns (lsof/ps are the guard's direct
+ * children) and for the adapters' direct-exec arm. The adapters' npx arm
+ * additionally relies on coreutils' process-GROUP signalling for its
+ * `-s KILL` grandchild reaping; busybox signals only its direct child, and
+ * this self-test deliberately does not probe that capability — see the
+ * adapter docblocks for the residual-gap statement.
  */
 function passesGuardSelfTest(guard) {
   try {
-    const selfTest = spawnSync(guard, ['-k', '1', '1', '/bin/sh', '-c', ':'], {
+    const selfTest = spawnSync(guard, ['-k', '1', '1', '/bin/sh', '-c', 'exit 42'], {
       encoding: 'utf-8',
       timeout: 3000,
       stdio: ['ignore', 'ignore', 'ignore'],
       windowsHide: true,
     });
-    return !selfTest.error && selfTest.status === 0;
+    return !selfTest.error && selfTest.status === 42;
   } catch {
     return false;
   }
@@ -359,4 +379,16 @@ function hasGitNexusDbLockedByGitNexusServer(dbPath, myPid) {
 
 module.exports = {
   hasGitNexusDbLockedByGitNexusServer,
+  // #2163 follow-up: the hook adapters wrap the augment CLI in the same
+  // guard. Returns a self-tested wrapper path — the built-in candidates are
+  // always absolute; a GITNEXUS_HOOK_TIMEOUT_PATH override is adopted as the
+  // exact string that passed the self-test. Same string is also the same
+  // RESOLUTION for absolute paths and for slashless names (PATH lookup is
+  // cwd-independent); a slash-containing RELATIVE override, however, is
+  // existsSync-checked and self-tested against this process's cwd while the
+  // adapters spawn the CLI with a `cwd` option (chdir-before-exec), so such
+  // a value can pass here yet ENOENT at the augment call site — set the
+  // override to an absolute path. Returns null when the wrapper is
+  // disabled/unavailable. Never call on win32 (see its JSDoc).
+  resolveUnixGuardTimeout,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.21",
+  "version": "1.6.8-rc.23",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",

package/skills/gitnexus-taint-analysis.md

@@ -0,0 +1,178 @@
+---
+name: gitnexus-taint-analysis
+description: "Use when working on, reviewing, or extending GitNexus's CFG/taint/PDG subsystem (the `--pdg` layers), or when reasoning about source→sink data-flow findings. Examples: \"How does taint analysis work here?\", \"Why didn't explain find this flow?\", \"Add a new sink/source\", \"Review the interprocedural taint code\"."
+---
+
+# CFG & Taint Analysis with GitNexus
+
+Expert knowledge for the opt-in `--pdg` program-analysis subsystem: control-flow
+graphs, reaching definitions, and intra- + inter-procedural taint. Read this
+before touching `gitnexus/src/core/ingestion/cfg/**` or
+`gitnexus/src/core/ingestion/taint/**`, or when explaining a finding.
+
+## When to Use
+
+- "How does the taint engine work / why is this flow (not) reported?"
+- Adding a source, sink, or sanitizer to the model.
+- Extending or reviewing the CFG / reaching-defs / taint / summary code.
+- Understanding the `explain` MCP tool's findings (intra- vs inter-procedural).
+- Debugging a false positive or false negative in `--pdg` output.
+
+## The layered substrate (build order)
+
+Taint runs **on** the graph, not beside it. Each layer is opt-in behind `--pdg`
+and a default `analyze` run is **byte-identical** (the golden parity gate is the
+hard floor for every change here).
+
+```
+L1  CFG            per-function basic blocks + control-flow edges   (M1 #2081)
+L2  REACHING_DEF   GEN/KILL def→use data dependence (pure solver)   (M2 #2082)
+L3  Taint (intra)  source→sink over RD facts, minus sanitizers      (M3 #2083)
+L4  Taint (inter)  per-function summaries composed over CALLS       (M4 #2084)
+```
+
+- **Worker-built, main-thread-solved.** The parse worker builds each function's
+  CFG + harvests def/use + call-site facts onto `ParsedFile.cfgSideChannel`
+  (plain, structured-clone-safe data — never AST nodes). The main thread runs
+  the pure solvers. NEVER re-parse on the main thread (re-introduces the #1983
+  OOM).
+- **In-phase emit (KTD1).** L1–L4-harvest all run INSIDE the scope-resolution
+  pdg window (`scope-resolution/pipeline/run.ts`, gated `input.pdg === true`),
+  because the disk-backed ParsedFile store is cleared when that phase ends — a
+  standalone post-`mro` phase would read empty data. The cross-function fixpoint
+  (L4) is the exception: it runs in its OWN registered phase (`taintSummaries`)
+  AFTER scope-resolution, because it needs the COMPLETE call graph, and consumes
+  small plain summary data threaded out via `ScopeResolutionOutput`.
+- **Pure-solver contract.** `computeReachingDefs`, `computeTaintFlows`,
+  `harvestFunctionSummary`, and `solveInterprocTaint` are pure and deterministic
+  (no graph, no I/O, no logger; sorted outputs). Snapshot tests and
+  content-derived edge ids depend on it.
+
+## Intra-procedural taint (L3)
+
+Forward reachability over RD facts from matched **sources** to matched **sinks**,
+killed by **sanitizers**. Key design points worth internalizing:
+
+- **Occurrence-tagged sites.** A flat per-arg binding set cannot tell
+  `exec(escape(x))` (safe) from `exec(x)` (finding); the harvest records nested
+  call structure (`SiteRecord.parent`/via-tags) so sanitizer interposition is
+  precise.
+- **Kind-set sanitizer model.** A taint carries a set of *neutralized*
+  `SinkKind`s; a sink fires unless its kind is in the set. So `escape(req.body)`
+  suppresses `res.send` (xss) but STILL fires `db.query` (sql) — a kind-blind
+  kill would be a suppressed live injection (the forbidden FN direction).
+  `path.basename(t)` neutralizes path-traversal only, not command-injection.
+- **Statement-level finding identity.** NOT block-pair (block conflation drops
+  distinct findings; `exec(req.body, req.query)` is two findings).
+- Persisted as `TAINTED` edges (BasicBlock→BasicBlock); the path rides the
+  `reason` column via the shared versioned codec (`taint/path-codec.ts`).
+
+## Interprocedural taint (L4) — the functional/summary method
+
+The production approach (Sharir-Pnueli 1981; the same shape as Meta's Pysa and
+Mariana Trench, and FB Infer) — NOT full IFDS tabulation. Each function is
+reduced to a compact **summary**, and summaries are composed over the already-
+resolved `CALLS` graph.
+
+**Summary shape** (`taint/summary-model.ts`, whole-parameter granularity):
+
+| Edge | Meaning | Analogue |
+|------|---------|----------|
+| `param→return` | a param flows to the return value | TITO — **reserved** (the floor already covers its recall; precision pass deferred) |
+| `param→callee-arg` | a param flows into arg *j* of a call (carries the path's neutralized sink kinds) | TITO into callee |
+| `param→sink` | a param reaches a modelled sink | partial/triggered sink |
+| `source→return` | the function generates+returns a source | generative — **composed** via the caller's `callResults` |
+| `source→callee-arg` | a generated source flows into a call | fixpoint SEED |
+| `callResults` | a user-function call's result flows to a sink/return/callee-arg in the caller | composes with callee `source→return` |
+
+**The fixpoint** (`taint/interproc-solver.ts`): the unit is `(function,
+parameter, source)`. Seed from `source→callee-arg`, propagate via
+`param→callee-arg`, fire a finding when a tainted param meets `param→sink`.
+
+- **Cycle-safe by monotonicity.** The tainted-set is monotone over a finite
+  lattice (`fn × param × source`), so the worklist converges — a recursive call
+  just re-proposes an already-visited entry. SCC condensation would only refine
+  processing order; correctness/termination don't require it.
+- **Source-discriminated state (load-bearing).** Key the state by the SOURCE
+  too. Keying only by `(fn, param)` collapses multi-source flows: a sink param
+  tainted by source A is marked visited and a later flow from source B is dropped
+  before firing — the recurring multi-source bug class. (Bit M3; bit M4 U9.)
+- **Name-based call join.** Match a summary's call-arg edge to a `CALLS` edge by
+  CALLEE NAME, not call-site line — line-base parity (CFG 1-based vs reference
+  site) is fragile; the callee identity is exact and context-insensitivity
+  taints the callee's param identically at every call site.
+- Persisted as `TAINT_PATH` edges (Function→Function), function-level hop chain
+  in `reason` via the same codec; confidence < the intra-procedural 1.0.
+
+**Context-insensitivity** is the accepted trade-off at this tier: one summary
+per function, return/call-site merging accepted (security-conservative). Expect
+some FP from merging; the bigger FN sources are unmodeled features (below).
+
+## Known false-negative classes (documented, deferred)
+
+The largest is **closures/callbacks** (`arr.forEach(() => sink(y))`) — taint
+into a callback is dropped without per-library models (true of CodeQL's JS libs
+too). Also deferred: field/property flows (`obj.x = taint; sink(obj.y)`),
+field-sensitive access paths, guard-style sanitizers, implicit/control-dependence
+flows, promise/async-await threading, and **destructured/rest params before a
+tainted simple param** (the summary port index is the binding ordinal, not the
+formal arg position — needs a formal-param index threaded from the worker
+`BindingEntry`). The interprocedural join is also context-insensitive: when one
+caller invokes two distinct **same-named callees**, a flow into one
+over-attributes to both (sound — over-report, never a missed flow). Absence of a
+finding is NOT proof of safety.
+
+## GitNexus-specific gotchas
+
+- **Function↔CFG join.** `FunctionCfg.functionStartLine` is 1-based; `Function`/
+  `Method` node `startLine` is 0-based — join at `startLine - 1`. Function nodes
+  have no column, so same-line functions (`{a:()=>x(), b:()=>y()}`) are
+  ambiguous → drop (the summary driver counts `unresolved`) rather than
+  cross-wire.
+- **No rel-property index (S1).** Kuzu has no secondary index on relationship
+  properties, and unanchored `[:TAINTED*]`/`[:TAINT_PATH*]` queries explode.
+  TAINT_PATH is therefore MATERIALIZED + anchored at analyze time, never
+  traversed live; `explain` reads it source-anchored + LIMIT-guarded.
+- **`explain` is the only discovery surface.** `TAINTED`/`TAINT_PATH` are
+  deliberately OUT of `VALID_RELATION_TYPES` (impact's allow-list) and the web
+  schema (pinned in `security.test.ts`). `explain` enumerates both layers
+  (cross-function findings carry `interprocedural: true`).
+- **One shared codec.** Both the emit path and `explain` import
+  `taint/path-codec.ts`. Two hand-rolled copies of a wire format drift — never
+  fork it. New metadata extends the format WITHIN the version when writer +
+  reader ship together.
+- **Cache versioning.** A worker-harvest shape change bumps the parse-cache pdg
+  NAMESPACE (`pdg:N`), NOT `SCHEMA_BUMP` (which cold-invalidates every user).
+  Persisted-graph/config changes ride `RepoMeta.pdg`'s key-union mismatch →
+  full writeback. Model content rides `taintModelVersion`.
+
+## Adding a source / sink / sanitizer
+
+Edit the language model in `taint/typescript-model.ts` (registered via the
+explicit `registerBuiltinTaintModels` seam, keyed by `SupportedLanguages`). The
+spec is hashable data (no functions). A sanitizer's `neutralizes` lists the
+EXACT sink kinds it defends — never a blanket kill. Add a fixture + assert the
+finding (or its absence) in `test/unit/taint/` (real-source harness:
+`test/helpers/ts-cfg-harness.ts`); the end-to-end proof is
+`test/integration/cfg/`.
+
+## Validation checklist for any `--pdg` change
+
+```
+1. tsc clean (schema additions are exhaustiveness-checked; watch the
+   api.ts getNodeQuery runtime read-path if a node label is added).
+2. Targeted vitest by directory (test/unit/taint, test/unit/cfg,
+   test/integration/cfg) — verify by ISOLATION, not full-suite exit
+   (known load-flakes). `node scripts/build.js` before worker/integration runs.
+3. Flag-off golden byte-identical (pipeline-graph-golden.test.ts).
+4. bench/cfg/measure.mjs --check (no fingerprint drift / budget regression).
+5. detect_changes() before commit; impact({direction:'upstream'}) before
+   editing shared symbols (KnowledgeGraph, RepoMeta, RelationshipType, codec).
+```
+
+## Prior art (for deeper design questions)
+
+Sharir & Pnueli 1981 (functional approach); Reps-Horwitz-Sagiv IFDS (POPL 1995);
+FlowDroid/StubDroid (access-path summaries); Pysa & Mariana Trench (TITO /
+propagations, parallel SCC fixpoint); CodeQL Models-as-Data (the richest port
+notation, incl. callback ports); Infer (content-keyed incremental summaries).