gitnexus 1.6.8-rc.2 → 1.6.8-rc.21

package/dist/core/ingestion/cfg/reaching-defs.js

@@ -0,0 +1,364 @@
+/**
+ * Canonical `block:stmt` string key for a program point. Colon-separated to
+ * match the codebase's `blockIndex:stmtIndex` id conventions. Shared by the
+ * taint propagation engine (dedup/state keys) and the taint emit path
+ * (persisted edge-id material) so the two never drift.
+ */
+export function pointKey(p) {
+    return `${p.blockIndex}:${p.stmtIndex}`;
+}
+/**
+ * def-site key: packs (blockIndex, stmtIndex) into one number. The stride is
+ * a per-BLOCK statement bound, and `maxFunctionLines` caps LINES, not
+ * statements — a minified one-line function coalesces arbitrarily many
+ * statements into one block, so an overflow would silently alias
+ * (block b, stmt STRIDE+k) with (block b+1, stmt k) and fabricate wrong-block
+ * facts. computeReachingDefs therefore range-checks up front and bails to a
+ * sound empty `truncated` result instead of ever letting a key alias.
+ * 2^21 statements per block × blocks ≤ 2^32 stays inside Number's 2^53.
+ */
+const STMT_STRIDE = 1 << 21;
+const defKey = (blockIndex, stmtIndex) => blockIndex * STMT_STRIDE + stmtIndex;
+const EMPTY_LATTICE = new Map();
+/**
+ * Compute reaching definitions for one function. See the module doc for the
+ * purity/determinism/sharing contract.
+ */
+export function computeReachingDefs(cfg, limits) {
+    if (!cfg.bindings) {
+        return { status: 'no-facts', bindings: [], facts: [], defCount: 0, useCount: 0 };
+    }
+    const blocks = cfg.blocks;
+    const n = blocks.length;
+    // Key-aliasing guard (see STMT_STRIDE): a block with ≥ STRIDE statements
+    // cannot be keyed without aliasing into the next block's def sites, which
+    // would fabricate wrong-block facts — strictly worse than producing none.
+    // Bail to a sound empty `overflow` result (the emit path warns distinctly).
+    for (const b of blocks) {
+        if ((b.statements?.length ?? 0) >= STMT_STRIDE) {
+            return { status: 'overflow', bindings: cfg.bindings, facts: [], defCount: 0, useCount: 0 };
+        }
+    }
+    // ── adjacency (sorted for deterministic merges) ─────────────────────────
+    // A `throw` edge contributes IN(from) ∪ allDefs(from) to its handler, not
+    // OUT: an exception can fire BEFORE the block's defs complete (the seed def
+    // in `let x = seed(); try { x = risky(); } catch { sink(x) }` must reach the
+    // sink) AND between any two defs of a multi-def coalesced block (the parse
+    // def in `x = parse(a); x = normalize(x);` is live exactly when normalize
+    // throws — OUT's last-def-wins misses it). Sound over-approximation;
+    // monotone, so the fixpoint absorbs it. See mergePreds.
+    const preds = Array.from({ length: n }, () => []);
+    const succs = Array.from({ length: n }, () => []);
+    // Handlers whose IN depends on this block's IN (throw edges) — requeued on
+    // IN change, since a genned binding can absorb IN growth without changing
+    // OUT, which would otherwise leave the handler stale.
+    const throwSuccs = Array.from({ length: n }, () => []);
+    for (const e of cfg.edges) {
+        // Optional-chained pushes drop out-of-range endpoints defensively — the
+        // emit path validates via isEmitSafeCfg, but this pure function also runs
+        // on hand-built CFGs.
+        succs[e.from]?.push(e.to);
+        preds[e.to]?.push({ from: e.from, viaThrow: e.kind === 'throw' });
+        if (e.kind === 'throw')
+            throwSuccs[e.from]?.push(e.to);
+    }
+    for (const list of preds) {
+        list.sort((a, b) => a.from - b.from || Number(a.viaThrow) - Number(b.viaThrow));
+        // duplicate (from, throw+non-throw) pairs both survive — the throw leg
+        // adds IN(from); the merge dedups set-wise.
+    }
+    for (const list of succs)
+        list.sort((a, b) => a - b);
+    const gen = new Array(n).fill(null);
+    // allDefsGen[b]: bindingIdx → EVERY def-site key in the block (must + may).
+    // This is what a throw edge delivers to its handler: an exception can fire
+    // between any two statements, so every intermediate def may be the live one
+    // at the handler — IN∪OUT alone misses defs overwritten later in the same
+    // coalesced block (`try { x = parse(a); x = normalize(x); } catch { sink(x) }`
+    // — parse's value is exactly what sink sees when normalize throws).
+    const allDefsGen = new Array(n).fill(null);
+    const defLine = new Map(); // defKey → source line
+    let defCount = 0;
+    let useCount = 0;
+    for (const b of blocks) {
+        const stmts = b.statements;
+        if (!stmts || stmts.length === 0)
+            continue;
+        let g = null;
+        let all = null;
+        for (let i = 0; i < stmts.length; i++) {
+            const s = stmts[i];
+            useCount += s.uses.length;
+            const key = defKey(b.index, i);
+            const record = (d, kills) => {
+                defCount += 1;
+                defLine.set(key, s.line);
+                if (!g)
+                    g = new Map();
+                const entry = g.get(d);
+                if (kills || !entry) {
+                    g.set(d, { set: new Set([key]), kills: kills || (entry?.kills ?? false) });
+                }
+                else {
+                    entry.set.add(key); // may-def accumulates; never clears
+                }
+                if (!all)
+                    all = new Map();
+                const allSet = all.get(d);
+                if (allSet)
+                    allSet.add(key);
+                else
+                    all.set(d, new Set([key]));
+            };
+            if (s.mayDefs)
+                for (const d of s.mayDefs)
+                    record(d, false);
+            for (const d of s.defs)
+                record(d, true);
+        }
+        gen[b.index] = g;
+        allDefsGen[b.index] = all;
+    }
+    // ── iteration order: RPO over reachable blocks, then the rest by index ──
+    const order = reversePostOrder(cfg.entryIndex, succs, n);
+    // ── fixpoint ────────────────────────────────────────────────────────────
+    const inSets = new Array(n).fill(EMPTY_LATTICE);
+    const outSets = new Array(n).fill(EMPTY_LATTICE);
+    const inWorklist = new Array(n).fill(true);
+    let pending = n;
+    while (pending > 0) {
+        for (const b of order) {
+            if (!inWorklist[b])
+                continue;
+            inWorklist[b] = false;
+            pending -= 1;
+            const p = preds[b];
+            const inB = p.length === 0
+                ? EMPTY_LATTICE
+                : p.length === 1 && !p[0].viaThrow
+                    ? outSets[p[0].from] // alias — zero allocation on straight-line chains
+                    : mergePreds(p, inSets, outSets, allDefsGen);
+            const inChanged = !latticeEquals(inSets[b], inB);
+            inSets[b] = inB;
+            const g = gen[b];
+            // OUT = overlay(IN): a KILLING gen entry replaces the binding's set; a
+            // may-def-only entry unions with the incoming set (never kills). When
+            // nothing is genned, OUT aliases IN outright.
+            let outB;
+            if (!g) {
+                outB = inB;
+            }
+            else {
+                outB = new Map(inB); // copies REFERENCES, never set contents
+                for (const [bindingIdx, entry] of g) {
+                    if (entry.kills) {
+                        outB.set(bindingIdx, entry.set);
+                    }
+                    else {
+                        const incoming = inB.get(bindingIdx);
+                        outB.set(bindingIdx, incoming ? unionSets(incoming, entry.set) : entry.set);
+                    }
+                }
+            }
+            const requeue = (s) => {
+                if (!inWorklist[s]) {
+                    inWorklist[s] = true;
+                    pending += 1;
+                }
+            };
+            if (!latticeEquals(outSets[b], outB)) {
+                outSets[b] = outB;
+                for (const s of succs[b])
+                    requeue(s);
+            }
+            if (inChanged)
+                for (const s of throwSuccs[b])
+                    requeue(s);
+        }
+    }
+    // ── statement sweep: recover statement-granular def→use facts ───────────
+    const maxFacts = limits?.maxFacts && limits.maxFacts > 0 ? limits.maxFacts : Infinity;
+    const facts = [];
+    let truncated = false;
+    outer: for (const b of blocks) {
+        const stmts = b.statements;
+        if (!stmts || stmts.length === 0)
+            continue;
+        // Lazy overlay of IN — entries are replaced (never mutated) on def, so the
+        // shared sets stay intact.
+        let reach = null;
+        for (let i = 0; i < stmts.length; i++) {
+            const s = stmts[i];
+            // A use's binding that the SAME statement also defines could be a
+            // read-then-write (`x += 1` — sees prior defs) OR a write-then-read
+            // (`if ((m = re.exec(s)) && m[1])` — sees the same-statement def).
+            // StatementFacts carries no intra-statement order, so emit BOTH: prior
+            // defs ∪ the same-statement def. Sound over-approximation — the extra
+            // self-fact on compound assignments is harmless; missing the
+            // assign-and-test def→use (the most common JS idiom) would be a taint
+            // false negative. May-defs join the self-key set the same way.
+            const sameStmtDefs = s.defs.length > 0 || s.mayDefs?.length ? new Set([...s.defs, ...(s.mayDefs ?? [])]) : null;
+            for (const u of s.uses) {
+                const reaching = (reach ?? inSets[b.index]).get(u);
+                const selfKey = sameStmtDefs?.has(u) ? defKey(b.index, i) : undefined;
+                if (!reaching && selfKey === undefined)
+                    continue;
+                const keys = selfKey !== undefined && !reaching?.has(selfKey)
+                    ? [...(reaching ?? []), selfKey]
+                    : [...(reaching ?? [])];
+                for (const key of keys) {
+                    if (facts.length >= maxFacts) {
+                        truncated = true;
+                        break outer;
+                    }
+                    const defBlock = Math.floor(key / STMT_STRIDE);
+                    const defStmt = key % STMT_STRIDE;
+                    facts.push({
+                        bindingIdx: u,
+                        def: { blockIndex: defBlock, stmtIndex: defStmt, line: defLine.get(key) ?? s.line },
+                        use: { blockIndex: b.index, stmtIndex: i, line: s.line },
+                    });
+                }
+            }
+            if (s.mayDefs?.length) {
+                // Gen WITHOUT kill: the conditional def joins the binding's set.
+                if (!reach)
+                    reach = new Map(inSets[b.index]);
+                const key = defKey(b.index, i);
+                for (const d of s.mayDefs) {
+                    const prior = reach.get(d);
+                    reach.set(d, prior ? unionSets(prior, new Set([key])) : new Set([key]));
+                }
+            }
+            if (s.defs.length > 0) {
+                if (!reach)
+                    reach = new Map(inSets[b.index]);
+                for (const d of s.defs)
+                    reach.set(d, new Set([defKey(b.index, i)])); // kill + gen
+            }
+        }
+    }
+    facts.sort((a, b) => a.def.blockIndex - b.def.blockIndex ||
+        a.def.stmtIndex - b.def.stmtIndex ||
+        a.use.blockIndex - b.use.blockIndex ||
+        a.use.stmtIndex - b.use.stmtIndex ||
+        a.bindingIdx - b.bindingIdx);
+    return {
+        status: truncated ? 'truncated' : 'computed',
+        bindings: cfg.bindings,
+        facts,
+        defCount,
+        useCount,
+    };
+}
+/** RPO over blocks reachable from `entry`; unreachable blocks appended by index. */
+function reversePostOrder(entry, succs, n) {
+    const visited = new Array(n).fill(false);
+    const post = [];
+    // Iterative DFS with an explicit phase stack (children pushed in reverse so
+    // they pop in sorted order — determinism).
+    const stack = [{ node: entry, childIdx: 0 }];
+    visited[entry] = true;
+    while (stack.length) {
+        const top = stack[stack.length - 1];
+        const children = succs[top.node];
+        if (top.childIdx < children.length) {
+            const next = children[top.childIdx];
+            top.childIdx += 1;
+            if (!visited[next]) {
+                visited[next] = true;
+                stack.push({ node: next, childIdx: 0 });
+            }
+        }
+        else {
+            post.push(top.node);
+            stack.pop();
+        }
+    }
+    const order = post.reverse();
+    for (let b = 0; b < n; b++)
+        if (!visited[b])
+            order.push(b);
+    return order;
+}
+/**
+ * Union predecessor lattices, sharing sets where possible. A normal edge
+ * contributes OUT(from). A THROW edge contributes IN(from) ∪ allDefs(from):
+ * an exception may fire before, between, or after any of the block's defs, so
+ * the handler can observe the incoming state OR any intermediate def — OUT
+ * alone (last-def-wins) misses defs overwritten later in the same block.
+ * IN ∪ allDefs ⊇ OUT, so the throw contribution subsumes it.
+ */
+function mergePreds(preds, inSets, outSets, allDefsGen) {
+    const merged = new Map();
+    const mergeOne = (source) => {
+        for (const [bindingIdx, set] of source) {
+            const existing = merged.get(bindingIdx);
+            if (!existing) {
+                merged.set(bindingIdx, set); // share the first contributor's set
+            }
+            else if (existing !== set) {
+                // Union only when the references differ. Copy-on-extend: `existing`
+                // may be a shared set from another block — never mutate it.
+                let target = existing;
+                let copied = false;
+                for (const key of set) {
+                    if (!target.has(key)) {
+                        if (!copied) {
+                            target = new Set(existing);
+                            copied = true;
+                        }
+                        target.add(key);
+                    }
+                }
+                if (copied)
+                    merged.set(bindingIdx, target);
+            }
+        }
+    };
+    for (const p of preds) {
+        if (p.viaThrow) {
+            mergeOne(inSets[p.from]); // exception may fire pre-defs…
+            const all = allDefsGen[p.from];
+            if (all)
+                mergeOne(all); // …or after ANY of the block's defs
+        }
+        else {
+            mergeOne(outSets[p.from]);
+        }
+    }
+    return merged;
+}
+/** Order-stable union of two def-sets (shares `a` when `b` adds nothing). */
+function unionSets(a, b) {
+    let target = a;
+    let copied = false;
+    for (const key of b) {
+        if (!target.has(key)) {
+            if (!copied) {
+                target = new Set(a);
+                copied = true;
+            }
+            target.add(key);
+        }
+    }
+    return target;
+}
+/** Per-binding equality with a reference fast path (sets only ever grow). */
+function latticeEquals(a, b) {
+    if (a === b)
+        return true;
+    if (a.size !== b.size)
+        return false;
+    for (const [k, bSet] of b) {
+        const aSet = a.get(k);
+        if (aSet === bSet)
+            continue;
+        if (!aSet || aSet.size !== bSet.size)
+            return false;
+        for (const v of bSet)
+            if (!aSet.has(v))
+                return false;
+    }
+    return true;
+}

