gitnexus 1.6.8-rc.12 → 1.6.8-rc.14

package/dist/_shared/scope-resolution/parsed-file.d.ts

@@ -96,5 +96,26 @@ export interface ParsedFile {
      * side effects — the contract default) leave this undefined.
      */
     readonly captureSideChannel?: unknown;
+    /**
+     * Per-function control-flow graphs for this file (#2081 M1, PDG/taint
+     * substrate). A DISTINCT field from {@link captureSideChannel} — different
+     * producer, consumer, and lifecycle: the worker builds it from the
+     * tree-sitter AST via `LanguageProvider.cfgVisitor` (only on a `--pdg` run),
+     * and scope-resolution emits BasicBlock nodes + CFG edges from it while the
+     * disk-backed ParsedFile store is still live (it is NOT a capture-time
+     * marker the resolver restores into module maps). Kept separate so a future
+     * change to either channel's shape invalidates independently.
+     *
+     * Shared / ingestion code treats this as opaque (`unknown`) per AGENTS.md.
+     * Concretely it is a `readonly FunctionCfg[]` (see
+     * `core/ingestion/cfg/types.ts`) — plain JSON-serializable data (no AST
+     * refs, no class instances) so it round-trips through the parse cache and
+     * the `parsedfile-store` (whose interning reviver keys on `nodeId`, which
+     * these blocks/edges deliberately lack).
+     *
+     * Optional: `undefined` on non-`--pdg` runs and for languages with no
+     * `cfgVisitor` — the default for every run today.
+     */
+    readonly cfgSideChannel?: unknown;
 }
 //# sourceMappingURL=parsed-file.d.ts.map

package/dist/_shared/scope-resolution/parsed-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parsed-file.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/parsed-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC"}
+{"version":3,"file":"parsed-file.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/parsed-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAChD,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC"}

package/dist/cli/analyze-config.js

