gitnexus 1.6.8-rc.20 → 1.6.8-rc.21

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

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

package/dist/core/ingestion/taint/site-safety.js

@@ -0,0 +1,98 @@
+const SITE_KINDS = new Set(['call', 'new', 'member-read']);
+/**
+ * Whether a structurally-valid CFG's M3 `sites` annotations are safe to feed
+ * to the taint matcher/propagator. `true` when no statement carries sites
+ * (pre-M3 channel, or no calls) — absence is the well-formed empty case.
+ */
+export const hasTaintSafeSites = (cfg) => {
+    // Sites carry binding indices — a channel with sites but no binding table
+    // has nothing to range-check them against: reject (checked per statement).
+    const bindingCount = Array.isArray(cfg.bindings) ? cfg.bindings.length : -1;
+    for (const block of cfg.blocks) {
+        const stmts = block.statements;
+        if (stmts === undefined)
+            continue;
+        if (!Array.isArray(stmts))
+            return false;
+        for (const s of stmts) {
+            if (s?.sites === undefined)
+                continue;
+            if (bindingCount < 0)
+                return false;
+            if (!isSafeSiteList(s.sites, bindingCount))
+                return false;
+        }
+    }
+    return true;
+};
+const isSafeSiteList = (sites, bindingCount) => {
+    if (!Array.isArray(sites))
+        return false;
+    const siteCount = sites.length;
+    const bindingInRange = (i) => Number.isInteger(i) && i >= 0 && i < bindingCount;
+    const siteInRange = (i) => Number.isInteger(i) && i >= 0 && i < siteCount;
+    for (const site of sites) {
+        if (site === null || typeof site !== 'object')
+            return false;
+        if (typeof site.kind !== 'string' || !SITE_KINDS.has(site.kind))
+            return false;
+        if (site.callee !== undefined && typeof site.callee !== 'string')
+            return false;
+        if (site.receiver !== undefined && !bindingInRange(site.receiver))
+            return false;
+        if (site.requireArg !== undefined && typeof site.requireArg !== 'string')
+            return false;
+        if (site.template !== undefined && typeof site.template !== 'boolean')
+            return false;
+        if (site.spread !== undefined &&
+            (!Number.isInteger(site.spread) || site.spread < 0)) {
+            return false;
+        }
+        if (site.parent !== undefined) {
+            const p = site.parent;
+            if (!Array.isArray(p) || p.length !== 2)
+                return false;
+            if (!siteInRange(p[0]))
+                return false;
+            if (!Number.isInteger(p[1]) || p[1] < 0)
+                return false;
+        }
+        if (site.resultDefs !== undefined) {
+            if (!Array.isArray(site.resultDefs) || !site.resultDefs.every(bindingInRange))
+                return false;
+        }
+        if (site.args !== undefined) {
+            if (!Array.isArray(site.args))
+                return false;
+            for (const position of site.args) {
+                if (!Array.isArray(position))
+                    return false;
+                for (const entry of position) {
+                    if (typeof entry === 'number') {
+                        if (!bindingInRange(entry))
+                            return false;
+                    }
+                    else if (Array.isArray(entry) && entry.length === 2) {
+                        if (!bindingInRange(entry[0]) || !siteInRange(entry[1]))
+                            return false;
+                    }
+                    else {
+                        return false;
+                    }
+                }
+            }
+        }
+        if (site.kind === 'member-read') {
+            // The matcher dereferences both unconditionally on member reads.
+            if (!bindingInRange(site.object) || typeof site.property !== 'string')
+                return false;
+        }
+        else {
+            if (site.object !== undefined && !bindingInRange(site.object))
+                return false;
+            if (site.property !== undefined && typeof site.property !== 'string')
+                return false;
+        }
+    }
+    return true;
+};

package/dist/core/ingestion/taint/source-sink-config.d.ts

