gitnexus 1.6.8-rc.8 → 1.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.8",
+  "version": "1.6.8",
   "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",
@@ -49,7 +49,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "test:cross-platform": "tsx scripts/run-cross-platform.ts",
-    "postinstall": "node scripts/materialize-vendor-grammars.cjs && node scripts/build-tree-sitter-grammars.cjs",
+    "postinstall": "node scripts/build-tree-sitter-grammars.cjs",
     "assert-publish-coverage": "node scripts/assert-publish-grammar-coverage.cjs",
     "prepare": "node scripts/build.js",
     "prepack": "node scripts/assert-publish-grammar-coverage.cjs && node scripts/build.js"
@@ -59,6 +59,7 @@
     "@ladybugdb/core": "^0.17.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
+    "busboy": "^1.6.0",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.3",
     "cors": "^2.8.5",
@@ -93,6 +94,11 @@
     "uuid": "^14.0.0"
   },
   "devDependencies": {
+    "@babel/generator": "^7.29.7",
+    "@babel/parser": "^7.29.7",
+    "@babel/traverse": "^7.29.7",
+    "@babel/types": "^7.29.7",
+    "@types/busboy": "^1.5.4",
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
     "@types/express": "^5.0.6",

package/scripts/assert-publish-grammar-coverage.cjs

@@ -112,6 +112,24 @@ function findCoverageProblems({ grammars }) {
   return problems;
 }
 
+/**
+ * Stray local source-build outputs under `vendor/<name>/build/`. These would
+ * ship in the tarball (`files: ["vendor"]` overrides .gitignore/.npmignore) AND
+ * shadow the committed prebuilds — `node-gyp-build` resolves `build/Release`
+ * BEFORE `prebuilds/`, so a consumer on the publisher's platform would load the
+ * stray (possibly stale/wrong) binding instead of the curated prebuild. The
+ * build dir is gitignored and only appears if a maintainer source-built locally
+ * (e.g. on a no-prebuild platform); refuse to publish it. (#2144 review.)
+ */
+function findStrayBuildArtifacts(vendorDir) {
+  if (!fs.existsSync(vendorDir)) return [];
+  return fs
+    .readdirSync(vendorDir)
+    .filter((d) => /^tree-sitter-/.test(d))
+    .filter((d) => fs.existsSync(path.join(vendorDir, d, 'build')))
+    .map((d) => `vendor/${d}/build`);
+}
+
 function collectGrammars(vendorDir, shipsVendorSource) {
   if (!fs.existsSync(vendorDir)) return [];
   return fs
@@ -141,6 +159,18 @@ function main() {
     process.exit(1);
   }
 
+  const stray = findStrayBuildArtifacts(vendorDir);
+  if (stray.length > 0) {
+    console.error(
+      '[publish-guard] Refusing to publish — stray source-build output under vendor/ would\n' +
+        'ship and shadow the committed prebuilds (node-gyp-build loads build/Release before\n' +
+        'prebuilds/):',
+    );
+    for (const s of stray) console.error(`  - ${s}`);
+    console.error('\nFix: remove it before packing, e.g. `rm -rf gitnexus/vendor/*/build`.');
+    process.exit(1);
+  }
+
   const problems = findCoverageProblems({ grammars });
   if (problems.length > 0) {
     console.error('[publish-guard] Refusing to publish — a vendored grammar would ship unusable:');
@@ -163,6 +193,7 @@ if (require.main === module) main();
 
 module.exports = {
   findCoverageProblems,
+  findStrayBuildArtifacts,
   filesShipsVendorSource,
   isBuildableFromSource,
   sourceBuildSet,

package/scripts/build-tree-sitter-grammars.cjs

@@ -1,19 +1,25 @@
 #!/usr/bin/env node
 /**
- * Activate the vendored tree-sitter native bindings after
- * materialize-vendor-grammars.cjs. One registry-driven script replaces the
- * former per-grammar build-tree-sitter-<name>.cjs files (they were ~95%
- * identical).
+ * Activate the vendored tree-sitter native bindings IN PLACE under `vendor/`.
+ * One registry-driven script replaces the former per-grammar
+ * build-tree-sitter-<name>.cjs files (they were ~95% identical).
+ *
+ * The grammars (tree-sitter-c/dart/proto/swift/kotlin) are loaded from
+ * `vendor/<name>/` by absolute path at runtime (see
+ * src/core/tree-sitter/vendored-grammars.ts) and are NEVER copied into
+ * node_modules — an undeclared package under node_modules is "extraneous" to
+ * every subsequent npm/npx reify, which prunes/relocates it (Windows
+ * `EPERM: …, symlink` + a silent grammar deletion on the 2nd run; #2111/#1728).
  *
  * For each grammar the resolution order is identical:
- *   1. If the package isn't materialized (no binding.gyp) or the binding is
+ *   1. If the vendored source is absent (no binding.gyp) or the binding is
  *      already built, do nothing.
  *   2. Prefer a committed prebuild for this platform-arch (toolchain-free) via
- *      node-gyp-build — the goal once build-tree-sitter-prebuilds.yml has
- *      populated all six tuples.
+ *      node-gyp-build — `vendor/<name>/prebuilds/` ships all six tuples, so on a
+ *      supported platform this returns immediately and writes nothing.
  *   3. Otherwise source-build from the vendored grammar source (binding.gyp +
- *      src/) so parsing still works on any toolchain host — e.g. CI, before the
- *      prebuilds land.
+ *      src/) into `vendor/<name>/build/` (gitignored) so parsing still works on
+ *      a toolchain host that lacks a matching prebuild.
  *
  * HARD INVARIANT: this runs in `gitnexus`'s postinstall, so it MUST NEVER throw
  * or exit non-zero — a failure for any single grammar must not break the install.
@@ -53,7 +59,7 @@ function buildGrammar(short) {
     return;
   }
 
-  const dir = path.join(__dirname, '..', 'node_modules', `tree-sitter-${short}`);
+  const dir = path.join(__dirname, '..', 'vendor', `tree-sitter-${short}`);
   const bindingGyp = path.join(dir, 'binding.gyp');
   const bindingNode = path.join(dir, 'build', 'Release', `tree_sitter_${short}_binding.node`);
 

package/scripts/cross-platform-tests.ts

@@ -37,6 +37,7 @@ const PLATFORM_LOGIC = [
   'test/unit/repo-manager.test.ts',
   'test/unit/repo-manager-finalize-invariant.test.ts',
   'test/unit/hooks.test.ts',
+  'test/unit/hook-db-lock-probe.test.ts',
   'test/unit/cursor-hook.test.ts',
   'test/unit/sidecar-recovery.test.ts',
   'test/unit/pool-wal-recovery.test.ts',

package/skills/gitnexus-debugging.md

@@ -16,10 +16,10 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 ## Workflow
 
 ```
-1. query({query: "<error or symptom>"})            → Find related execution flows
+1. query({search_query: "<error or symptom>"})            → Find related execution flows
 2. context({name: "<suspect>"})                    → See callers/callees/processes
 3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
-4. cypher({query: "MATCH path..."})                 → Custom traces if needed
+4. cypher({statement: "MATCH path..."})                 → Custom traces if needed
 ```
 
 > If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
@@ -45,13 +45,14 @@ description: "Use when the user is debugging a bug, tracing an error, or asking
 | Intermittent failure | `context` → look for external calls, async deps            |
 | Performance issue    | `context` → find symbols with many callers (hot paths)     |
 | Recent regression    | `detect_changes` to see what your changes affect           |
+| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |
 
 ## Tools
 
 **query** — find code related to error:
 
 ```
-query({query: "payment validation error"})
+query({search_query: "payment validation error"})
 → Processes: CheckoutFlow, ErrorHandling
 → Symbols: validatePayment, handlePaymentError, PaymentException
 ```
@@ -72,10 +73,21 @@ MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "valid
 RETURN [n IN nodes(path) | n.name] AS chain
 ```
 
+**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:
+
+```
+trace({ from: "processCheckout", to: "fetchRates" })
+→ status: ok, hopCount: 3
+→ hops: processCheckout → validatePayment → verifyCard → fetchRates
+→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
+```
+
+When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).
+
 ## Example: "Payment endpoint returns 500 intermittently"
 
 ```
-1. query({query: "payment error handling"})
+1. query({search_query: "payment error handling"})
    → Processes: CheckoutFlow, ErrorHandling
    → Symbols: validatePayment, handlePaymentError
 

package/skills/gitnexus-exploring.md

@@ -18,7 +18,7 @@ description: "Use when the user asks how code works, wants to understand archite
 ```
 1. READ gitnexus://repos                          → Discover indexed repos
 2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. query({query: "<what you want to understand>"})  → Find related execution flows
+3. query({search_query: "<what you want to understand>"})  → Find related execution flows
 4. context({name: "<symbol>"})            → Deep dive on specific symbol
 5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
@@ -50,7 +50,7 @@ description: "Use when the user asks how code works, wants to understand archite
 **query** — find execution flows related to a concept:
 
 ```
-query({query: "payment processing"})
+query({search_query: "payment processing"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Symbols grouped by flow with file locations
 ```
@@ -68,7 +68,7 @@ context({name: "validateUser"})
 
 ```
 1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
-2. query({query: "payment processing"})
+2. query({search_query: "payment processing"})
    → CheckoutFlow: processPayment → validateCard → chargeStripe
    → RefundFlow: initiateRefund → calculateRefund → processRefund
 3. context({name: "processPayment"})

package/skills/gitnexus-guide.md

@@ -35,9 +35,13 @@ For any task involving code understanding, debugging, impact analysis, or refact
 | `query`          | Process-grouped code intelligence — execution flows related to a concept |
 | `context`        | 360-degree symbol view — categorized refs, processes it participates in  |
 | `impact`         | Symbol blast radius — what breaks at depth 1/2/3 with confidence         |
+| `trace`          | Shortest path between two symbols — "how does A reach B?" in one call     |
 | `detect_changes` | Git-diff impact — what do your current changes affect                    |
 | `rename`         | Multi-file coordinated rename with confidence-tagged edits               |
 | `cypher`         | Raw graph queries (read `gitnexus://repo/{name}/schema` first)           |
+| `explain`        | Persisted taint findings — source→sink data flows (needs `analyze --pdg`) |
+| `pdg_query`      | Control/data dependence — what gates X (CDG) / where Y flows (REACHING_DEF); needs `analyze --pdg` |
+| `check`          | Check graph invariants such as circular imports                          |
 | `list_repos`     | Discover indexed repos (paginated — `limit`/`offset`)                    |
 
 ### Paginating `list_repos`
@@ -71,6 +75,35 @@ list_repos { offset: 400 }  → repos 401–437,                 hasMore false
 
 Notes: `offset` ≥ `total` returns an empty page (with `total` still reported). Out-of-range or malformed `limit`/`offset` (non-integer, `limit` outside `[1, 200]`, `offset < 0`) are rejected with a clear error — `limit` above the max is rejected, not silently capped. The order is deterministic (lower-cased name, then path), so paging never skips or duplicates an entry while the registry is unchanged.
 
+### Taint findings (`explain`)
+
+`explain` returns intra-procedural taint findings (`TAINTED` edges) recorded by `gitnexus analyze --pdg` — each with a sink category (command-injection, code-injection, path-traversal, sql-injection, xss), source/sink lines, and the ordered hop path with the variable carried on each hop.
+
+- `explain {}` — enumerate all findings for the repo (bounded by `limit`, deterministic order)
+- `explain { target: "src/vuln.ts" }` — findings in a file (suffix path match accepted)
+- `explain { target: "runUserCommand" }` — findings in a function (resolved like `context`; ambiguous names return ranked candidates)
+
+A repo indexed without `--pdg` returns a clear "no taint layer" note. Caveats: findings are intra-procedural only — cross-function, closure/callback, property/field, and implicit flows are not modeled, so the absence of a finding is **not** proof of safety. `SANITIZES` (sanitizer-kill) edges are queryable via `cypher`.
+
+### Control & data dependence (`pdg_query`)
+
+`pdg_query` reads the control/data-dependence layers `gitnexus analyze --pdg` records (CDG + REACHING_DEF, basic-block granular) — the control/data analog of `explain`. It is **always anchored** (a `target` file path or symbol, resolved like `context`) and has two modes:
+
+- `pdg_query { mode: "controls", target: "..." }` — CDG: "under what condition does X run?". Each edge is a controlling predicate block → dependent block with the branch sense (`'T'`/`'F'`) in `reason`; an edge into an early `return`/`throw` is flagged `guard: true` (guard-clause discovery — the sense depends on the predicate, so don't filter guards by a fixed label).
+- `pdg_query { mode: "flows", target: "...", variable?: "..." }` — REACHING_DEF def→use edges within the function; pass `variable` to trace one binding.
+
+A repo indexed without `--pdg` returns a "no PDG layer" note (or "status unknown" when the layer can't be confirmed). Intra-procedural only — cross-function flow is taint's domain (`explain`). The raw CDG/REACHING_DEF edges are also queryable via `cypher`. See the `gitnexus-pdg-query` skill for the full query surface.
+
+### Shortest path between two symbols (`trace`)
+
+`trace` answers "how does A reach B?" in one call — the shortest directed path over `CALLS` (plus `HAS_METHOD`, so a class-rooted trace descends into its methods) instead of chaining 3–8 `context`/`impact` hops by hand.
+
+- `trace { from: "validateUser", to: "executeQuery" }` — shortest path between two symbols.
+- Disambiguate common names with `from_uid`/`to_uid` (zero-ambiguity) or `from_file`/`to_file`; an ambiguous name returns ranked candidates.
+- `maxDepth` (default 10, max 30) bounds the search; `includeTests` (default false) lets the traversal pass through test-file symbols.
+
+Returns ordered `hops` (each `{ name, filePath, startLine }`) and an aligned `edges[]` of `{ relType, confidence }`, so call hops and containment (`HAS_METHOD`) hops stay distinguishable. When no path exists it reports the **furthest** reachable node (where the chain breaks) and sets `truncated: true` if a traversal cap was hit first. Every result carries a `status`: `ok` / `no_path` / `ambiguous` / `not_found` / `error`.
+
 ## Resources Reference
 
 Lightweight reads (~100-500 tokens) for navigation:

package/skills/gitnexus-pdg-query.md

@@ -0,0 +1,89 @@
+---
+name: gitnexus-pdg-query
+description: "Use when querying or extending GitNexus's PDG control/data-dependence surface (the `pdg_query` MCP tool, CDG/REACHING_DEF edges), or reasoning about \"what controls X\" / \"where does Y flow\" / guard clauses. Examples: \"what guards this statement?\", \"trace this variable within the function\", \"why is the pdg_query result empty?\", \"add a CDG query\"."
+---
+
+# PDG query surface with GitNexus
+
+Expert knowledge for the `pdg_query` MCP tool and the control/data-dependence
+edges it reads — the opt-in `--pdg` program-dependence layers. Read this before
+touching `gitnexus/src/mcp/local/local-backend.ts` (`_pdgQueryImpl`) or the
+`pdg_query` tool def, or when explaining a `pdg_query` result.
+
+## When to Use
+
+- "Under what condition does this statement run?" (guarding predicates).
+- "Where does this variable flow inside the function?" (def→use).
+- Guard-clause discovery (early-return guards — subsumes the #559 heuristic).
+- Extending or reviewing `pdg_query` / the CDG / REACHING_DEF read path.
+- Debugging an empty or surprising `pdg_query` result.
+
+## The layered substrate (build order)
+
+`pdg_query` runs **on** the same graph taint runs on. Each layer is opt-in
+behind `--pdg`; a default `analyze` run records none of them (byte-identical).
+
+```
+L1  CFG            per-function basic blocks + control-flow edges   (M1 #2081)
+L2  REACHING_DEF   GEN/KILL def→use data dependence (pure solver)   (M2 #2082)
+L5  CDG            Ferrante control dependence (post-dominators)    (M5 #2085)
+```
+
+All three are `BasicBlock → BasicBlock` edges in the single `CodeRelation` table
+(keyed by the `type` property). There is **no** `Function → BasicBlock` edge.
+
+## The two modes
+
+- `pdg_query({ mode: 'controls', target })` — CDG. For the anchored function,
+  each edge: controlling predicate block → dependent block + branch sense in
+  `label` (`'T'` = predicate's true/taken arm, `'F'` = false/fall-through). An
+  edge into an early-return/throw block is flagged `guard: true`.
+- `pdg_query({ mode: 'flows', target, variable? })` — REACHING_DEF def→use
+  edges; `variable` filters to one binding.
+
+`target` is **required** — a file path or a symbol/function name (resolved like
+`context()`). There is no anchorless mode (see below).
+
+## The corrected guard-clause Cypher
+
+The RFC #567 §2 form (`[:CDG {label:'F'}]`) does **not** run as written. Edges
+are values of the single `CodeRelation` table's `type` property, and the branch
+sense is in `reason`, NOT a `label` column:
+
+```cypher
+MATCH (pred:BasicBlock)-[r:CodeRelation {type: 'CDG'}]->(dep:BasicBlock)
+WHERE dep.text STARTS WITH 'return' OR dep.text STARTS WITH 'throw'
+RETURN pred.startLine, r.reason AS branch, dep.startLine, dep.text
+```
+
+`r.reason` is the sense the predicate took to reach the early exit. For
+`if (!ok) return;` the return rides the predicate's **true** arm (`'T'`) and the
+protected body rides the **false** arm (`'F'`) — polarity depends on the guard,
+so don't hard-code one sense.
+
+## Gotchas (the load-bearing ones)
+
+- **Always anchored + LIMIT-bounded.** LadybugDB has no rel-property index, so
+  an unanchored `[:CDG*]`/`[:REACHING_DEF*]` path scan is unbounded. `pdg_query`
+  requires `target` and bounds the page; raw `cypher` callers must anchor on a
+  file id-prefix or symbol span themselves.
+- **BasicBlock↔symbol join is reconstructed.** No `Function→BasicBlock` edge:
+  the block is matched by its id-prefix (`BasicBlock:<file>:<fnStartLine>:…`)
+  plus `startLine` within the symbol's span. BasicBlock `startLine` is **1-based**
+  while the symbol node's `startLine`/`endLine` are **0-based**, so **both** bounds
+  are shifted `+1` (`[symStart+1, symEnd+1]`): the upper `+1` keeps a guard/def/use
+  on the function's **final line**, the lower `+1` excludes an adjacent function's
+  block on the line directly **above**. Same-line / nested functions anchor coarsely.
+- **No PDG layer ⇒ a note, not an error.** If the repo wasn't indexed with
+  `--pdg` the tool returns `{ results: [], note: "no PDG layer …" }` (cheap meta
+  probe on `RepoMeta.pdg.maxCdgEdgesPerFunction` / `maxReachingDefEdgesPerFunction`).
+- **CDG labels are binary in M5/M6.** Every `switch`-case arm is `'T'`; per-case
+  conditions are not yet distinguished.
+- **Intra-procedural only.** Cross-function flow is taint's domain (`explain`).
+
+## Mirror, don't fork
+
+`_pdgQueryImpl` is the front half of `_explainImpl` (WAL wrapper, meta no-layer
+probe, limit validation, `resolveSymbolCandidates` anchoring) with CDG/
+REACHING_DEF instead of TAINTED — and none of taint's path-codec / interproc
+`TAINT_PATH` machinery. Reuse those shared helpers; do not re-implement them.

package/skills/gitnexus-refactoring.md

@@ -17,7 +17,7 @@ description: "Use when the user wants to rename, extract, split, move, or restru
 
 ```
 1. impact({target: "X", direction: "upstream"})  → Map all dependents
-2. query({query: "X"})                            → Find execution flows involving X
+2. query({search_query: "X"})                            → Find execution flows involving X
 3. context({name: "X"})                           → See all incoming/outgoing refs
 4. Plan update order: interfaces → implementations → callers → tests
 ```

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).

package/vendor/tree-sitter-c/package.json

@@ -6,7 +6,7 @@
   "license": "MIT",
   "main": "bindings/node/index.js",
   "types": "bindings/node/index.d.ts",
-  "_vendoredBy": "gitnexus - runtime package derived from tree-sitter-c@0.21.4 (tree-sitter/tree-sitter-c). HELD at 0.21.4 for ABI compatibility with the bundled tree-sitter@0.21.1 runtime (#1242/#858) — do not bump without the runtime upgrade. Vendored because upstream ships native prebuilds for only 4 of 6 platforms (no linux-arm64/win32-arm64, #2116), and tree-sitter-c is a REQUIRED grammar whose source build hard-fails `npm install` on a toolchain-less ARM host. GitNexus cross-builds all six prebuilds via .github/workflows/build-tree-sitter-prebuilds.yml; the C source (binding.gyp + src/) is ALSO vendored so build-tree-sitter-c.cjs can source-build the binding on a toolchain host when no prebuild matches (e.g. CI before prebuilds land). Copied to node_modules/ by materialize-vendor-grammars.cjs (no scripts.install here — #836/#1728).",
+  "_vendoredBy": "gitnexus - runtime package derived from tree-sitter-c@0.21.4 (tree-sitter/tree-sitter-c). HELD at 0.21.4 for ABI compatibility with the bundled tree-sitter@0.21.1 runtime (#1242/#858) — do not bump without the runtime upgrade. Vendored because upstream ships native prebuilds for only 4 of 6 platforms (no linux-arm64/win32-arm64, #2116), and tree-sitter-c is a REQUIRED grammar whose source build hard-fails `npm install` on a toolchain-less ARM host. GitNexus cross-builds all six prebuilds via .github/workflows/build-tree-sitter-prebuilds.yml; the C source (binding.gyp + src/) is ALSO vendored so build-tree-sitter-grammars.cjs can source-build the binding on a toolchain host when no prebuild matches (e.g. CI before prebuilds land). Loaded from vendor/ by absolute path at runtime (vendored-grammars.ts) — NEVER copied to node_modules (#2111) (no scripts.install here — #836/#1728).",
   "peerDependencies": {
     "tree-sitter": "^0.21.0"
   },

package/vendor/tree-sitter-dart/package.json

@@ -6,7 +6,7 @@
   "license": "ISC",
   "main": "bindings/node",
   "types": "bindings/node",
-  "_vendoredBy": "gitnexus - pinned to UserNobody14/tree-sitter-dart commit 80e23c07b64494f7e21090bb3450223ef0b192f4. Copied to node_modules/ by materialize-vendor-grammars.cjs; native build via build-tree-sitter-dart.cjs (#1728, #836).",
+  "_vendoredBy": "gitnexus - pinned to UserNobody14/tree-sitter-dart commit 80e23c07b64494f7e21090bb3450223ef0b192f4. Loaded from vendor/ by absolute path at runtime (vendored-grammars.ts) — NEVER copied to node_modules (#2111); native build via build-tree-sitter-grammars.cjs (#1728, #836).",
   "peerDependencies": {
     "tree-sitter": "^0.21.0"
   },

package/vendor/tree-sitter-kotlin/package.json

@@ -6,7 +6,7 @@
   "license": "MIT",
   "main": "bindings/node/index.js",
   "types": "bindings/node/index.d.ts",
-  "_vendoredBy": "gitnexus - runtime package derived from tree-sitter-kotlin@0.3.8 (fwcd). Unlike Swift's upstream-shipped prebuilds, upstream tree-sitter-kotlin ships SOURCE ONLY (no prebuilds/); the native prebuilds/ here are GitNexus-cross-built by .github/workflows/build-tree-sitter-prebuilds.yml. The grammar source (parser.c/scanner.c/binding.gyp + src/) is ALSO vendored so build-tree-sitter-kotlin.cjs can source-build the binding on a toolchain host when no prebuild matches (e.g. CI before prebuilds land). The generated parser.c is large (~23 MB on disk; it compresses heavily in git); once the prebuilds cover every platform-arch the source serves only as the fallback. Copied to node_modules/ by materialize-vendor-grammars.cjs (no scripts.install here — #836/#1728).",
+  "_vendoredBy": "gitnexus - runtime package derived from tree-sitter-kotlin@0.3.8 (fwcd). Unlike Swift's upstream-shipped prebuilds, upstream tree-sitter-kotlin ships SOURCE ONLY (no prebuilds/); the native prebuilds/ here are GitNexus-cross-built by .github/workflows/build-tree-sitter-prebuilds.yml. The grammar source (parser.c/scanner.c/binding.gyp + src/) is ALSO vendored so build-tree-sitter-grammars.cjs can source-build the binding on a toolchain host when no prebuild matches (e.g. CI before prebuilds land). The generated parser.c is large (~23 MB on disk; it compresses heavily in git); once the prebuilds cover every platform-arch the source serves only as the fallback. Loaded from vendor/ by absolute path at runtime (vendored-grammars.ts) — NEVER copied to node_modules (#2111) (no scripts.install here — #836/#1728).",
   "peerDependencies": {
     "tree-sitter": "^0.21.0"
   },

package/vendor/tree-sitter-proto/package.json

@@ -5,7 +5,7 @@
   "repository": "https://github.com/coder3101/tree-sitter-proto",
   "license": "MIT",
   "main": "bindings/node",
-  "_vendoredBy": "gitnexus — materialized to node_modules/ by materialize-vendor-grammars.cjs; native build via build-tree-sitter-proto.cjs. Do NOT re-add dependencies or an install script (#836, #1728).",
+  "_vendoredBy": "gitnexus — loaded from vendor/ by absolute path at runtime (vendored-grammars.ts) — NEVER copied to node_modules (#2111); native build via build-tree-sitter-grammars.cjs. Do NOT re-add dependencies or an install script (#836, #1728).",
   "peerDependencies": {
     "tree-sitter": ">=0.21.0"
   }

package/vendor/tree-sitter-swift/package.json

@@ -9,7 +9,7 @@
     "type": "git",
     "url": "git+https://github.com/alex-pinkus/tree-sitter-swift.git"
   },
-  "_vendoredBy": "gitnexus - runtime package derived from official tree-sitter-swift@0.7.1 (gitHead 88bfd19a89be9d0481b14566fb6160cccea2fe0a). Unified with Dart/Proto/Kotlin/C: the grammar source (parser.c/scanner.c/binding.gyp + src/) is ALSO vendored so build-tree-sitter-grammars.cjs can source-build the binding on a toolchain host when no prebuild matches (e.g. CI before prebuilds land); src/parser.c is the ABI-14 default (~18 MB on disk, compresses heavily in git — the upstream parser_abi13.c alternate is not vendored). The native prebuilds/ are GitNexus-cross-built by .github/workflows/build-tree-sitter-prebuilds.yml (originally upstream-shipped). Build activation runs via gitnexus/scripts/build-tree-sitter-grammars.cjs after materialize-vendor-grammars.cjs (no scripts.install here — avoids #836 / #1728).",
+  "_vendoredBy": "gitnexus - runtime package derived from official tree-sitter-swift@0.7.1 (gitHead 88bfd19a89be9d0481b14566fb6160cccea2fe0a). Unified with Dart/Proto/Kotlin/C: the grammar source (parser.c/scanner.c/binding.gyp + src/) is ALSO vendored so build-tree-sitter-grammars.cjs can source-build the binding on a toolchain host when no prebuild matches (e.g. CI before prebuilds land); src/parser.c is the ABI-14 default (~18 MB on disk, compresses heavily in git — the upstream parser_abi13.c alternate is not vendored). The native prebuilds/ are GitNexus-cross-built by .github/workflows/build-tree-sitter-prebuilds.yml (originally upstream-shipped). Build activation runs via gitnexus/scripts/build-tree-sitter-grammars.cjs (no scripts.install here — avoids #836 / #1728).",
   "peerDependencies": {
     "tree-sitter": "^0.21.1 || ^0.22.1"
   },