@@ -63,6 +63,7 @@ const KEY_SPECS = {
     skipContextFiles: { target: 'skipAgentsMd', kind: 'boolean' },
     skipAiContext: { target: 'skipAgentsMd', kind: 'boolean' },
     skipSkills: { target: 'skipSkills', kind: 'boolean' },
+    pdg: { target: 'pdg', kind: 'boolean' },
     indexOnly: { target: 'indexOnly', kind: 'boolean' },
     stats: { target: 'stats', kind: 'boolean' },
     noStats: { target: 'stats', kind: 'boolean-negate' },

package/dist/cli/analyze.d.ts

@@ -37,6 +37,12 @@ export interface AnalyzeOptions {
     verbose?: boolean;
     /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */
     skipAgentsMd?: boolean;
+    /**
+     * Build the control-flow-graph / PDG substrate (#2081 M1). Opt-in; off by
+     * default. Threaded to both the worker (CFG build) and scope-resolution
+     * (BasicBlock/CFG emit).
+     */
+    pdg?: boolean;
     /**
      * Stats inclusion in AGENTS.md and CLAUDE.md.
      *

package/dist/cli/analyze.js

@@ -841,6 +841,8 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
             skipGit: options.skipGit,
             skipAgentsMd,
             skipSkills,
+            // CFG/PDG substrate opt-in (#2081 M1) — threaded to both sinks downstream.
+            pdg: options.pdg === true,
             // Resolved default branch (CLI > .gitnexusrc > auto-detect > "main")
             // threaded into the generated regression-compare example (#243).
             defaultBranch: resolvedDefaultBranch,

package/dist/cli/index.js

@@ -32,6 +32,8 @@ program
     .option('--skills', 'Generate repo-specific skill files from detected communities ' +
     '(no-op when --index-only is also set).')
     .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
+    .option('--pdg', 'Build the control-flow-graph / PDG substrate (BasicBlock nodes + CFG edges) ' +
+    'for supported languages. Opt-in; off by default. (#2081 M1)')
     .option('--default-branch <branch>', 'Default branch used in the generated regression-compare example (base_ref). ' +
     'Falls back to .gitnexusrc, then auto-detected origin/HEAD, then "main".')
     .option('--branch <name>', 'Index the working tree under a specific branch slot (multi-branch indexing). ' +

package/dist/core/ingestion/cfg/cfg-builder.d.ts

@@ -0,0 +1,51 @@
+/**
+ * CfgBuilder (issue #2081, M1) — the language-agnostic accumulator.
+ *
+ * A per-language `CfgVisitor` drives this: it creates blocks as it walks
+ * statements, wires edges (including back-edges and break/continue/return/throw
+ * targets resolved via {@link ControlFlowContext}), and calls {@link finish} to
+ * produce the serializable {@link FunctionCfg}. The builder owns the synthetic
+ * ENTRY (index 0) and EXIT blocks and de-duplicates identical edges so repeated
+ * `connect` calls (common when wiring a set of dangling exits) stay idempotent.
+ *
+ * It has no knowledge of any AST — it is exercised directly in unit tests with
+ * hand-built block sequences, which is how the classic CFG hazards are pinned
+ * before the tree-sitter visitor (U2) drives it.
+ */
+import type { BasicBlockData, CfgEdgeKind, FunctionCfg } from './types.js';
+export declare class CfgBuilder {
+    private readonly filePath;
+    private readonly functionStartLine;
+    private readonly functionEndLine;
+    /** Start column of the owning function — disambiguates same-line functions
+     *  in the BasicBlock ids (see {@link FunctionCfg.functionStartColumn}).
+     *  Defaults to 0 for hand-built test CFGs that don't model columns. */
+    private readonly functionStartColumn;
+    private readonly blocks;
+    private readonly edges;
+    private readonly edgeKeys;
+    readonly entryIndex: number;
+    readonly exitIndex: number;
+    constructor(filePath: string, functionStartLine: number, functionEndLine: number, 
+    /** Start column of the owning function — disambiguates same-line functions
+     *  in the BasicBlock ids (see {@link FunctionCfg.functionStartColumn}).
+     *  Defaults to 0 for hand-built test CFGs that don't model columns. */
+    functionStartColumn?: number);
+    /** Create a block and return its index. */
+    newBlock(startLine: number, endLine: number, text: string, kind?: BasicBlockData['kind']): number;
+    /** Add a single edge (idempotent on from+to+kind). */
+    edge(from: number, to: number, kind: CfgEdgeKind): void;
+    /** Wire a set of dangling exits to a single target block with one kind. */
+    connect(exits: readonly number[], to: number, kind?: CfgEdgeKind): void;
+    /** Extend a block's end line as more statements accrue to it. */
+    extendBlock(index: number, endLine: number, appendText?: string): void;
+    get blockCount(): number;
+    /** Produce the serializable CFG. Caller is responsible for having wired the
+     *  function's dangling exits to {@link exitIndex} before calling. */
+    finish(): FunctionCfg;
+}
+/**
+ * Block indices reachable from `entryIndex` by following edges. Backs the
+ * reachability property tests (R9) over hand-built and visitor-produced CFGs.
+ */
+export declare const reachableBlocks: (cfg: FunctionCfg) => Set<number>;

package/dist/core/ingestion/cfg/cfg-builder.js

@@ -0,0 +1,100 @@
+export class CfgBuilder {
+    filePath;
+    functionStartLine;
+    functionEndLine;
+    functionStartColumn;
+    blocks = [];
+    edges = [];
+    edgeKeys = new Set();
+    entryIndex;
+    exitIndex;
+    constructor(filePath, functionStartLine, functionEndLine, 
+    /** Start column of the owning function — disambiguates same-line functions
+     *  in the BasicBlock ids (see {@link FunctionCfg.functionStartColumn}).
+     *  Defaults to 0 for hand-built test CFGs that don't model columns. */
+    functionStartColumn = 0) {
+        this.filePath = filePath;
+        this.functionStartLine = functionStartLine;
+        this.functionEndLine = functionEndLine;
+        this.functionStartColumn = functionStartColumn;
+        this.entryIndex = this.newBlock(functionStartLine, functionStartLine, '', 'entry');
+        this.exitIndex = this.newBlock(functionEndLine, functionEndLine, '', 'exit');
+    }
+    /** Create a block and return its index. */
+    newBlock(startLine, endLine, text, kind = 'normal') {
+        this.blocks.push({ startLine, endLine, textParts: text ? [text] : [], kind });
+        return this.blocks.length - 1;
+    }
+    /** Add a single edge (idempotent on from+to+kind). */
+    edge(from, to, kind) {
+        const key = `${from}->${to}:${kind}`;
+        if (this.edgeKeys.has(key))
+            return;
+        this.edgeKeys.add(key);
+        this.edges.push({ from, to, kind });
+    }
+    /** Wire a set of dangling exits to a single target block with one kind. */
+    connect(exits, to, kind = 'seq') {
+        for (const from of exits)
+            this.edge(from, to, kind);
+    }
+    /** Extend a block's end line as more statements accrue to it. */
+    extendBlock(index, endLine, appendText) {
+        const b = this.blocks[index];
+        if (!b)
+            return;
+        if (endLine > b.endLine)
+            b.endLine = endLine;
+        if (appendText)
+            b.textParts.push(appendText);
+    }
+    get blockCount() {
+        return this.blocks.length;
+    }
+    /** Produce the serializable CFG. Caller is responsible for having wired the
+     *  function's dangling exits to {@link exitIndex} before calling. */
+    finish() {
+        return {
+            filePath: this.filePath,
+            functionStartLine: this.functionStartLine,
+            functionEndLine: this.functionEndLine,
+            functionStartColumn: this.functionStartColumn,
+            entryIndex: this.entryIndex,
+            exitIndex: this.exitIndex,
+            blocks: this.blocks.map((b, index) => ({
+                index,
+                startLine: b.startLine,
+                endLine: b.endLine,
+                text: b.textParts.join('\n'),
+                kind: b.kind,
+            })),
+            edges: [...this.edges],
+        };
+    }
+}
+/**
+ * Block indices reachable from `entryIndex` by following edges. Backs the
+ * reachability property tests (R9) over hand-built and visitor-produced CFGs.
+ */
+export const reachableBlocks = (cfg) => {
+    const adj = new Map();
+    for (const e of cfg.edges) {
+        const list = adj.get(e.from);
+        if (list)
+            list.push(e.to);
+        else
+            adj.set(e.from, [e.to]);
+    }
+    const seen = new Set([cfg.entryIndex]);
+    const stack = [cfg.entryIndex];
+    while (stack.length) {
+        const n = stack.pop();
+        for (const next of adj.get(n) ?? []) {
+            if (!seen.has(next)) {
+                seen.add(next);
+                stack.push(next);
+            }
+        }
+    }
+    return seen;
+};

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

@@ -0,0 +1,30 @@
+/**
+ * collectFunctionCfgs (issue #2081, M1).
+ *
+ * Walks a parsed file's tree-sitter tree and builds one {@link FunctionCfg} per
+ * CFG-bearing function via the language's {@link CfgVisitor}. Runs IN THE PARSE
+ * WORKER (where the AST lives — KTD1/KTD7); the result rides on
+ * `ParsedFile.cfgSideChannel` across the worker→main boundary.
+ *
+ * Nested functions are enumerated independently — each gets its own CFG, and
+ * appears as an opaque straight-line block in its enclosing function's CFG (the
+ * visitor does not descend into nested function bodies). `maxFunctionLines`
+ * bounds per-function cost: a function whose source span exceeds the cap is
+ * skipped (and counted) rather than walked, so a pathological mega-function
+ * cannot blow up worker time/memory. A cap of `0` means no limit.
+ */
+import type { SyntaxNode } from '../utils/ast-helpers.js';
+import type { CfgVisitor, FunctionCfg } from './types.js';
+/**
+ * Default per-function source-line cap used by the worker when the `--pdg` run
+ * does not specify `pdgMaxFunctionLines`. A function longer than this (almost
+ * always minified/generated code) is skipped rather than walked — its CFG is
+ * both expensive and low-value. Overridable via `PipelineOptions.pdgMaxFunctionLines`.
+ */
+export declare const DEFAULT_PDG_MAX_FUNCTION_LINES = 2000;
+export interface CollectedCfgs {
+    readonly cfgs: readonly FunctionCfg[];
+    /** Functions skipped for exceeding `maxFunctionLines` (0 ⇒ none skipped). */
+    readonly skipped: number;
+}
+export declare function collectFunctionCfgs(root: SyntaxNode, visitor: CfgVisitor<SyntaxNode>, filePath: string, maxFunctionLines?: number): CollectedCfgs;

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

@@ -0,0 +1,34 @@
+/**
+ * Default per-function source-line cap used by the worker when the `--pdg` run
+ * does not specify `pdgMaxFunctionLines`. A function longer than this (almost
+ * always minified/generated code) is skipped rather than walked — its CFG is
+ * both expensive and low-value. Overridable via `PipelineOptions.pdgMaxFunctionLines`.
+ */
+export const DEFAULT_PDG_MAX_FUNCTION_LINES = 2000;
+export function collectFunctionCfgs(root, visitor, filePath, maxFunctionLines = 0) {
+    const cfgs = [];
+    let skipped = 0;
+    const stack = [root];
+    while (stack.length) {
+        const node = stack.pop();
+        if (visitor.isFunction(node)) {
+            const lines = node.endPosition.row - node.startPosition.row + 1;
+            if (maxFunctionLines > 0 && lines > maxFunctionLines) {
+                skipped++;
+            }
+            else {
+                const cfg = visitor.buildFunctionCfg(node, filePath);
+                if (cfg)
+                    cfgs.push(cfg);
+            }
+        }
+        // Descend regardless (a skipped mega-function may still contain small
+        // nested functions that are worth a CFG of their own).
+        for (let i = node.namedChildCount - 1; i >= 0; i--) {
+            const child = node.namedChild(i);
+            if (child)
+                stack.push(child);
+        }
+    }
+    return { cfgs, skipped };
+}

package/dist/core/ingestion/cfg/control-flow-context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ControlFlowContext (issue #2081, M1).
+ *
+ * Resolves the targets of `break`/`continue` (plain and labeled) as the visitor
+ * descends through loops and switches. Loops and switches push a target frame
+ * on entry and pop it on exit; a labeled statement attaches its label to the
+ * frame of the construct it labels, so `break outer` / `continue outer` resolve
+ * against the right enclosing loop/switch rather than the nearest one.
+ */
+export declare class ControlFlowContext {
+    private readonly stack;
+    pushLoop(continueTo: number, breakTo: number, label?: string): void;
+    pushSwitch(breakTo: number, label?: string): void;
+    pop(): void;
+    /**
+     * Target block for a `break`. With a label, the nearest enclosing frame
+     * carrying that label (loop or switch); without, the nearest frame of any
+     * kind. Returns `undefined` if there is no valid target (malformed input).
+     */
+    breakTarget(label?: string): number | undefined;
+    /**
+     * Target block for a `continue`. With a label, the nearest enclosing **loop**
+     * carrying that label; without, the nearest loop (switches are skipped — you
+     * cannot `continue` a switch). Returns `undefined` if there is no valid loop.
+     */
+    continueTarget(label?: string): number | undefined;
+}

package/dist/core/ingestion/cfg/control-flow-context.js

@@ -0,0 +1,49 @@
+/**
+ * ControlFlowContext (issue #2081, M1).
+ *
+ * Resolves the targets of `break`/`continue` (plain and labeled) as the visitor
+ * descends through loops and switches. Loops and switches push a target frame
+ * on entry and pop it on exit; a labeled statement attaches its label to the
+ * frame of the construct it labels, so `break outer` / `continue outer` resolve
+ * against the right enclosing loop/switch rather than the nearest one.
+ */
+export class ControlFlowContext {
+    stack = [];
+    pushLoop(continueTo, breakTo, label) {
+        this.stack.push({ kind: 'loop', continueTo, breakTo, label });
+    }
+    pushSwitch(breakTo, label) {
+        this.stack.push({ kind: 'switch', breakTo, label });
+    }
+    pop() {
+        this.stack.pop();
+    }
+    /**
+     * Target block for a `break`. With a label, the nearest enclosing frame
+     * carrying that label (loop or switch); without, the nearest frame of any
+     * kind. Returns `undefined` if there is no valid target (malformed input).
+     */
+    breakTarget(label) {
+        for (let i = this.stack.length - 1; i >= 0; i--) {
+            const f = this.stack[i];
+            if (label === undefined || f.label === label)
+                return f.breakTo;
+        }
+        return undefined;
+    }
+    /**
+     * Target block for a `continue`. With a label, the nearest enclosing **loop**
+     * carrying that label; without, the nearest loop (switches are skipped — you
+     * cannot `continue` a switch). Returns `undefined` if there is no valid loop.
+     */
+    continueTarget(label) {
+        for (let i = this.stack.length - 1; i >= 0; i--) {
+            const f = this.stack[i];
+            if (f.kind !== 'loop')
+                continue;
+            if (label === undefined || f.label === label)
+                return f.continueTo;
+        }
+        return undefined;
+    }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * cfg/emit.ts (issue #2081, M1) — serialized side-channel → graph.
+ *
+ * Pure helper: given a file's per-function CFGs (off `ParsedFile.cfgSideChannel`,
+ * produced by the worker in U3), emit one persisted `BasicBlock` node per block
+ * and one `CFG` edge per edge into the {@link KnowledgeGraph}. Invoked from
+ * scope-resolution (run.ts Phase 4) while the disk-backed ParsedFile store is
+ * still live — the only window where the worker-built CFGs are loaded (KTD1/
+ * KTD5). Default (`--pdg` off) runs never call this, so the emitted graph stays
+ * byte-identical to a pre-#2081 run.
+ *
+ * BasicBlock id: `BasicBlock:<filePath>:<functionStartLine>:<functionStartColumn>:<blockIndex>`
+ * (KTD3). The function start line+column segments disambiguate blocks across
+ * multiple functions in one file — including same-line functions — since each
+ * function's block indices restart at 0; blocks carry no `name` (the
+ * BasicBlock table has no such column). The edge KIND
+ * (`seq`/`cond-true`/…) rides in the relationship `reason` — CFG edges are
+ * values of the single `CodeRelation` table's `type` column (`'CFG'`), so the
+ * kind cannot be its own edge type and is queried via `reason`.
+ */
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { FunctionCfg } from './types.js';
+/**
+ * Default per-function CFG edge cap. A pathological generated function could
+ * otherwise emit an unbounded edge set; the cap bounds graph growth and is
+ * overridable via `--pdg` options. `0` (in options) means no cap (unlimited
+ * — see the `cap` mapping in {@link emitFileCfgs}); `undefined` means this
+ * default.
+ */
+export declare const DEFAULT_MAX_CFG_EDGES_PER_FUNCTION = 5000;
+export interface CfgEmitResult {
+    blocks: number;
+    edges: number;
+    /** Edges dropped because a function's edge count exceeded the cap. */
+    droppedEdges: number;
+    /** Number of functions that hit the cap. */
+    cappedFunctions: number;
+}
+/**
+ * Whether an untrusted `cfgSideChannel` element is safe to feed to
+ * {@link emitFileCfgs}. Deliberately NOT full FunctionCfg validation — it
+ * checks exactly the fields whose corruption is SILENT given emit's
+ * mechanics: {@link basicBlockId} string-templates every id-anchor value
+ * (filePath, function start line/column, block index, edge endpoints) and
+ * the graph's addNode/addRelationship are no-throw Map inserts. Unchecked,
+ * a missing anchor field cross-wires same-`undefined`-id blocks across
+ * functions (addNode is first-writer-wins), and an edge endpoint that
+ * matches no block index becomes a dangling `BasicBlock:…:<n>` edge that
+ * detonates much later at DB bulk-load instead of throwing here — so
+ * endpoints are checked for MEMBERSHIP in the block-index set, not just
+ * integer-ness. Lives in this module so the guard evolves with the id
+ * templating it defends (#2099 F4; M2 fields that join the id path must
+ * join this check).
+ */
+export declare const isEmitSafeCfg: (cfg: FunctionCfg | undefined | null) => cfg is FunctionCfg;
+/**
+ * Emit BasicBlock nodes + CFG edges for every function CFG in `cfgs`.
+ *
+ * `maxEdgesPerFunction` caps edges per function. On overflow we stop emitting
+ * that function's remaining edges and call `onWarn` naming the dropped count —
+ * no silent truncation (KTD6/R6). Block nodes are always fully emitted (their
+ * count is bounded by the function's statement count); only edges are capped.
+ */
+export declare function emitFileCfgs(graph: KnowledgeGraph, cfgs: readonly FunctionCfg[], maxEdgesPerFunction?: number, onWarn?: (message: string) => void): CfgEmitResult;

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

@@ -0,0 +1,95 @@
+import { generateId } from '../../../lib/utils.js';
+/**
+ * Default per-function CFG edge cap. A pathological generated function could
+ * otherwise emit an unbounded edge set; the cap bounds graph growth and is
+ * overridable via `--pdg` options. `0` (in options) means no cap (unlimited
+ * — see the `cap` mapping in {@link emitFileCfgs}); `undefined` means this
+ * default.
+ */
+export const DEFAULT_MAX_CFG_EDGES_PER_FUNCTION = 5000;
+const basicBlockId = (filePath, functionStartLine, functionStartColumn, blockIndex) => `BasicBlock:${filePath}:${functionStartLine}:${functionStartColumn}:${blockIndex}`;
+/**
+ * Whether an untrusted `cfgSideChannel` element is safe to feed to
+ * {@link emitFileCfgs}. Deliberately NOT full FunctionCfg validation — it
+ * checks exactly the fields whose corruption is SILENT given emit's
+ * mechanics: {@link basicBlockId} string-templates every id-anchor value
+ * (filePath, function start line/column, block index, edge endpoints) and
+ * the graph's addNode/addRelationship are no-throw Map inserts. Unchecked,
+ * a missing anchor field cross-wires same-`undefined`-id blocks across
+ * functions (addNode is first-writer-wins), and an edge endpoint that
+ * matches no block index becomes a dangling `BasicBlock:…:<n>` edge that
+ * detonates much later at DB bulk-load instead of throwing here — so
+ * endpoints are checked for MEMBERSHIP in the block-index set, not just
+ * integer-ness. Lives in this module so the guard evolves with the id
+ * templating it defends (#2099 F4; M2 fields that join the id path must
+ * join this check).
+ */
+export const isEmitSafeCfg = (cfg) => {
+    if (typeof cfg?.filePath !== 'string' ||
+        !Number.isInteger(cfg.functionStartLine) ||
+        !Number.isInteger(cfg.functionStartColumn) ||
+        !Array.isArray(cfg.blocks) ||
+        !Array.isArray(cfg.edges)) {
+        return false;
+    }
+    const blockIndices = new Set();
+    for (const b of cfg.blocks) {
+        if (!Number.isInteger(b?.index))
+            return false;
+        blockIndices.add(b.index);
+    }
+    return cfg.edges.every((e) => blockIndices.has(e?.from) && blockIndices.has(e?.to));
+};
+/**
+ * Emit BasicBlock nodes + CFG edges for every function CFG in `cfgs`.
+ *
+ * `maxEdgesPerFunction` caps edges per function. On overflow we stop emitting
+ * that function's remaining edges and call `onWarn` naming the dropped count —
+ * no silent truncation (KTD6/R6). Block nodes are always fully emitted (their
+ * count is bounded by the function's statement count); only edges are capped.
+ */
+export function emitFileCfgs(graph, cfgs, maxEdgesPerFunction = DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, onWarn) {
+    const result = { blocks: 0, edges: 0, droppedEdges: 0, cappedFunctions: 0 };
+    const cap = maxEdgesPerFunction > 0 ? maxEdgesPerFunction : Infinity;
+    for (const cfg of cfgs) {
+        const { filePath, functionStartLine, functionStartColumn } = cfg;
+        for (const b of cfg.blocks) {
+            graph.addNode({
+                id: basicBlockId(filePath, functionStartLine, functionStartColumn, b.index),
+                label: 'BasicBlock',
+                properties: {
+                    name: '', // BasicBlock has no name column; identified by id + span
+                    filePath,
+                    startLine: b.startLine,
+                    endLine: b.endLine,
+                    text: b.text,
+                },
+            });
+            result.blocks++;
+        }
+        let emittedForFn = 0;
+        for (const e of cfg.edges) {
+            if (emittedForFn >= cap) {
+                const dropped = cfg.edges.length - emittedForFn;
+                result.droppedEdges += dropped;
+                result.cappedFunctions++;
+                onWarn?.(`[cfg] ${filePath}:${functionStartLine}: per-function CFG edge cap ` +
+                    `(${maxEdgesPerFunction}) reached — dropped ${dropped} of ${cfg.edges.length} edges`);
+                break;
+            }
+            const sourceId = basicBlockId(filePath, functionStartLine, functionStartColumn, e.from);
+            const targetId = basicBlockId(filePath, functionStartLine, functionStartColumn, e.to);
+            graph.addRelationship({
+                id: generateId('CFG', `${sourceId}->${targetId}:${e.kind}`),
+                type: 'CFG',
+                sourceId,
+                targetId,
+                confidence: 1.0,
+                reason: e.kind, // CfgEdgeKind (seq/cond-true/loop-back/…) — queryable
+            });
+            result.edges++;
+            emittedForFn++;
+        }
+    }
+    return result;
+}

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,66 @@
+/**
+ * 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`.
+ */
+/** 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';
+}
+/** Why one block flows to another — drives the `reason` on the emitted CFG edge. */
+export type CfgEdgeKind = 'seq' | 'cond-true' | 'cond-false' | 'loop-back' | 'break' | 'continue' | 'return' | 'throw' | 'switch-case' | 'fallthrough';
+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[];
+}
+/**
+ * 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 {};