@@ -1,36 +1,107 @@
 /**
- * Source/sink/sanitizer config model (issue #2080, taint/PDG substrate M0).
+ * Source/sink/sanitizer config model (issue #2080 M0 seam, extended by #2083
+ * M3 U2).
  *
- * The per-language taint configuration *shape*. M0 ships only the type and an
- * (empty) registry seam — no analysis consumes it yet. M3 (#2083, intra-proc
- * taint) populates per-language specs and reads them when emitting TAINTED /
- * SANITIZES edges.
+ * The per-language taint configuration *shape*. M0 shipped only the bare
+ * `{name, args?}` callable matcher and an empty registry seam; M3 U2 extends
+ * it with the `kind` taxonomy and the resolution-mechanism fields the
+ * import-aware matcher (`taint/match.ts`) needs, and fills the registry with
+ * the built-in TS/JS model (`taint/typescript-model.ts`).
  *
- * Kept deliberately minimal: enough for M3 to express "callable X is a
- * source / sink / sanitizer, optionally for argument position N" without M0
- * committing to matcher semantics it cannot yet validate. The shape is
- * expected to grow (e.g. sanitizer escape conditions, return-position taint)
- * when M3 makes contact with real flows; that is a forward-declared-interface
- * design choice, not a finished contract.
+ * Design rule: entries describe WHAT a callable is (category + how its name
+ * resolves), never HOW matching works — matching semantics (import joins,
+ * shadow checks, spread/template position rules) live in the matcher so the
+ * spec stays declarative data that can hash into `taintModelVersion`.
  */
+/** Categories of taint sources. M3 ships remote HTTP input only. */
+export type SourceKind = 'remote-input';
 /**
- * Identifies a callable that participates in taint flow. `name` is matched
- * against a resolved callable (simple or qualified name — exact matching
- * semantics are M3's call). `args` optionally narrows to specific 0-based
- * argument positions that carry taint (for a source/sink) or clear it (for a
- * sanitizer); omit to mean "unspecified / all".
+ * Vulnerability categories for sinks. Sanitizers reference the SAME taxonomy
+ * via {@link TaintSanitizerEntry.neutralizes}: a sanitizer kill applies only
+ * when it neutralizes the matched sink's kind (`path.basename` strips
+ * directories, not shell metacharacters — a kind-blind kill is a suppressed
+ * live command injection, the forbidden false-negative direction).
  */
