cgraphx 2.0.1 → 2.0.3

package/dist/core/code/engine/core/ingestion/cfg/callee-cell-format.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Wire format of the `BasicBlock.callees` / `BasicBlock.calleeIds` cells.
+ *
+ * A LEAF module on purpose: it declares two string constants and imports
+ * nothing. `cfg/emit.ts` produces those cells and `mcp/local/pdg-impact.ts`
+ * parses them, but `emit.ts` is analyze-only and drags the whole CFG closure
+ * (reaching-defs, control-dependence, post-dominators, synthetic-escape,
+ * call-site-harvest) behind it — 8 modules evaluated at every MCP server start
+ * just to read two strings, since ESM evaluates a module to import any binding
+ * from it (#2802 review). Splitting the format constants out deletes that cost
+ * rather than deferring it, which is the same bar #2802 held its own proposals
+ * to.
+ *
+ * `emit.ts` RE-EXPORTS both names, so every existing importer keeps working and
+ * the producer/consumer pair still resolves to one definition — the drift this
+ * shared constant exists to prevent stays impossible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CALLEE_ID_SEP = exports.CALLEES_TRUNCATED_SENTINEL = void 0;
+/**
+ * Reserved token placed in `BasicBlock.callees` when a statement's call sites
+ * were truncated at the per-statement site cap: the recorded callee list is then
+ * INCOMPLETE, so over-cap callees are absent. `*` is not a valid identifier
+ * leaf, so it cannot collide with a real callee name. The impact bridge treats a
+ * slice containing this sentinel as "callees unknown" and keeps reach
+ * callgraph-equal (proven), rather than falsely labeling an absent-but-real
+ * callee `unproven-bridge`.
+ */
+exports.CALLEES_TRUNCATED_SENTINEL = '*';
+/**
+ * Inner separator for the `BasicBlock.calleeIds` cell (resolved callee symbol
+ * ids). A TAB is used — NOT a space — because resolved ids embed `filePath` and
+ * C++ overload shape tags with multi-word primitive types (e.g. `unsigned char`,
+ * `long double`), so an id can legitimately contain a space; a space-joined cell
+ * then fragments on read and silently drops inter-procedural reach to that
+ * callee (#2227 tri-review). A tab cannot appear in a tree-sitter-derived id
+ * token (paths/identifiers/type tokens are tab-free) and round-trips intact
+ * through `escapeCSVField` (tab is in its preserved set) and the RFC-4180 COPY
+ * reader (every cell is quoted). Producer (`calleeIdsOfBlock`) and consumer
+ * (`splitCalleeIds`) both resolve to this single constant so they cannot drift.
+ * The sibling `callees` (leaf-name) cell stays space-joined — leaf names are
+ * bare identifiers and never contain a space.
+ */
+exports.CALLEE_ID_SEP = '\t';

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

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reachableBlocks = exports.CfgBuilder = exports.CfgNestingDepthError = exports.MAX_CFG_NESTING_DEPTH = void 0;
+/**
+ * Hard ceiling on CFG recursive-descent scope-entry depth (#2195). A language
+ * `CfgVisitor` wraps each nested block scope in {@link CfgBuilder.withNesting} (its
+ * `visitBody` / `visitSeq` choke points), so the live count tracks scope entries,
+ * not statement width. NOTE the count is ~2× LEXICAL nesting for block-bodied
+ * constructs (visitBody → visitSeq both enter), so the effective lexical ceiling
+ * is ~250 levels for block bodies (~500 for single-statement bodies / bare
+ * blocks). Real source nests ≤ ~50 deep, so this fires only on machine-generated
+ * / adversarial input. Both effective ceilings sit far below the engine's native
+ * stack limit (~1.2k+ nesting even on the raised worker `stackSizeMb`), so the
+ * bail is a DETERMINISTIC, language-independent {@link CfgNestingDepthError}
+ * rather than a nondeterministic `RangeError` thrown somewhere mid-walk.
+ */
+exports.MAX_CFG_NESTING_DEPTH = 500;
+/**
+ * Thrown by the visitor nesting-depth guard ({@link CfgBuilder.enterNesting})
+ * when lexical nesting exceeds {@link MAX_CFG_NESTING_DEPTH}. `collectFunctionCfgs`
+ * catches it and counts the function under `skipped.tooDeeplyNested`, isolating
+ * the bail to one function instead of risking a worker-wide stack overflow.
+ */
+class CfgNestingDepthError extends Error {
+    limit;
+    constructor(limit) {
+        super(`CFG nesting depth exceeded ${limit}`);
+        this.limit = limit;
+        this.name = 'CfgNestingDepthError';
+    }
+}
+exports.CfgNestingDepthError = CfgNestingDepthError;
+class CfgBuilder {
+    filePath;
+    functionStartLine;
+    functionEndLine;
+    functionStartColumn;
+    blocks = [];
+    edges = [];
+    edgeKeys = new Set();
+    /** Live recursive-descent nesting depth — see {@link enterNesting}. */
+    nesting = 0;
+    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', facts) {
+        this.blocks.push({
+            startLine,
+            endLine,
+            textParts: text ? [text] : [],
+            kind,
+            statements: facts ? [facts] : [],
+        });
+        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, facts) {
+        const b = this.blocks[index];
+        if (!b)
+            return;
+        if (endLine > b.endLine)
+            b.endLine = endLine;
+        if (appendText)
+            b.textParts.push(appendText);
+        if (facts)
+            b.statements.push(facts);
+    }
+    /**
+     * Attach a facts-only statement record to a block WITHOUT touching its text
+     * or line span (#2082 M2 U1) — bench fingerprints and CFG snapshots include
+     * block text, so harvesting must never perturb it (ENTRY-block param defs
+     * are the canonical use; records that must precede a walked body get their
+     * own facts-only block instead, see the catch-param handling in visitTry).
+     */
+    attachFacts(index, facts) {
+        const b = this.blocks[index];
+        if (!b)
+            return;
+        b.statements.push(facts);
+    }
+    get blockCount() {
+        return this.blocks.length;
+    }
+    /**
+     * Run `fn` inside ONE nested block scope (#2195) — the single choke every
+     * visitor's `visitBody` / `visitSeq` funnels through. Enters on the way in and
+     * exits in a `finally`, so the live depth is balanced on every return AND every
+     * throw and the enter/exit can never drift out of pair (the reason this is one
+     * helper, not 24 hand-paired call sites). Throws {@link CfgNestingDepthError}
+     * when nesting exceeds {@link MAX_CFG_NESTING_DEPTH} — a proactive, deterministic
+     * bail before the native stack can overflow on a pathologically nested function.
+     *
+     * A block-bodied construct passes through BOTH visitBody and visitSeq, so it
+     * costs TWO scopes per lexical level: the effective structural ceiling is
+     * ~MAX_CFG_NESTING_DEPTH/2 (~250) lexical levels for block bodies (~500 for
+     * single-statement bodies / bare blocks, which hit only one of the two). Still
+     * an order of magnitude below the native limit and far above real code (≤ ~50).
+     */
+    withNesting(fn) {
+        this.enterNesting();
+        try {
+            return fn();
+        }
+        finally {
+            this.exitNesting();
+        }
+    }
+    /**
+     * Increment the nesting counter, throwing {@link CfgNestingDepthError} past the
+     * cap. Prefer {@link withNesting}, which pairs the exit in a `finally`; this is
+     * exposed for direct depth-accounting tests only.
+     */
+    enterNesting() {
+        if (++this.nesting > exports.MAX_CFG_NESTING_DEPTH)
+            throw new CfgNestingDepthError(exports.MAX_CFG_NESTING_DEPTH);
+    }
+    /** Decrement the nesting counter — the partner of {@link enterNesting}. */
+    exitNesting() {
+        this.nesting--;
+    }
+    /** Produce the serializable CFG. Caller is responsible for having wired the
+     *  function's dangling exits to {@link exitIndex} before calling.
+     *
+     *  Pass `bindings` (the function's binding table, possibly empty) to emit
+     *  statement facts (#2082 M2 U1) — every block then carries a `statements`
+     *  array. Omit it (hand-built test CFGs, pre-M2 producers) and both fields
+     *  are absent, which the reaching-defs solver reports as `no-facts`. */
+    finish(bindings) {
+        const withFacts = bindings !== undefined;
+        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,
+                ...(withFacts ? { statements: b.statements } : {}),
+            })),
+            edges: [...this.edges],
+            ...(withFacts ? { bindings } : {}),
+        };
+    }
+}
+exports.CfgBuilder = CfgBuilder;
+/**
+ * Block indices reachable from `entryIndex` by following edges. Backs the
+ * reachability property tests (R9) over hand-built and visitor-produced CFGs.
+ */
+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;
+};
+exports.reachableBlocks = reachableBlocks;

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

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PDG_MAX_FUNCTION_LINES = void 0;
+exports.collectFunctionCfgs = collectFunctionCfgs;
+const cfg_builder_js_1 = require("./cfg-builder.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`.
+ */
+exports.DEFAULT_PDG_MAX_FUNCTION_LINES = 2000;
+/**
+ * Convert a CFG built from an EXTRACTED sub-document's AST (script-relative
+ * tree-sitter rows) into the enclosing file's coordinates by adding `offset` to
+ * every source-line field. Needed for embedded scripts — a Vue SFC `<script>`
+ * block parses at row 0 but lives at `lineOffset` in the `.vue` file, and every
+ * other worker-emitted graph node is already file-relative; without this, the
+ * CFG's `functionStartLine` would never join its Function/Method graph node
+ * (inter-procedural taint silently resolves nothing) and BasicBlock source
+ * lines would point at the wrong `.vue` line. A 0 offset returns the input
+ * unchanged (the common case: `.ts`/`.js`/etc. parse at the file root), keeping
+ * non-embedded languages byte-identical. Synthetic bindings keep `declLine` 0.
+ */
+function shiftCfgLines(cfg, offset) {
+    if (offset === 0)
+        return cfg;
+    return {
+        ...cfg,
+        functionStartLine: cfg.functionStartLine + offset,
+        functionEndLine: cfg.functionEndLine + offset,
+        blocks: cfg.blocks.map((b) => ({
+            ...b,
+            startLine: b.startLine + offset,
+            endLine: b.endLine + offset,
+            statements: b.statements?.map((s) => ({ ...s, line: s.line + offset })),
+        })),
+        bindings: cfg.bindings?.map((bd) => bd.declLine > 0 ? { ...bd, declLine: bd.declLine + offset } : bd),
+    };
+}
+function collectFunctionCfgs(root, visitor, filePath, maxFunctionLines = 0, lineOffset = 0) {
+    const cfgs = [];
+    let tooManyLines = 0;
+    let tooDeeplyNested = 0;
+    let buildError = 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) {
+                tooManyLines++;
+            }
+            else {
+                // Isolate the per-function build: a proactive deep-nesting bail
+                // (CfgNestingDepthError) or any other visitor throw is counted and
+                // skipped HERE, so it can't escape to the worker's language-group catch
+                // and silently drop every remaining function's CFG (#2195).
+                try {
+                    const cfg = visitor.buildFunctionCfg(node, filePath);
+                    if (cfg)
+                        cfgs.push(shiftCfgLines(cfg, lineOffset));
+                }
+                catch (err) {
+                    if (err instanceof cfg_builder_js_1.CfgNestingDepthError)
+                        tooDeeplyNested++;
+                    else
+                        buildError++;
+                }
+            }
+        }
+        // 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: { tooManyLines, tooDeeplyNested, buildError } };
+}

