gitnexus 1.6.8-rc.2 → 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/ingestion/utils/method-props.js

@@ -184,6 +184,7 @@ export function buildMethodProps(info) {
         ...(info.isAsync ? { isAsync: info.isAsync } : {}),
         ...(info.isPartial ? { isPartial: info.isPartial } : {}),
         ...(info.isConst ? { isConst: info.isConst } : {}),
+        ...(info.isDeleted ? { isDeleted: info.isDeleted } : {}),
         ...(info.annotations.length > 0 ? { annotations: info.annotations } : {}),
     };
 }

package/dist/core/ingestion/workers/clone-safety.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Structured-clone safety for the worker result boundary (#2112).
+ *
+ * A parse worker delivers its accumulated result to the main thread via
+ * `parentPort.postMessage(...)`. Node serializes that payload with the
+ * structured-clone algorithm SYNCHRONOUSLY on the worker thread, and it
+ * THROWS a `DataCloneError` the instant it meets a value it can't serialize —
+ * a function, a symbol, a Promise, a WeakMap, etc. The reporter of #2112 hit
+ * exactly this: a node record whose `properties` carried an own-enumerable
+ * value pointing at a native function (`function toString() { [native code] }
+ * could not be cloned`). One such value aborted the entire parse phase,
+ * because the worker re-posts the throw as `{type:'error'}` which the pool
+ * counts as a worker death — and under `GITNEXUS_WORKER_POOL_SIZE=1` the same
+ * graph re-throws on every respawn until the slot's budget is exhausted.
+ *
+ * This module is the safety net. It runs ONLY after a real clone failure on
+ * the fast-path post (zero overhead on healthy runs), and rewrites the
+ * boundary-crossing arrays so the result becomes cloneable: a non-cloneable
+ * value inside a plain extraction record is dropped (the record is otherwise
+ * kept — strictly-missing data, never wrong), and a `ParsedFile` that can't be
+ * made cloneable is dropped whole so scope-resolution re-derives it on the
+ * main thread (where there is no clone boundary) with intact edge data.
+ *
+ * Language-neutral by construction: it keys on value shape and field name
+ * only, never on a language (AGENTS.md shared-pipeline rule). The strip
+ * semantics mirror what the store path's `JSON.stringify` already silently
+ * drops, so store / no-store / cold / warm runs converge on the same graph.
+ */
+/** A file whose parse result was sanitized or dropped at the clone boundary. */
+export interface SkippedPath {
+    /** Best-effort source path of the offending record (or `(unknown)`). */
+    path: string;
+    /** Human-readable reason, e.g. "dropped 1 non-serializable value from nodes". */
+    reason: string;
+}
+/**
+ * True iff `value` survives Node's structured-clone algorithm (the same
+ * algorithm `postMessage` uses). This is the authoritative probe — it matches
+ * the real failure exactly, including Map/Set/Date/RegExp/TypedArray support,
+ * so it never false-positives on the `Scope` Maps that clone fine.
+ */
+export declare function isStructuredCloneable(value: unknown): boolean;
+/** The leaf values the structured-clone algorithm copies verbatim. */
+type CloneablePrimitive = undefined | null | boolean | number | bigint | string;
+/**
+ * Maps `T` to itself when every value reachable from it is structured-clone
+ * safe, and to a type containing `never` at the first offending property
+ * otherwise. A function or symbol — the values `postMessage` rejects — becomes
+ * `never`, so a struct carrying one is no longer assignable to its own
+ * `Cloneable<T>` and `assertCloneable` rejects it, naming the bad key.
+ *
+ * Implemented as a homomorphic mapped type (`{ [K in keyof T]: … }`) so it
+ * preserves `interface` shapes and `readonly` modifiers and works WITHOUT
+ * requiring the payload types to carry an index signature — sidestepping the
+ * "closed interface is not assignable to a recursive index-signature type" wall
+ * that blocked the value-typed-`Cloneable` approach (#2143). `Map`/`Set`/array
+ * containers recurse into their element types; `Date`/`RegExp` are clone-safe
+ * leaves.
+ */
+/** True iff `T` is `any` (the canonical `IsAny` probe: only `any` satisfies `0 extends 1 & T`). */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+export type Cloneable<T> = IsAny<T> extends true ? never : T extends CloneablePrimitive | Date | RegExp ? T : T extends (...args: never[]) => unknown ? never : T extends symbol ? never : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<Cloneable<K>, Cloneable<V>> : T extends ReadonlySet<infer U> ? ReadonlySet<Cloneable<U>> : T extends readonly (infer U)[] ? T extends unknown[] ? Cloneable<U>[] : readonly Cloneable<U>[] : T extends object ? {
+    [K in keyof T]: Cloneable<T[K]>;
+} : never;
+/**
+ * Identity at runtime (zero cost — returns its argument unchanged); a
+ * compile-time assertion that `value` is structured-clone safe. Wrap a
+ * producer that feeds an `unknown` worker-result sink:
+ *
+ *   collectCaptureSideChannel: (filePath) => assertCloneable(collectFoo(filePath))
+ *
+ * If `collectFoo`'s return type ever gains a non-cloneable member (a function, a
+ * `SyntaxNode`, …) the call fails to compile, pointing at the offending key.
+ *
+ * The parameter is a conditional type rather than an `extends Cloneable<T>`
+ * constraint because a self-referential constraint (`T extends Cloneable<T>`)
+ * is a "circular constraint" error in TypeScript. For a clone-safe `T` the
+ * parameter resolves to `T` (call type-checks as a plain identity); for an
+ * unsafe `T` it resolves to `Cloneable<T>` (which has `never` at the bad key),
+ * so the argument is rejected.
+ */
+export declare function assertCloneable<T>(value: T extends Cloneable<T> ? T : Cloneable<T>): T;
+export interface MakeCloneSafeOptions {
+    /**
+     * Array field names whose offending elements are DROPPED whole rather than
+     * stripped in place (e.g. `parsedFiles` — its `captureSideChannel` drives
+     * edge resolution, so a stripped-and-delivered file would ship WRONG edges;
+     * dropping it lets scope-resolution re-derive it on the main thread).
+     */
+    dropWholeElement: ReadonlySet<string>;
+    /** Field names to skip entirely (e.g. the `skippedPaths` field itself). */
+    skipFields?: ReadonlySet<string>;
+    /** Keys to probe for a file path when attributing a skip. */
+    pathKeys?: readonly string[];
+}
+/**
+ * Make a worker result's boundary-crossing array fields structured-cloneable,
+ * mutating `result` in place. Only arrays that actually contain a
+ * non-cloneable value are rewritten; everything else keeps referential
+ * identity. Returns the list of affected file paths for reporting.
+ *
+ * Call this after ANY failure of the fast-path post — a `DataCloneError`, OR a
+ * throwing getter's own error surfaced by structuredClone (the caller in
+ * `post-result.ts` recovers on any throw, not only `DataCloneError`).
+ */
+export declare function makeWorkerResultCloneSafe(result: Record<string, unknown>, options: MakeCloneSafeOptions): {
+    skipped: SkippedPath[];
+};
+export {};