-export interface TaintCallableMatcher {
+export type SinkKind = 'command-injection' | 'code-injection' | 'path-traversal' | 'sql-injection' | 'xss';
+/**
+ * Identifies a callable that participates in taint flow. `name` is the
+ * callable's own (unqualified) name — qualification comes from the
+ * resolution-mechanism fields on the extending entry types, not from dotted
+ * `name` strings. `args` optionally narrows to specific 0-based argument
+ * positions that carry taint into a sink (or are cleared by a sanitizer);
+ * omit to mean "all positions".
+ */
+export interface TaintCallableMatcher<K extends string = string> {
+    readonly name: string;
+    readonly args?: readonly number[];
+    /** Category label — drives finding classification and sanitizer kind-compat. */
+    readonly kind: K;
+}
+/**
+ * A sink callable. Exactly one resolution mechanism should be set per entry:
+ *
+ * - `module` — the callable lives in a package/builtin module; the matcher
+ *   resolves call sites against it import-aware (ESM `parsedImports` aliases,
+ *   namespace handles, and the CommonJS `require('<literal>')` join). `name`
+ *   is the exported member (`'exec'` of `'child_process'`); the pseudo-name
+ *   `'default'` denotes invoking the module's default export / the module
+ *   handle itself.
+ * - `global` — a true ECMAScript global (`eval`, `Function`); matched by bare
+ *   name only when the name is not shadowed by an in-function declaration and
+ *   not bound by an import. `newOnly` further restricts to `new` expressions
+ *   (`new Function(body)`).
+ * - `anyReceiver` — a method matched on ANY receiver chain by its final
+ *   segment (`.query(sql)` / `.execute(sql)` on whatever the DB handle is
+ *   named) — deliberately name-conventional, like Semgrep's default rules.
+ * - `receivers` — a method matched only on the listed conventional receiver
+ *   names (`res.send` / `res.write`); exactly `<receiver>.<name>`, name-based.
+ */
+export interface TaintSinkEntry extends TaintCallableMatcher<SinkKind> {
+    readonly module?: string;
+    readonly global?: boolean;
+    /** Only meaningful with `global`: match `new <name>(…)` sites only. */
+    readonly newOnly?: boolean;
+    readonly anyReceiver?: boolean;
+    readonly receivers?: readonly string[];
+}
+/**
+ * A sanitizer callable. Carries the sink kinds it `neutralizes` instead of a
+ * `kind` of its own. STRICTER resolution than sinks by design: only the
+ * `module` (import-aware) and `global` mechanisms exist — never a bare-name
+ * convention — because a sanitizer mis-match is a false KILL (a user's own
+ * `escape` helper must not suppress findings), while a sink mis-match is
+ * merely noise. `args` narrows which argument positions are cleared (omit =
+ * all).
+ */
+export interface TaintSanitizerEntry {
     readonly name: string;
     readonly args?: readonly number[];
+    readonly neutralizes: readonly SinkKind[];
+    readonly module?: string;
+    readonly global?: boolean;
+}
+/**
+ * A member-read taint source: reading `<object>.<property>` where the object
+ * is one of the conventional receiver `objects` names (`req`/`request`) and
+ * the property is one of `properties` (`body`, `query`, …). Matching is
+ * name-based on the harvested `member-read` site (Semgrep-convention, not
+ * type-aware — the accepted M3 FP/FN trade recorded in the plan's risk
+ * table). One entry fans out over the objects × properties product.
+ */
+export interface TaintMemberSourceEntry {
+    readonly kind: SourceKind;
+    readonly objects: readonly string[];
+    readonly properties: readonly string[];
 }
 /**
- * The taint configuration for a single language: which callables introduce
- * taint (sources), which are dangerous to reach with tainted input (sinks),
- * and which clear taint (sanitizers).
+ * The taint configuration for a single language: which member reads introduce
+ * taint (sources), which callables are dangerous to reach with tainted input
+ * (sinks), and which callables clear it (sanitizers). M3 sources are
+ * member-read entries only; call-result sources are a forward extension
+ * (add a union variant), not a missing case.
  */
 export interface SourceSinkSanitizerSpec {
-    readonly sources: readonly TaintCallableMatcher[];
-    readonly sinks: readonly TaintCallableMatcher[];
-    readonly sanitizers: readonly TaintCallableMatcher[];
+    readonly sources: readonly TaintMemberSourceEntry[];
+    readonly sinks: readonly TaintSinkEntry[];
+    readonly sanitizers: readonly TaintSanitizerEntry[];
 }

package/dist/core/ingestion/taint/source-sink-config.js

@@ -1,16 +1,16 @@
 /**
- * Source/sink/sanitizer config model (issue #2080, taint/PDG substrate M0).
+ * Source/sink/sanitizer config model (issue #2080 M0 seam, extended by #2083
+ * M3 U2).
  *
- * The per-language taint configuration *shape*. M0 ships only the type and an
- * (empty) registry seam — no analysis consumes it yet. M3 (#2083, intra-proc
- * taint) populates per-language specs and reads them when emitting TAINTED /
- * SANITIZES edges.
+ * The per-language taint configuration *shape*. M0 shipped only the bare
+ * `{name, args?}` callable matcher and an empty registry seam; M3 U2 extends
+ * it with the `kind` taxonomy and the resolution-mechanism fields the
+ * import-aware matcher (`taint/match.ts`) needs, and fills the registry with
+ * the built-in TS/JS model (`taint/typescript-model.ts`).
  *
- * Kept deliberately minimal: enough for M3 to express "callable X is a
- * source / sink / sanitizer, optionally for argument position N" without M0
- * committing to matcher semantics it cannot yet validate. The shape is
- * expected to grow (e.g. sanitizer escape conditions, return-position taint)
- * when M3 makes contact with real flows; that is a forward-declared-interface
- * design choice, not a finished contract.
+ * Design rule: entries describe WHAT a callable is (category + how its name
+ * resolves), never HOW matching works — matching semantics (import joins,
+ * shadow checks, spread/template position rules) live in the matcher so the
+ * spec stays declarative data that can hash into `taintModelVersion`.
  */
 export {};

package/dist/core/ingestion/taint/source-sink-registry.d.ts

@@ -1,10 +1,12 @@
 /**
  * Per-language source/sink/sanitizer registry seam (issue #2080).
  *
- * A keyed registry of {@link SourceSinkSanitizerSpec} by language id. M0 stands
- * up the empty seam — no language is registered and nothing in the pipeline
- * reads it. M3 (#2083) registers per-language specs and queries this registry
- * when emitting taint edges.
+ * A keyed registry of {@link SourceSinkSanitizerSpec} by language id. M0 stood
+ * up the empty seam; M3 U2 (#2083) fills it with the built-in TS/JS model via
+ * the EXPLICIT `registerBuiltinTaintModels()` seam in `typescript-model.ts` —
+ * deliberately not an import side-effect. The U4 taint emit path must call it
+ * once before the pdg window consumes the registry (idempotent; the registry
+ * itself stays empty until then, preserving default-run parity).
  *
  * The store is module-level (matching the codebase's other per-language
  * registries). {@link clearSourceSinkRegistry} resets it for test isolation.

package/dist/core/ingestion/taint/source-sink-registry.js

@@ -1,10 +1,12 @@
 /**
  * Per-language source/sink/sanitizer registry seam (issue #2080).
  *
- * A keyed registry of {@link SourceSinkSanitizerSpec} by language id. M0 stands
- * up the empty seam — no language is registered and nothing in the pipeline
- * reads it. M3 (#2083) registers per-language specs and queries this registry
- * when emitting taint edges.
+ * A keyed registry of {@link SourceSinkSanitizerSpec} by language id. M0 stood
+ * up the empty seam; M3 U2 (#2083) fills it with the built-in TS/JS model via
+ * the EXPLICIT `registerBuiltinTaintModels()` seam in `typescript-model.ts` —
+ * deliberately not an import side-effect. The U4 taint emit path must call it
+ * once before the pdg window consumes the registry (idempotent; the registry
+ * itself stays empty until then, preserving default-run parity).
  *
  * The store is module-level (matching the codebase's other per-language
  * registries). {@link clearSourceSinkRegistry} resets it for test isolation.

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

@@ -0,0 +1,38 @@
+/**
+ * Built-in TS/JS taint model (#2083 M3 U2, plan KTD7).
+ *
+ * The canonical Express/Node source/sink/sanitizer set, registered for the
+ * `typescript` and `javascript` language ids via the EXPLICIT
+ * {@link registerBuiltinTaintModels} seam — deliberately not an import
+ * side-effect, so the U4 emit path controls WHEN registration happens (call
+ * it once before the pdg window runs; it is idempotent — the registry is
+ * last-write-wins on the same language id).
+ *
+ * `taintModelVersion` is a deterministic digest of the FULL model content
+ * (entries, kinds, args, modules). It joins the RepoMeta `pdg` stamp in U5 so
+ * that ANY model change — adding an entry, relabeling a kind — trips full
+ * writeback on an existing `--pdg` index (R7): persisted findings must never
+ * outlive the model that produced them.
+ */
+import type { SourceSinkSanitizerSpec } from './source-sink-config.js';
+/**
+ * The built-in TS/JS model. Module provenance uses bare specifier names —
+ * the matcher normalizes the `node:` scheme prefix, so `import { exec } from
+ * 'node:child_process'` resolves identically.
+ */
+export declare const TS_JS_TAINT_MODEL: SourceSinkSanitizerSpec;
+/**
+ * Deterministic digest of a spec's full content. Key order is canonicalized
+ * (recursively sorted) so the version reflects CONTENT, not literal layout;
+ * array order is semantic (entry identity) and intentionally preserved.
+ */
+export declare function computeTaintModelVersion(spec: SourceSinkSanitizerSpec): string;
+/** Version stamp of the built-in TS/JS model (joins the RepoMeta pdg key in U5). */
+export declare const taintModelVersion: string;
+/**
+ * Register the built-in model for TypeScript and JavaScript. Explicit init
+ * seam for the U4 emit path (call before the pdg window consumes the
+ * registry); idempotent. Vue and other TS-adjacent language ids are
+ * deliberately NOT registered — the M3 scope is TS/JS only.
+ */
+export declare function registerBuiltinTaintModels(): void;

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

@@ -0,0 +1,102 @@
+/**
+ * Built-in TS/JS taint model (#2083 M3 U2, plan KTD7).
+ *
+ * The canonical Express/Node source/sink/sanitizer set, registered for the
+ * `typescript` and `javascript` language ids via the EXPLICIT
+ * {@link registerBuiltinTaintModels} seam — deliberately not an import
+ * side-effect, so the U4 emit path controls WHEN registration happens (call
+ * it once before the pdg window runs; it is idempotent — the registry is
+ * last-write-wins on the same language id).
+ *
+ * `taintModelVersion` is a deterministic digest of the FULL model content
+ * (entries, kinds, args, modules). It joins the RepoMeta `pdg` stamp in U5 so
+ * that ANY model change — adding an entry, relabeling a kind — trips full
+ * writeback on an existing `--pdg` index (R7): persisted findings must never
+ * outlive the model that produced them.
+ */
+import { createHash } from 'node:crypto';
+import { SupportedLanguages } from '../../../_shared/index.js';
+import { registerSourceSinkConfig } from './source-sink-registry.js';
+/**
+ * The built-in TS/JS model. Module provenance uses bare specifier names —
+ * the matcher normalizes the `node:` scheme prefix, so `import { exec } from
+ * 'node:child_process'` resolves identically.
+ */
+export const TS_JS_TAINT_MODEL = {
+    sources: [
+        // Express-convention request member reads, matched name-based on the
+        // receiver (`req`/`request`) — the plan's accepted Semgrep-style trade.
+        {
+            kind: 'remote-input',
+            objects: ['req', 'request'],
+            properties: ['body', 'query', 'params', 'headers', 'cookies'],
+        },
+    ],
+    sinks: [
+        // Command execution — the command string is argument 0.
+        { name: 'exec', kind: 'command-injection', args: [0], module: 'child_process' },
+        { name: 'execSync', kind: 'command-injection', args: [0], module: 'child_process' },
+        { name: 'spawn', kind: 'command-injection', args: [0], module: 'child_process' },
+        // Code evaluation. `eval` takes code at 0; `new Function(...)` treats
+        // EVERY argument as source text (params + body), so `args` is omitted
+        // (= all positions) rather than pinned to 0.
+        { name: 'eval', kind: 'code-injection', args: [0], global: true },
+        { name: 'Function', kind: 'code-injection', global: true, newOnly: true },
+        // Filesystem path consumption — path argument 0.
+        { name: 'readFile', kind: 'path-traversal', args: [0], module: 'fs' },
+        { name: 'readFileSync', kind: 'path-traversal', args: [0], module: 'fs' },
+        { name: 'writeFile', kind: 'path-traversal', args: [0], module: 'fs' },
+        { name: 'writeFileSync', kind: 'path-traversal', args: [0], module: 'fs' },
+        // SQL — `.query(sql)` / `.execute(sql)` member calls on ANY receiver
+        // (mysql2/pg/knex handles go by many names; receiver-conventional).
+        { name: 'query', kind: 'sql-injection', args: [0], anyReceiver: true },
+        { name: 'execute', kind: 'sql-injection', args: [0], anyReceiver: true },
+        // Reflected XSS — Express response writes, conventional receiver `res`.
+        { name: 'send', kind: 'xss', args: [0], receivers: ['res'] },
+        { name: 'write', kind: 'xss', args: [0], receivers: ['res'] },
+    ],
+    sanitizers: [
+        // URL-encoding: neutralizes markup injection AND path separators
+        // (`%2F` is not a separator inside a path component).
+        { name: 'encodeURIComponent', neutralizes: ['xss', 'path-traversal'], global: true },
+        // `escape-html` exports its function as the module default — the
+        // `'default'` pseudo-name matches the default-imported / require'd
+        // module handle being invoked directly.
+        { name: 'default', neutralizes: ['xss'], module: 'escape-html' },
+        { name: 'encode', neutralizes: ['xss'], module: 'he' },
+        { name: 'basename', neutralizes: ['path-traversal'], module: 'path' },
+        { name: 'escape', neutralizes: ['xss'], module: 'validator' },
+    ],
+};
+/**
+ * Deterministic digest of a spec's full content. Key order is canonicalized
+ * (recursively sorted) so the version reflects CONTENT, not literal layout;
+ * array order is semantic (entry identity) and intentionally preserved.
+ */
+export function computeTaintModelVersion(spec) {
+    return createHash('sha256').update(canonicalJson(spec)).digest('hex').slice(0, 12);
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/** Version stamp of the built-in TS/JS model (joins the RepoMeta pdg key in U5). */
+export const taintModelVersion = computeTaintModelVersion(TS_JS_TAINT_MODEL);
+/**
+ * Register the built-in model for TypeScript and JavaScript. Explicit init
+ * seam for the U4 emit path (call before the pdg window consumes the
+ * registry); idempotent. Vue and other TS-adjacent language ids are
+ * deliberately NOT registered — the M3 scope is TS/JS only.
+ */
+export function registerBuiltinTaintModels() {
+    registerSourceSinkConfig(SupportedLanguages.TypeScript, TS_JS_TAINT_MODEL);
+    registerSourceSinkConfig(SupportedLanguages.JavaScript, TS_JS_TAINT_MODEL);
+}

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

@@ -65,6 +65,13 @@ export interface AnalyzeOptions {
     /** Per-function REACHING_DEF edge cap (#2082 M2). Forwarded to
      *  `PipelineOptions.pdgMaxReachingDefEdgesPerFunction`. */
     pdgMaxReachingDefEdgesPerFunction?: number;
+    /** Per-function taint findings cap (#2083 M3). Forwarded to
+     *  `PipelineOptions.pdgMaxTaintFindingsPerFunction`. No CLI flag or rc key
+     *  (KTD8) — programmatic / server path only, like the other pdg caps. */
+    pdgMaxTaintFindingsPerFunction?: number;
+    /** Per-finding taint hop cap (#2083 M3, KTD6). Forwarded to
+     *  `PipelineOptions.pdgMaxTaintHops`. No CLI flag or rc key (KTD8). */
+    pdgMaxTaintHops?: number;
     /**
      * Default branch threaded into generated AGENTS.md / CLAUDE.md so the
      * regression-compare example uses the configured branch instead of a
@@ -185,7 +192,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'>;
+type PdgOptions = Pick<AnalyzeOptions, 'pdg' | 'pdgMaxFunctionLines' | 'pdgMaxEdgesPerFunction' | 'pdgMaxReachingDefEdgesPerFunction' | 'pdgMaxTaintFindingsPerFunction' | 'pdgMaxTaintHops'>;
 export declare const resolvePdgConfig: (options: PdgOptions) => RepoMeta["pdg"];
 /**
  * Whether the requested `--pdg` configuration differs from the one the

package/dist/core/run-analyze.js

@@ -20,6 +20,8 @@ import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
 import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 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 { taintModelVersion } from './ingestion/taint/typescript-model.js';
 import { computeFileHashes, diffFileHashes } from '../storage/file-hash.js';
 import { extractChangedSubgraph, computeEffectiveWriteSet, } from './incremental/subgraph-extract.js';
 import { shadowCandidatesFor } from './incremental/shadow-candidates.js';
@@ -136,6 +138,16 @@ export const resolvePdgConfig = (options) => options.pdg === true
         maxEdgesPerFunction: options.pdgMaxEdgesPerFunction ?? DEFAULT_MAX_CFG_EDGES_PER_FUNCTION,
         maxReachingDefEdgesPerFunction: options.pdgMaxReachingDefEdgesPerFunction ??
             DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION,
+        // #2083 M3: taint caps + model identity. The key-union comparator in
+        // pdgModeMismatch picks these up structurally — an M2-era stamp lacks
+        // all three, so the first M3 run over an M2 `--pdg` index trips a full
+        // 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,
+        // 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.
+        taintModelVersion,
     }
     : undefined;
 /**
@@ -487,6 +499,8 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         pdgMaxFunctionLines: options.pdgMaxFunctionLines,
         pdgMaxEdgesPerFunction: options.pdgMaxEdgesPerFunction,
         pdgMaxReachingDefEdgesPerFunction: options.pdgMaxReachingDefEdgesPerFunction,
+        pdgMaxTaintFindingsPerFunction: options.pdgMaxTaintFindingsPerFunction,
+        pdgMaxTaintHops: options.pdgMaxTaintHops,
         fetchWrappers: options.fetchWrappers,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────

package/dist/mcp/local/local-backend.d.ts

@@ -424,6 +424,35 @@ export declare class LocalBackend {
      */
     private context;
     private _contextImpl;
+    /**
+     * Explain tool (#2083 M3 U6) — persisted taint-finding explanation.
+     * WAL-aware wrapper mirroring `context`.
+     */
+    private explain;
+    /**
+     * Taint findings are persisted as `TAINTED` rows in CodeRelation whose
+     * endpoints are BOTH BasicBlock nodes — the label anchor restricts every
+     * query here to the BasicBlock→BasicBlock partition of the rel table
+     * (which holds only the sparse, per-function-capped pdg layers), never a
+     * global symbol-space scan (the S1 verdict; LadybugDB has no rel-property
+     * index, so the label anchor IS the bound).
+     *
+     * Anchoring granularity:
+     * - file target → BasicBlock id prefix (`BasicBlock:<filePath>:` — the
+     *   shared `basicBlockId` template) with an exact-or-suffix path match so
+     *   `vuln.ts` finds `src/vuln.ts`.
+     * - symbol target → resolved via `resolveSymbolCandidates` (the context()
+     *   path: ambiguous ⇒ ranked candidates, unknown ⇒ not-found), then the
+     *   file id-prefix PLUS source-block startLine within the symbol's
+     *   [startLine, endLine] span. Findings are intra-procedural, so filtering
+     *   the SOURCE endpoint is sufficient — both endpoints share the function.
+     *   Symbols without a line span degrade to the file-level filter.
+     *
+     * The per-finding `sinkKind` and hop path decode from the persisted
+     * `reason` via the SHARED `taint/path-codec.ts` (the U4 write path encodes
+     * with the same module — `;<kind>` header + ordered `variable:line` hops).
+     */
+    private _explainImpl;
     /**
      * Legacy explore — kept for backwards compatibility with resources.ts.
      * Routes cluster/process types to direct graph queries.