package/dist/core/ingestion/cfg/traversal-result.d.ts

@@ -0,0 +1,20 @@
+/**
+ * TraversalResult (issue #2081, M1).
+ *
+ * Visiting a statement (or a statement sequence) returns the block its control
+ * flow ENTERS through, plus the set of blocks whose **normal** control flows
+ * out the bottom (the "dangling exits") — to be wired to the entry of whatever
+ * comes next. Abnormal exits (return/break/continue/throw) are wired directly
+ * to their targets during the walk and are NOT part of `exits`.
+ *
+ * A statement that cannot fall through (e.g. ends in `return`/`throw`, or both
+ * branches of an `if` return) yields an empty `exits` array.
+ */
+export interface TraversalResult {
+    /** Block index control enters this statement/sequence through. */
+    readonly entry: number;
+    /** Block indices whose normal control falls out the bottom (may be empty). */
+    readonly exits: readonly number[];
+}
+/** A sequence of statements that produced no blocks (e.g. an empty body). */
+export declare const emptyTraversal: (entry: number) => TraversalResult;

package/dist/core/ingestion/cfg/traversal-result.js

@@ -0,0 +1,2 @@
+/** A sequence of statements that produced no blocks (e.g. an empty body). */
+export const emptyTraversal = (entry) => ({ entry, exits: [entry] });