package/dist/core/code/engine/core/ingestion/cfg/control-dependence.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeControlDependence = computeControlDependence;
+/**
+ * Control dependence (#2085 M5 U3) — Ferrante, Ottenstein & Warren §3.1.1
+ * semantics. A block `dependent` is control-dependent on a branch block
+ * `controller` when `controller` decides whether `dependent` executes: formally,
+ * there is a CFG edge `controller → B` such that `dependent` post-dominates `B`
+ * but does NOT strictly post-dominate `controller`.
+ *
+ * Construction — the reverse-CFG dominance-frontier formulation (Cytron,
+ * Ferrante, Rosen, Wegman & Zadeck 1991): control dependence IS the dominance
+ * frontier of the reverse CFG, so `A ∈ PDF(X)` (the post-dominance frontier)
+ * ⟺ `X` is control-dependent on `A`. The PDF is computed bottom-up over the
+ * post-dom tree (`PDF_local` from a node's CFG predecessors + `PDF_up` from its
+ * post-dom-tree children) in O(N + E + output) — each up-step is charged to a
+ * distinct emitted edge, NOT re-walked per CFG edge as the original §3.1.1
+ * up-walk did (which was Θ(N²) on a deep post-dom chain). The two formulations
+ * enumerate the IDENTICAL full `(controller, dependent, label)` set (verified
+ * byte-identical on 3203 CFGs + ~1M-case differential fuzz); LLVM, Joern and WALA
+ * use the reverse-DF form. (Only the rare TRUNCATED prefix — when a function
+ * exceeds `maxEdges` — differs from the old prefix: it is now a sorted
+ * deterministic prefix rather than CFG-edge-iteration order. Both are valid,
+ * deterministic subsets; the full untruncated output is unchanged.)
+ * The branch SENSE ('T' | 'F') of the controlling edge becomes the edge label
+ * (KTD4 / KTD3 — it rides the persisted relation's `reason` column).
+ *
+ * PURE AND DETERMINISTIC (mirrors post-dominators.ts / reaching-defs.ts): no
+ * graph, no logger, importable outside the worker; output is deduped per
+ * (controller, dependent, label) and sorted, so snapshot tests and
+ * content-derived edge ids are stable. The loop header legitimately appears as
+ * control-dependent on ITSELF (`controller === dependent`) — the loop predicate
+ * gates its own re-execution; this is standard PDG behavior, not a bug.
+ */
+const post_dominators_js_1 = require("./post-dominators.js");
+function buildArmSenses(cfg) {
+    const n = cfg.blocks.length;
+    const senses = Array.from({ length: n }, () => ({
+        hasTrueArm: false,
+        hasFalseArm: false,
+    }));
+    for (const e of cfg.edges) {
+        if (e.from < 0 || e.from >= n)
+            continue;
+        if (e.kind === 'cond-true' || e.kind === 'switch-case')
+            senses[e.from].hasTrueArm = true;
+        else if (e.kind === 'cond-false')
+            senses[e.from].hasFalseArm = true;
+    }
+    return senses;
+}
+/**
+ * The CDG label ('T'|'F') for a control-dependence edge, given the controlling
+ * block's arm senses. An explicitly-sensed edge is taken at face value; an
+ * ambiguous fall-through edge (`seq`/`loop-back`/`fallthrough`/jump) is the
+ * COMPLEMENT of the controller's explicit sibling arm. Per-case `switch` value
+ * labels are deferred to #2086 — every `switch-case` is 'T' in M5.
+ */
+function labelFor(kind, controller) {
+    if (kind === 'cond-true' || kind === 'switch-case')
+        return 'T';
+    if (kind === 'cond-false')
+        return 'F';
+    // Ambiguous structural kind: take the complement of the controller's explicit
+    // arm. A block with a true arm reaches here via its false fall-through; a
+    // do/while bottom-test (false arm = cond-false) reaches here via its true
+    // loop-back. With neither explicit arm (a degenerate / exit-unreachable
+    // region — see #2188 F2, where the dependence itself is unsound) the sense is
+    // indeterminate; default 'F' since fall-through is the common case.
+    if (controller.hasTrueArm)
+        return 'F';
+    if (controller.hasFalseArm)
+        return 'T';
+    return 'F';
+}
+/**
+ * Compute control-dependence edges for one function's CFG. `postDom` may be
+ * supplied to reuse an already-built tree; otherwise it is computed. See the
+ * module doc for the purity/determinism contract.
+ */
+function computeControlDependence(cfg, postDom, 
+// Output-size ceiling, mirroring computeReachingDefs' `maxFacts` (#2188 review).
+// The reverse-DF set is the bounded (controller, dependent, label) dependence
+// relation, so peak working set ≈ output here (no pre-dedup spike like the old
+// up-walk) — this caps the final edge COUNT, not transient memory. `0` ⇒
+// unbounded. On overflow `edges` is a deterministic SORTED prefix and
+// `truncated` is set — never a silent drop. (The sorted prefix is the prefix
+// CONTENTS may differ from the old up-walk's CFG-edge-iteration prefix at the
+// cap boundary; the FULL untruncated set is byte-identical — see the module doc.)
+maxEdges = 0) {
+    const tree = postDom ?? (0, post_dominators_js_1.computePostDominators)(cfg);
+    const { ipdom } = tree;
+    const n = cfg.blocks.length;
+    const armSenses = buildArmSenses(cfg);
+    const cap = maxEdges > 0 ? maxEdges : Infinity;
+    // Reverse-CFG post-dominance frontier (Cytron, Ferrante, Rosen, Wegman,
+    // Zadeck 1991): control dependence IS the dominance frontier of the reverse
+    // CFG. `A ∈ PDF(X)` ⟺ X is control-dependent on A, so emit (controller=A,
+    // dependent=X). Computing the PDF bottom-up over the post-dom tree charges
+    // each up-step to a DISTINCT emitted entry — O(N+E+output) — instead of the
+    // old Ferrante up-walk that re-climbs the ipdom chain per CFG edge (Θ(N²) on
+    // a deep post-dom chain). Output is the identical (controller, dependent,
+    // label) set (verified byte-identical on 3203 CFGs across all languages +
+    // fuzz) and 1-2 orders of magnitude faster. LLVM (ReverseIDFCalculator),
+    // Joern (CdgPass) and WALA use the same formulation.
+    const children = Array.from({ length: n }, () => []);
+    const inEdges = Array.from({ length: n }, () => []);
+    for (let b = 0; b < n; b++) {
+        const ip = ipdom[b];
+        if (ip !== post_dominators_js_1.NO_IPDOM && ip >= 0 && ip < n)
+            children[ip].push(b);
+    }
+    for (const e of cfg.edges) {
+        if (e.from < 0 || e.from >= n || e.to < 0 || e.to >= n)
+            continue;
+        inEdges[e.to].push({ from: e.from, kind: e.kind });
+    }
+    // Post-dom-tree post-order (children before parents). Iterative — the post-dom
+    // forest can itself be chain-deep. Roots are the NO_IPDOM nodes (EXIT, plus
+    // any exit-unreachable region per #2188 F2). The reverse of a root-first DFS
+    // visits every parent AFTER all its descendants.
+    const dfs = [];
+    for (let r = 0; r < n; r++)
+        if (ipdom[r] === post_dominators_js_1.NO_IPDOM)
+            dfs.push(r);
+    const preorder = [];
+    while (dfs.length) {
+        const x = dfs.pop();
+        preorder.push(x);
+        for (const c of children[x])
+            dfs.push(c);
+    }
+    const order = preorder.reverse();
+    // PDF[X]: controller A → the label SET with which A controls X. A set (not one
+    // label) because a controller can reach X via opposite-sense arms (goto-
+    // cycles) — the old (a, cur, label) dedup kept both rows.
+    const pdf = Array.from({ length: n }, () => new Map());
+    const add = (x, a, label) => {
+        const set = pdf[x].get(a);
+        if (set)
+            set.add(label);
+        else
+            pdf[x].set(a, new Set([label]));
+    };
+    for (const x of order) {
+        // PDF_local: a CFG-predecessor A of X that X does not (immediately) post-
+        // dominate. `A !== X && ipdom[A] !== X` is exactly the production
+        // `!postDominates(X, A)` for one edge A→X (postDominates(X,A) ⟺ ipdom[A]===X),
+        // and it excludes self-edges + NO_IPDOM regions. Sense is read from the
+        // CONTROLLER's arms (seq/loop-back fall-through false arms would otherwise
+        // mislabel as 'T' — #2188 F1).
+        for (const { from: a, kind } of inEdges[x]) {
+            if (a !== x && ipdom[a] !== x)
+                add(x, a, labelFor(kind, armSenses[a]));
+        }
+        // PDF_up: inherit each post-dom child's frontier controller (with its label
+        // set) when X does not post-dominate it.
+        for (const z of children[x]) {
+            for (const [a, labels] of pdf[z]) {
+                if (ipdom[a] !== x)
+                    for (const l of labels)
+                        add(x, a, l);
+            }
+        }
+    }
+    const out = [];
+    for (const x of order) {
+        for (const [a, labels] of pdf[x]) {
+            for (const label of labels)
+                out.push({ controllerBlock: a, dependentBlock: x, label });
+        }
+    }
+    out.sort((x, y) => x.controllerBlock - y.controllerBlock ||
+        x.dependentBlock - y.dependentBlock ||
+        (x.label < y.label ? -1 : x.label > y.label ? 1 : 0));
+    // `maxEdges` is a heap-safety backstop applied to the SORTED set (the DF makes
+    // overflow far rarer than the old per-edge walk). Deterministic prefix, never
+    // a silent drop; mirrors computeReachingDefs' `truncated`.
+    let truncated = false;
+    if (cap !== Infinity && out.length > cap) {
+        truncated = true;
+        out.length = cap;
+    }
+    return { edges: out, truncated };
+}

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

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlFlowContext = void 0;
+exports.wireJumpThroughFinalizers = wireJumpThroughFinalizers;
+exports.drainFinalizerPending = drainFinalizerPending;
+class ControlFlowContext {
+    stack = [];
+    pushLoop(continueTo, breakTo, labels = []) {
+        this.stack.push({ kind: 'loop', continueTo, breakTo, labels });
+    }
+    pushSwitch(breakTo, labels = []) {
+        this.stack.push({ kind: 'switch', breakTo, labels });
+    }
+    /** Push a labeled non-loop statement's break-target frame. */
+    pushLabeledBlock(breakTo, labels) {
+        this.stack.push({ kind: 'block', breakTo, labels });
+    }
+    /**
+     * Push a finalizer frame and return it — the owning `visitTry` keeps the
+     * reference to wire {@link FinalizerFrame.pending} after popping it.
+     */
+    pushFinalizer(entry) {
+        const frame = { kind: 'finalizer', entry, pending: [] };
+        this.stack.push(frame);
+        return frame;
+    }
+    pop() {
+        this.stack.pop();
+    }
+    /**
+     * Resolve a `break`: the nearest enclosing loop/switch frame (or, with a
+     * label, the nearest frame carrying that label) plus every finalizer frame
+     * stacked ABOVE it — i.e. exactly the finallys the jump crosses, innermost
+     * first. Returns `undefined` if there is no valid target (malformed input or
+     * an unmodeled label) — the caller falls back to its conservative routing and
+     * threads nothing.
+     */
+    resolveBreak(label) {
+        return this.resolve((f) => label === undefined
+            ? f.kind !== 'block' // an unlabeled break never targets a labeled block
+            : f.labels.includes(label));
+    }
+    /** Resolve a `continue`: like {@link resolveBreak} but only loop frames match. */
+    resolveContinue(label) {
+        return this.resolve((f) => f.kind === 'loop' && (label === undefined || f.labels.includes(label)), (f) => f.continueTo);
+    }
+    /**
+     * Resolve a Java `yield e` (switch-EXPRESSION arm exit): the nearest enclosing
+     * SWITCH frame's exit, threading the finalizers stacked above it. Unlike a
+     * `break`, a `yield` ALWAYS targets the switch — never an intervening loop — so
+     * it cannot match a loop frame (a `yield` inside a loop inside a switch arm
+     * still exits the whole switch). Returns `undefined` when there is no enclosing
+     * switch (malformed input); the caller falls back to its conservative routing.
+     */
+    resolveYield() {
+        return this.resolve((f) => f.kind === 'switch');
+    }
+    /** Every active finalizer, innermost first — what a `return` must cross. */
+    finalizersForReturn() {
+        const fins = [];
+        for (let i = this.stack.length - 1; i >= 0; i--) {
+            const f = this.stack[i];
+            if (f.kind === 'finalizer')
+                fins.push(f);
+        }
+        return fins;
+    }
+    /**
+     * Target block for a `break` (no finalizer info) — see {@link resolveBreak}.
+     * Prefer `resolveBreak` + {@link wireJumpThroughFinalizers} in visitors: a
+     * target-only lookup silently loses finalizer threading (the M2 soundness
+     * fix). Kept for target-shape assertions in tests.
+     */
+    breakTarget(label) {
+        return this.resolveBreak(label)?.target;
+    }
+    /** Target block for a `continue` — same caveat as {@link breakTarget}. */
+    continueTarget(label) {
+        return this.resolveContinue(label)?.target;
+    }
+    resolve(matches, targetOf = (f) => f.breakTo) {
+        const crossed = [];
+        for (let i = this.stack.length - 1; i >= 0; i--) {
+            const f = this.stack[i];
+            if (f.kind === 'finalizer') {
+                crossed.push(f);
+                continue;
+            }
+            if (matches(f))
+                return { target: targetOf(f), finalizers: crossed };
+        }
+        return undefined;
+    }
+}
+exports.ControlFlowContext = ControlFlowContext;
+/**
+ * Wire a jump from `from` to `target`, routing through the finallys it
+ * crosses (innermost first). The first leg keeps the bare jump `kind`
+ * (preserving the "kind ⟹ source-block terminator" invariant in types.ts);
+ * each finally's completion leg is registered as pending on its frame with the
+ * matching `finally-*` kind and wired by the owning try via
+ * {@link drainFinalizerPending} once the finally's exits are known.
+ *
+ * Language-agnostic on purpose (#2082 M2): the threading protocol encodes
+ * three subtle invariants every future language visitor needs identically —
+ * keeping it here means a new visitor cannot drift on any of them.
+ */
+function wireJumpThroughFinalizers(builder, from, finalizers, target, kind) {
+    if (finalizers.length === 0) {
+        builder.edge(from, target, kind);
+        return;
+    }
+    const completionKind = `finally-${kind}`;
+    builder.edge(from, finalizers[0].entry, kind);
+    for (let i = 0; i < finalizers.length; i++) {
+        const to = i + 1 < finalizers.length ? finalizers[i + 1].entry : target;
+        finalizers[i].pending.push({ to, kind: completionKind });
+    }
+}
+/**
+ * Wire a popped finalizer frame's pending completion legs from the finally's
+ * exit blocks. A finally that itself always jumps (`finally { return 2; }`)
+ * has no exits — its pending legs wire nowhere, matching JS's
+ * finally-override semantics.
+ */
+function drainFinalizerPending(builder, frame, finallyExits) {
+    for (const p of frame.pending) {
+        builder.connect(finallyExits, p.to, p.kind);
+    }
+}