package/dist/core/ingestion/cfg/types.d.ts

@@ -0,0 +1,231 @@
+/**
+ * CFG data model — plain, JSON-serializable types (issue #2081, M1).
+ *
+ * These cross the worker→main boundary and the disk-backed/durable ParsedFile
+ * store, so they must contain NO tree-sitter AST references, class instances,
+ * or anything that does not survive `JSON.stringify` → `JSON.parse`. Block and
+ * edge endpoints are referenced by integer index within a function's CFG.
+ *
+ * The per-language `CfgVisitor` (built in the parse worker, where the AST
+ * lives — see the M1 plan KTD1/KTD7) produces a `FunctionCfg` per function; the
+ * array of them is what rides on `ParsedFile.cfgSideChannel`.
+ */
+/**
+ * One distinct declared variable (binding) within a function (#2082 M2 U1).
+ *
+ * Statement facts reference bindings by integer index into
+ * {@link FunctionCfg.bindings} — names appear once per binding instead of once
+ * per occurrence (measured ~4× smaller serialized payload than named records).
+ * Distinct bindings of the same name (shadowing) get distinct entries, which is
+ * what keeps an inner `let x` from falsely killing the outer `x`'s definitions
+ * in the reaching-defs solver. NOTE: no field here may be named `nodeId` — the
+ * durable parsedfile-store reviver dedups objects keyed on that field name.
+ */
+export interface BindingEntry {
+    /** Source-level variable name (what the persisted edge's `reason` carries). */
+    readonly name: string;
+    /**
+     * 1-based line/0-based column of the canonical declaration site — `var`
+     * multi-declarations canonicalize to the FIRST declaration in source order.
+     * Both 0 for synthetic bindings.
+     */
+    readonly declLine: number;
+    readonly declColumn: number;
+    /** How the binding was introduced (param/catch matter to the M3 taint pass). */
+    readonly kind: 'var' | 'let' | 'const' | 'param' | 'catch' | 'function' | 'class' | 'module';
+    /**
+     * True when the name has no in-function declaration site (implicit global,
+     * import, or a variable captured from an enclosing function) — keyed
+     * `name@module` in edge ids instead of `name:line:col`.
+     */
+    readonly synthetic?: boolean;
+}
+/**
+ * One occurrence of a binding inside a call/new site's argument position
+ * (#2083 M3 U1). A bare `number` is a DIRECT occurrence (binding index into
+ * {@link FunctionCfg.bindings}); a `[bindingIdx, viaSiteIdx]` tuple marks an
+ * occurrence that reaches this argument THROUGH the nested site at
+ * `viaSiteIdx` (an index into the SAME statement's {@link StatementFacts.sites}
+ * array). The tag is load-bearing for sanitizer interposition (plan KTD4a):
+ * a flat per-arg binding set cannot distinguish `exec(escape(x))` (kill) from
+ * `exec(x)` (finding) — the single most common safe pattern would
+ * false-positive without it.
+ */
+export type SiteArgOccurrence = number | readonly [number, number];
+/**
+ * One call site, constructor call, or value-position member read harvested
+ * from a statement (#2083 M3 U1, plan KTD2). Worker-side substrate for the M3
+ * taint pass: the M2 facts carry no expression structure, and the main thread
+ * cannot re-parse (the #1983 OOM shape). Spec-AGNOSTIC — records structure
+ * only, never source/sink/sanitizer-ness (matching is a main-thread concern).
+ *
+ * Integer indices: binding fields (`receiver`/`object`/`resultDefs`/arg
+ * occurrences) index {@link FunctionCfg.bindings}; site references (`parent`,
+ * via-tags) index the OWNING statement's `sites` array. JSON-plain; NO field
+ * here may be named `nodeId` (durable parsedfile-store reviver hazard — see
+ * {@link BindingEntry}).
+ */
+export interface SiteRecord {
+    readonly kind: 'call' | 'new' | 'member-read';
+    /**
+     * Dotted callee path for call/new sites whose callee chain is rooted at an
+     * identifier/`this`/`super` (`child_process.exec`, `req.body.toString`).
+     * Optional chaining is normalized (`a?.b()` ⇒ `a.b`); string-literal
+     * subscripts fold into the path (`cp["exec"]` ⇒ `cp.exec`). Absent when the
+     * chain is not statically resolvable (dynamic key, call-rooted chain).
+     */
+    readonly callee?: string;
+    /**
+     * Binding index of the callee chain's ROOT identifier when the callee is a
+     * member chain (`userInput.trim()` ⇒ `userInput`). Method calls launder
+     * taint without it (plan KTD5 receiver-position TITO). Absent for bare
+     * calls (`exec(x)`) and non-identifier roots.
+     */
+    readonly receiver?: number;
+    /**
+     * Per-argument-position occurrence entries (trailing empty positions are
+     * trimmed; absent when no argument carries a binding occurrence). For
+     * `template: true` sites every substitution occurrence aggregates at
+     * position 0 (tagged templates have no positional argument list).
+     */
+    readonly args?: ReadonlyArray<readonly SiteArgOccurrence[]>;
+    /**
+     * Bindings defined by a declarator/assignment whose ENTIRE value (after
+     * unwrapping parens/`await`/`as`/`!`) is this call — `const b = escape(t)`
+     * ⇒ `[b]`. Per-declarator: `const a = t, b = escape(t)` attaches `[b]`
+     * only. Kill placement (KTD4b) keys on this: a sanitizer kills exactly the
+     * defs that receive its result directly.
+     */
+    readonly resultDefs?: readonly number[];
+    /**
+     * `[siteIdx, argIdx]` of the innermost enclosing call/new site argument
+     * position this site occurs in (`exec(escape(x))` ⇒ escape's parent is
+     * `[execSiteIdx, 0]`). Absent for top-level sites.
+     */
+    readonly parent?: readonly [number, number];
+    /**
+     * Index of the FIRST spread argument (`exec(...args)` ⇒ 0). Presence means
+     * position matching must degrade soundly (any sink position ≥ this index —
+     * plan KTD2/U2). A number (not boolean) because the matcher needs the index.
+     */
+    readonly spread?: number;
+    /** Tagged-template call (`sql\`…${id}\``) — argument positions are not positional. */
+    readonly template?: boolean;
+    /**
+     * String-literal first argument when the callee is bare `require` —
+     * CommonJS aliases resolve like ESM imports on the main thread (KTD7).
+     */
+    readonly requireArg?: string;
+    /** Member read: binding index of the object root (`req.body` ⇒ `req`). */
+    readonly object?: number;
+    /**
+     * Member read: property name (`req.body` ⇒ `'body'`; `req["body"]`
+     * included; dynamic `req[key]` is never recorded — documented KTD10 FN).
+     */
+    readonly property?: string;
+}
+/**
+ * Def/use facts for one harvested statement (or construct header), in
+ * execution order within its block (#2082 M2 U1). `defs`/`uses` are indices
+ * into {@link FunctionCfg.bindings}. A compound assignment / update expression
+ * lists its binding in BOTH. Self-describing — `line` is carried here, never
+ * inferred from the block's text fragments (facts-only records exist, e.g.
+ * params on ENTRY and catch params).
+ *
+ * `mayDefs` (tri-review P1): defs harvested inside CONDITIONALLY-EVALUATED
+ * subexpressions — short-circuit right operands (`a && (x = v)`,
+ * `c ?? (c = load())`), ternary arms, logical-assignment operators, and
+ * switch case-test expressions. The solver treats them as GEN WITHOUT KILL:
+ * treating them as must-defs would falsely kill the prior def on the
+ * not-taken path (a taint false negative on core JS idioms). Optional —
+ * absent means none.
+ *
+ * `sites` (#2083 M3 U1): call/member-read structure for the taint pass —
+ * see {@link SiteRecord}. Optional and omit-when-empty; absent on pre-M3
+ * channels and on statements with no calls or member reads. Sites inside
+ * nested functions are NOT recorded (consistent with def/use invisibility —
+ * the enclosing `arr.forEach(...)` call IS, with receiver `arr`).
+ */
+export interface StatementFacts {
+    readonly line: number;
+    readonly defs: readonly number[];
+    readonly uses: readonly number[];
+    readonly mayDefs?: readonly number[];
+    readonly sites?: readonly SiteRecord[];
+}
+/** A basic block: a maximal straight-line run of statements between leaders. */
+export interface BasicBlockData {
+    /** Block index within its function. The synthetic ENTRY is always 0. */
+    readonly index: number;
+    readonly startLine: number;
+    readonly endLine: number;
+    /** Source snippet for the block (empty for synthetic ENTRY/EXIT). */
+    readonly text: string;
+    readonly kind: 'entry' | 'exit' | 'normal';
+    /**
+     * Per-statement def/use facts in execution order (#2082 M2 U1). Present only
+     * when the producing visitor harvests (TS/JS under `--pdg`); absent on
+     * hand-built or pre-M2 CFGs — the reaching-defs solver reports `no-facts`.
+     */
+    readonly statements?: readonly StatementFacts[];
+}
+/**
+ * Why one block flows to another — drives the `reason` on the emitted CFG edge.
+ *
+ * Kind invariant (M2): a bare jump kind (`return`/`break`/`continue`) means the
+ * SOURCE block's terminator is that jump statement. A `finally-*` kind marks a
+ * COMPLETION edge out of a `finally` body's exit — the leg that resumes a jump
+ * which was re-routed through the finally (issue #2082 U2). Reusing the bare
+ * kinds on completion edges would silently break consumers that infer the
+ * source block's terminator from the kind, and a single generic kind would lose
+ * WHICH jump each completion edge completes when a shared finally has several
+ * pending targets.
+ */
+export type CfgEdgeKind = 'seq' | 'cond-true' | 'cond-false' | 'loop-back' | 'break' | 'continue' | 'return' | 'throw' | 'switch-case' | 'fallthrough' | 'finally-return' | 'finally-break' | 'finally-continue';
+export interface CfgEdgeData {
+    readonly from: number;
+    readonly to: number;
+    readonly kind: CfgEdgeKind;
+}
+/** One function's control-flow graph. `cfgSideChannel` is `readonly FunctionCfg[]`. */
+export interface FunctionCfg {
+    readonly filePath: string;
+    /** Source span of the owning function — anchors the BasicBlock node ids. */
+    readonly functionStartLine: number;
+    readonly functionEndLine: number;
+    /**
+     * Start COLUMN of the owning function. Combined with `functionStartLine` it
+     * disambiguates the BasicBlock node ids when two functions share a start line
+     * — e.g. `{ a: () => x(), b: () => y() }`, where both arrows begin on the same
+     * line and each restarts its block indices at 0. Without the column the ids
+     * collide and the graph's first-writer-wins `addNode` silently drops the
+     * second function's blocks and cross-wires its edges.
+     */
+    readonly functionStartColumn: number;
+    readonly entryIndex: number;
+    readonly exitIndex: number;
+    readonly blocks: readonly BasicBlockData[];
+    readonly edges: readonly CfgEdgeData[];
+    /**
+     * The function's binding table (#2082 M2 U1) — referenced by index from
+     * {@link BasicBlockData.statements}. Present iff statement facts are.
+     */
+    readonly bindings?: readonly BindingEntry[];
+}
+/**
+ * Per-language CFG strategy. Invoked **in the parse worker** for each function
+ * node. `TNode` is the language's AST node type (tree-sitter `SyntaxNode` for
+ * TS/JS) — kept generic so this module stays AST-library-agnostic. Returns
+ * `undefined` when the node is not a CFG-bearing function (the caller skips it).
+ */
+export interface CfgVisitor<TNode = unknown> {
+    buildFunctionCfg(fnNode: TNode, filePath: string): FunctionCfg | undefined;
+    /**
+     * Whether `node` is a CFG-bearing function this visitor handles. Lets the
+     * worker enumerate functions (and apply the per-function line budget) by a
+     * cheap node-type test, instead of attempting to build a CFG for every AST
+     * node. `buildFunctionCfg` still re-checks, so this is purely an optimization
+     * + the seam the line-budget hooks into.
+     */
+    isFunction(node: TNode): boolean;
+}

package/dist/core/ingestion/cfg/types.js

@@ -0,0 +1,13 @@
+/**
+ * CFG data model — plain, JSON-serializable types (issue #2081, M1).
+ *
+ * These cross the worker→main boundary and the disk-backed/durable ParsedFile
+ * store, so they must contain NO tree-sitter AST references, class instances,
+ * or anything that does not survive `JSON.stringify` → `JSON.parse`. Block and
+ * edge endpoints are referenced by integer index within a function's CFG.
+ *
+ * The per-language `CfgVisitor` (built in the parse worker, where the AST
+ * lives — see the M1 plan KTD1/KTD7) produces a `FunctionCfg` per function; the
+ * array of them is what rides on `ParsedFile.cfgSideChannel`.
+ */
+export {};