gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/core/ingestion/cfg/post-dominators.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Post-dominators (#2085 M5 U2) — the immediate-post-dominator tree of one
+ * function's CFG, the substrate the Ferrante control-dependence pass walks.
+ *
+ * A block `p` post-dominates a block `b` iff every path from `b` to the
+ * function EXIT passes through `p`. Post-dominators are exactly the DOMINATORS
+ * of the REVERSE CFG rooted at EXIT, so this is the Cooper–Harvey–Kennedy
+ * "A Simple, Fast Dominance Algorithm" run over reversed edges. KTD2 of the M5
+ * plan picks CHK over Lengauer–Tarjan: per-function CFGs are small and
+ * line-capped, CHK is near-linear in practice, and its iterative shape matches
+ * the reaching-defs fixpoint already in this module.
+ *
+ * PURE AND DETERMINISTIC (load-bearing, mirrors reaching-defs.ts): no graph, no
+ * logger, importable outside the worker; predecessors/successors are sorted and
+ * iteration is reverse-postorder so the `ipdom` array is identical across runs
+ * (snapshot tests and content-derived edge ids depend on it).
+ *
+ * The single-EXIT invariant the M1 TS visitor preserves (visitors/typescript.ts)
+ * makes EXIT the unique reverse-CFG root. Blocks that cannot reach EXIT in the
+ * forward CFG (an exit-less infinite loop) are not reverse-reachable from it and
+ * have NO post-dominator: their `ipdom` is {@link NO_IPDOM}. The control-
+ * dependence pass treats "no post-dominator" as "does not post-dominate" (KTD5).
+ *
+ * NOTE (issue #2188 F2): this is NOT a fully sound over-approximation. Inside a
+ * region where NO block reaches EXIT, every `ipdom` is `NO_IPDOM`, so the
+ * Ferrante walk degenerates to one edge per control point — it can both DROP a
+ * real control dependence and INVENT a spurious one. This does not arise for the
+ * current TS visitor (every loop is given a structural `header → loopExit`
+ * `cond-false` edge, so EXIT stays reverse-reachable), but it is unsound for
+ * hand-built CFGs and any future language visitor lacking that exit edge.
+ * Nontermination-sensitive post-dominance (a virtual root over the
+ * non-terminating SCCs) would be the correct treatment — tracked for follow-up.
+ */
+import type { FunctionCfg } from './types.js';
+/**
+ * Sentinel `ipdom` value: the block has no immediate post-dominator. True for
+ * the EXIT block itself (the reverse-CFG root) and for any block that cannot
+ * reach EXIT. Chosen as -1 so the {@link postDominates} climb terminates
+ * naturally instead of self-looping on the root.
+ */
+export declare const NO_IPDOM = -1;
+export interface PostDomTree {
+    /**
+     * `ipdom[b]` = the index of `b`'s immediate post-dominator, or
+     * {@link NO_IPDOM} when `b` has none (EXIT, or a block that cannot reach EXIT).
+     */
+    readonly ipdom: readonly number[];
+}
+/**
+ * Compute the immediate-post-dominator tree for one function's CFG. See the
+ * module doc for the purity/determinism contract and EXIT-root assumptions.
+ */
+export declare function computePostDominators(cfg: FunctionCfg): PostDomTree;
+/**
+ * Does block `p` post-dominate block `b`? Climbs the post-dom tree from `b`
+ * toward EXIT and tests membership of `p`. Reflexive: a block post-dominates
+ * itself. A block with no post-dominator (EXIT, or one that cannot reach EXIT)
+ * is post-dominated only by itself. The step guard is purely defensive — the
+ * `ipdom` chain is a tree and always terminates at {@link NO_IPDOM}.
+ */
+export declare function postDominates(tree: PostDomTree, p: number, b: number): boolean;
+/**
+ * Precondition for SOUND post-dominance (#2188 review): EXIT must be reachable
+ * (forward) from every block that is itself reachable from ENTRY. When it
+ * fails — an entry-reachable region that cannot reach EXIT, e.g. a
+ * non-terminating loop or a multi-terminal CFG a future language visitor might
+ * emit — the EXIT-rooted reverse walk degenerates (every such block gets
+ * {@link NO_IPDOM}), which both DROPS real control dependences and INVENTS
+ * spurious ones (the unsoundness documented in the module header). Consumers
+ * ({@link emitFileCdg}) check this and skip CDG for the function rather than
+ * persist an unsound projection — CFG and REACHING_DEF, which do not depend on
+ * post-dominance, are unaffected.
+ *
+ * The current TS visitor always satisfies this (every loop is given a
+ * structural `header → loopExit` edge, keeping EXIT reverse-reachable), so this
+ * is a guard for future visitors and hand-built CFGs, not a behavior change
+ * today. Pure and O(V+E).
+ */
+export declare function isExitReachableFromAllBlocks(cfg: FunctionCfg): boolean;

package/dist/core/ingestion/cfg/post-dominators.js

@@ -0,0 +1,176 @@
+/**
+ * Sentinel `ipdom` value: the block has no immediate post-dominator. True for
+ * the EXIT block itself (the reverse-CFG root) and for any block that cannot
+ * reach EXIT. Chosen as -1 so the {@link postDominates} climb terminates
+ * naturally instead of self-looping on the root.
+ */
+export const NO_IPDOM = -1;
+/**
+ * Compute the immediate-post-dominator tree for one function's CFG. See the
+ * module doc for the purity/determinism contract and EXIT-root assumptions.
+ */
+export function computePostDominators(cfg) {
+    const n = cfg.blocks.length;
+    const exit = cfg.exitIndex;
+    if (n === 0 || exit < 0 || exit >= n) {
+        return { ipdom: new Array(n).fill(NO_IPDOM) };
+    }
+    // Forward adjacency (sorted for deterministic intersect order). The reverse
+    // CFG, on which we compute dominators, flips these: a node's reverse-CFG
+    // successors are its CFG predecessors, and its reverse-CFG predecessors
+    // (the "preds" CHK intersects over) are its CFG successors.
+    const cfgPreds = Array.from({ length: n }, () => []);
+    const cfgSuccs = Array.from({ length: n }, () => []);
+    for (const e of cfg.edges) {
+        if (e.from < 0 || e.from >= n || e.to < 0 || e.to >= n)
+            continue;
+        cfgSuccs[e.from].push(e.to);
+        cfgPreds[e.to].push(e.from);
+    }
+    for (const l of cfgPreds)
+        l.sort((a, b) => a - b);
+    for (const l of cfgSuccs)
+        l.sort((a, b) => a - b);
+    // Postorder of the reverse CFG from EXIT (traversing CFG-predecessor edges).
+    // Iterative DFS with an explicit phase stack; children pushed in sorted order
+    // for determinism. postNum is the CHK comparison key: higher = closer to root.
+    const postNum = new Array(n).fill(-1);
+    const postorder = [];
+    const visited = new Array(n).fill(false);
+    const stack = [{ node: exit, childIdx: 0 }];
+    visited[exit] = true;
+    while (stack.length) {
+        const top = stack[stack.length - 1];
+        const revSuccs = cfgPreds[top.node]; // reverse-CFG successors
+        if (top.childIdx < revSuccs.length) {
+            const next = revSuccs[top.childIdx];
+            top.childIdx += 1;
+            if (!visited[next]) {
+                visited[next] = true;
+                stack.push({ node: next, childIdx: 0 });
+            }
+        }
+        else {
+            postNum[top.node] = postorder.length;
+            postorder.push(top.node);
+            stack.pop();
+        }
+    }
+    const rpo = [...postorder].reverse();
+    // CHK fixpoint. ipdom[exit] = exit DURING computation (the root dominates
+    // itself, so the intersect climb has a common terminus); it is reset to
+    // NO_IPDOM before returning so callers' climbs terminate at the root.
+    const ipdom = new Array(n).fill(NO_IPDOM);
+    ipdom[exit] = exit;
+    const intersect = (a, b) => {
+        let f1 = a;
+        let f2 = b;
+        while (f1 !== f2) {
+            while (postNum[f1] < postNum[f2])
+                f1 = ipdom[f1];
+            while (postNum[f2] < postNum[f1])
+                f2 = ipdom[f2];
+        }
+        return f1;
+    };
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const b of rpo) {
+            if (b === exit)
+                continue;
+            // CHK "predecessors in the reverse CFG" = this block's CFG successors.
+            // Fold only those already processed (ipdom assigned); RPO guarantees at
+            // least one for every block reverse-reachable from EXIT.
+            let newIpdom = NO_IPDOM;
+            for (const s of cfgSuccs[b]) {
+                if (ipdom[s] !== NO_IPDOM) {
+                    newIpdom = newIpdom === NO_IPDOM ? s : intersect(s, newIpdom);
+                }
+            }
+            if (newIpdom !== NO_IPDOM && ipdom[b] !== newIpdom) {
+                ipdom[b] = newIpdom;
+                changed = true;
+            }
+        }
+    }
+    ipdom[exit] = NO_IPDOM; // root: no post-dominator above it
+    return { ipdom };
+}
+/**
+ * Does block `p` post-dominate block `b`? Climbs the post-dom tree from `b`
+ * toward EXIT and tests membership of `p`. Reflexive: a block post-dominates
+ * itself. A block with no post-dominator (EXIT, or one that cannot reach EXIT)
+ * is post-dominated only by itself. The step guard is purely defensive — the
+ * `ipdom` chain is a tree and always terminates at {@link NO_IPDOM}.
+ */
+export function postDominates(tree, p, b) {
+    const { ipdom } = tree;
+    const n = ipdom.length;
+    if (p < 0 || b < 0 || p >= n || b >= n)
+        return false;
+    let cur = b;
+    let steps = 0;
+    while (cur !== NO_IPDOM && steps <= n) {
+        if (cur === p)
+            return true;
+        cur = ipdom[cur];
+        steps += 1;
+    }
+    return false;
+}
+/**
+ * Precondition for SOUND post-dominance (#2188 review): EXIT must be reachable
+ * (forward) from every block that is itself reachable from ENTRY. When it
+ * fails — an entry-reachable region that cannot reach EXIT, e.g. a
+ * non-terminating loop or a multi-terminal CFG a future language visitor might
+ * emit — the EXIT-rooted reverse walk degenerates (every such block gets
+ * {@link NO_IPDOM}), which both DROPS real control dependences and INVENTS
+ * spurious ones (the unsoundness documented in the module header). Consumers
+ * ({@link emitFileCdg}) check this and skip CDG for the function rather than
+ * persist an unsound projection — CFG and REACHING_DEF, which do not depend on
+ * post-dominance, are unaffected.
+ *
+ * The current TS visitor always satisfies this (every loop is given a
+ * structural `header → loopExit` edge, keeping EXIT reverse-reachable), so this
+ * is a guard for future visitors and hand-built CFGs, not a behavior change
+ * today. Pure and O(V+E).
+ */
+export function isExitReachableFromAllBlocks(cfg) {
+    const n = cfg.blocks.length;
+    if (n === 0)
+        return true;
+    const { entryIndex, exitIndex } = cfg;
+    if (entryIndex < 0 || entryIndex >= n || exitIndex < 0 || exitIndex >= n)
+        return false;
+    const succ = Array.from({ length: n }, () => []);
+    const pred = Array.from({ length: n }, () => []);
+    for (const e of cfg.edges) {
+        if (e.from < 0 || e.from >= n || e.to < 0 || e.to >= n)
+            continue;
+        succ[e.from].push(e.to);
+        pred[e.to].push(e.from);
+    }
+    const reach = (start, adj) => {
+        const seen = new Uint8Array(n);
+        const stack = [start];
+        seen[start] = 1;
+        while (stack.length > 0) {
+            const b = stack.pop();
+            for (const next of adj[b]) {
+                if (!seen[next]) {
+                    seen[next] = 1;
+                    stack.push(next);
+                }
+            }
+        }
+        return seen;
+    };
+    const fromEntry = reach(entryIndex, succ); // forward-reachable from ENTRY
+    const canReachExit = reach(exitIndex, pred); // can reach EXIT (reverse from EXIT)
+    for (let i = 0; i < n; i++) {
+        if (fromEntry[i] && !canReachExit[i])
+            return false;
+    }
+    return true;
+}

package/dist/core/ingestion/cfg/reaching-def-reason-codec.d.ts

@@ -0,0 +1,106 @@
+/**
+ * REACHING_DEF reason codec (PDG FU-B-2) — the ONE shared encoder/decoder for
+ * the source-level annotation carried on a persisted `REACHING_DEF` edge's
+ * `reason` column.
+ *
+ * A `REACHING_DEF` edge is `(defBlock:BasicBlock)->(useBlock:BasicBlock)` for one
+ * binding. The persisted columns (`from,to,type,confidence,reason,step`) are
+ * DEDUPED to `(defBlock, useBlock, bindingIdx)` (emit.ts), so the persisted
+ * edge cannot, by itself, recover the def→use chain WITHIN a coalesced
+ * straight-line BasicBlock: lines 7-9 of `chainCompute` collapse to one block
+ * and `a@7 -> b@8 -> c@9` become block-self edges with no line information. This
+ * codec ANNOTATES each edge with the ORDERED LIST of (defLine, useLine) source
+ * lines for that (block-pair, binding) group — the full set of def→use steps the
+ * solver produced for it — so the statement-granular intra-block chain is
+ * recoverable at projection time (pdg-impact.ts) WITHOUT widening the dedup key:
+ * the edge COUNT is unchanged (still one edge per group), only the `reason`
+ * carries the pair LIST (RD/taint substrate + cfg-bench budgets protected — the
+ * cfg-bench canon does not include the persisted `reason`).
+ *
+ * Carrying the FULL list (not just the FIRST pair) is what makes a SAME-BINDING
+ * reassignment chain recoverable: `acc = f(acc); acc = g(acc); acc = h(acc)`
+ * coalesces into one block, and ALL of `acc@24->acc@25`, `acc@25->acc@26`,
+ * `acc@26->acc@27` share the one `(self-block, self-block, accIdx)` group. A
+ * first-pair-only annotation could chain `24->25` but never reach `26`; the full
+ * list lets the projection walk the whole chain to fixpoint.
+ *
+ * ## Wire format (version `1`)
+ *
+ * ```
+ * <name>                                       (legacy / pre-FU-B-2 — bare name)
+ * <name>|1:<d1>:<u1>                           (FU-B-2, single pair)
+ * <name>|1:<d1>:<u1>;<d2>:<u2>;...             (FU-B-2, ordered pair LIST)
+ * ```
+ *
+ * The binding NAME comes FIRST, verbatim, so the established read paths keep
+ * working with a trivial change: `pdg_query` mode:'flows' filters the variable
+ * by `r.reason = $variable OR r.reason STARTS WITH $variable|` and projects the
+ * name via {@link decodeReachingDefReason}. Source identifiers never contain `|`
+ * (the structural separator), so the name is unambiguously the substring before
+ * the first `|`; an un-annotated reason has no `|` and decodes to itself with no
+ * line info. Within the annotation, `;` separates pairs and `:` separates the
+ * version + the two lines of each pair. `<defLine>`/`<useLine>` are 1-based
+ * decimal source lines.
+ *
+ * ## Delimiter / round-trip discipline (mirrors call-summary-codec KTD6)
+ *
+ * Every structural character (`|`, `:`, `;`, the version digit, decimal digits)
+ * is printable ASCII, so the encoding survives `escapeCSVField ∘ sanitizeUTF8`
+ * (csv-generator.ts) byte-exact. The decoder NEVER throws — anything not a
+ * well-formed version-`1` annotation degrades to "name only, no pairs" (the sound
+ * default: the projection then falls back to block-start granularity exactly as
+ * before FU-B-2). A malformed individual pair within an otherwise-well-formed
+ * list is dropped; the well-formed pairs are kept.
+ */
+/** One-character format version prefix. Bump on any wire-format change. */
+export declare const REACHING_DEF_REASON_CODEC_VERSION = "1";
+/** One def→use source-line step within a coalesced block's self chain. */
+export interface DefUseLinePair {
+    /** 1-based def source line. */
+    readonly defLine: number;
+    /** 1-based use source line. */
+    readonly useLine: number;
+}
+/** A decoded REACHING_DEF reason. `pairs` is empty for a legacy (un-annotated)
+ * reason. `defLine`/`useLine` mirror the FIRST pair for back-compat consumers. */
+export interface DecodedReachingDefReason {
+    /** The source-level binding name (always present — the legacy payload). */
+    readonly name: string;
+    /**
+     * The ordered list of (defLine, useLine) steps the FU-B-2 annotation carries.
+     * Empty for a legacy / malformed / un-annotated reason.
+     */
+    readonly pairs: readonly DefUseLinePair[];
+    /** 1-based def source line of the FIRST pair (back-compat; absent if none). */
+    readonly defLine?: number;
+    /** 1-based use source line of the FIRST pair (back-compat; absent if none). */
+    readonly useLine?: number;
+}
+/**
+ * Encode a binding name + its ordered (defLine, useLine) step list into the
+ * versioned `reason` wire string. Deterministic; never throws. Malformed /
+ * negative pairs are dropped (defensive — the solver always passes 1-based
+ * integers); if NO valid pair survives the result degrades to the bare name
+ * (legacy form) so a malformed annotation never fabricates bad lines. The name
+ * is written verbatim FIRST (see the module doc), so a name that —
+ * pathologically — already contains `|` would be re-decoded with a truncated
+ * name; binding names are source identifiers, which never contain `|`, so this
+ * cannot occur for real input (and would only lose line precision, never corrupt
+ * the substrate).
+ */
+export declare function encodeReachingDefReasonPairs(name: string, pairs: ReadonlyArray<DefUseLinePair>): string;
+/**
+ * Single-pair convenience over {@link encodeReachingDefReasonPairs} — kept for
+ * call sites and tests that carry exactly one def→use step.
+ */
+export declare function encodeReachingDefReason(name: string, defLine: number, useLine: number): string;
+/**
+ * Decode a REACHING_DEF `reason` wire string into its binding name + (when
+ * present) the FU-B-2 def/use source-line pair LIST. Never throws — a non-string,
+ * an un-annotated bare name, or a malformed annotation all yield `{ name, pairs:
+ * [] }` (the sound default: the consumer falls back to block-start granularity).
+ * A well-formed `<name>|1:<d1>:<u1>;<d2>:<u2>;...` yields every well-formed pair
+ * (a single malformed pair is dropped, the rest kept); `defLine`/`useLine` mirror
+ * the first pair for back-compat consumers.
+ */
+export declare function decodeReachingDefReason(reason: unknown): DecodedReachingDefReason;

package/dist/core/ingestion/cfg/reaching-def-reason-codec.js

@@ -0,0 +1,133 @@
+/**
+ * REACHING_DEF reason codec (PDG FU-B-2) — the ONE shared encoder/decoder for
+ * the source-level annotation carried on a persisted `REACHING_DEF` edge's
+ * `reason` column.
+ *
+ * A `REACHING_DEF` edge is `(defBlock:BasicBlock)->(useBlock:BasicBlock)` for one
+ * binding. The persisted columns (`from,to,type,confidence,reason,step`) are
+ * DEDUPED to `(defBlock, useBlock, bindingIdx)` (emit.ts), so the persisted
+ * edge cannot, by itself, recover the def→use chain WITHIN a coalesced
+ * straight-line BasicBlock: lines 7-9 of `chainCompute` collapse to one block
+ * and `a@7 -> b@8 -> c@9` become block-self edges with no line information. This
+ * codec ANNOTATES each edge with the ORDERED LIST of (defLine, useLine) source
+ * lines for that (block-pair, binding) group — the full set of def→use steps the
+ * solver produced for it — so the statement-granular intra-block chain is
+ * recoverable at projection time (pdg-impact.ts) WITHOUT widening the dedup key:
+ * the edge COUNT is unchanged (still one edge per group), only the `reason`
+ * carries the pair LIST (RD/taint substrate + cfg-bench budgets protected — the
+ * cfg-bench canon does not include the persisted `reason`).
+ *
+ * Carrying the FULL list (not just the FIRST pair) is what makes a SAME-BINDING
+ * reassignment chain recoverable: `acc = f(acc); acc = g(acc); acc = h(acc)`
+ * coalesces into one block, and ALL of `acc@24->acc@25`, `acc@25->acc@26`,
+ * `acc@26->acc@27` share the one `(self-block, self-block, accIdx)` group. A
+ * first-pair-only annotation could chain `24->25` but never reach `26`; the full
+ * list lets the projection walk the whole chain to fixpoint.
+ *
+ * ## Wire format (version `1`)
+ *
+ * ```
+ * <name>                                       (legacy / pre-FU-B-2 — bare name)
+ * <name>|1:<d1>:<u1>                           (FU-B-2, single pair)
+ * <name>|1:<d1>:<u1>;<d2>:<u2>;...             (FU-B-2, ordered pair LIST)
+ * ```
+ *
+ * The binding NAME comes FIRST, verbatim, so the established read paths keep
+ * working with a trivial change: `pdg_query` mode:'flows' filters the variable
+ * by `r.reason = $variable OR r.reason STARTS WITH $variable|` and projects the
+ * name via {@link decodeReachingDefReason}. Source identifiers never contain `|`
+ * (the structural separator), so the name is unambiguously the substring before
+ * the first `|`; an un-annotated reason has no `|` and decodes to itself with no
+ * line info. Within the annotation, `;` separates pairs and `:` separates the
+ * version + the two lines of each pair. `<defLine>`/`<useLine>` are 1-based
+ * decimal source lines.
+ *
+ * ## Delimiter / round-trip discipline (mirrors call-summary-codec KTD6)
+ *
+ * Every structural character (`|`, `:`, `;`, the version digit, decimal digits)
+ * is printable ASCII, so the encoding survives `escapeCSVField ∘ sanitizeUTF8`
+ * (csv-generator.ts) byte-exact. The decoder NEVER throws — anything not a
+ * well-formed version-`1` annotation degrades to "name only, no pairs" (the sound
+ * default: the projection then falls back to block-start granularity exactly as
+ * before FU-B-2). A malformed individual pair within an otherwise-well-formed
+ * list is dropped; the well-formed pairs are kept.
+ */
+/** One-character format version prefix. Bump on any wire-format change. */
+export const REACHING_DEF_REASON_CODEC_VERSION = '1';
+/**
+ * Structural separator between the binding name and the versioned annotation.
+ * Source identifiers cannot contain it, so the name is the substring before the
+ * first occurrence (and a name with no occurrence is a legacy bare-name reason).
+ */
+const NAME_SEP = '|';
+/** Separator between consecutive (defLine:useLine) pairs in the annotation. */
+const PAIR_SEP = ';';
+/** Whether a (defLine, useLine) pair is a well-formed 1-based-or-0 integer pair. */
+function isValidPair(defLine, useLine) {
+    return Number.isInteger(defLine) && Number.isInteger(useLine) && defLine >= 0 && useLine >= 0;
+}
+/**
+ * Encode a binding name + its ordered (defLine, useLine) step list into the
+ * versioned `reason` wire string. Deterministic; never throws. Malformed /
+ * negative pairs are dropped (defensive — the solver always passes 1-based
+ * integers); if NO valid pair survives the result degrades to the bare name
+ * (legacy form) so a malformed annotation never fabricates bad lines. The name
+ * is written verbatim FIRST (see the module doc), so a name that —
+ * pathologically — already contains `|` would be re-decoded with a truncated
+ * name; binding names are source identifiers, which never contain `|`, so this
+ * cannot occur for real input (and would only lose line precision, never corrupt
+ * the substrate).
+ */
+export function encodeReachingDefReasonPairs(name, pairs) {
+    const valid = pairs.filter((p) => isValidPair(p.defLine, p.useLine));
+    if (valid.length === 0)
+        return name;
+    const body = valid.map((p) => `${p.defLine}:${p.useLine}`).join(PAIR_SEP);
+    return `${name}${NAME_SEP}${REACHING_DEF_REASON_CODEC_VERSION}:${body}`;
+}
+/**
+ * Single-pair convenience over {@link encodeReachingDefReasonPairs} — kept for
+ * call sites and tests that carry exactly one def→use step.
+ */
+export function encodeReachingDefReason(name, defLine, useLine) {
+    return encodeReachingDefReasonPairs(name, [{ defLine, useLine }]);
+}
+/**
+ * Decode a REACHING_DEF `reason` wire string into its binding name + (when
+ * present) the FU-B-2 def/use source-line pair LIST. Never throws — a non-string,
+ * an un-annotated bare name, or a malformed annotation all yield `{ name, pairs:
+ * [] }` (the sound default: the consumer falls back to block-start granularity).
+ * A well-formed `<name>|1:<d1>:<u1>;<d2>:<u2>;...` yields every well-formed pair
+ * (a single malformed pair is dropped, the rest kept); `defLine`/`useLine` mirror
+ * the first pair for back-compat consumers.
+ */
+export function decodeReachingDefReason(reason) {
+    const raw = typeof reason === 'string' ? reason : '';
+    const sep = raw.indexOf(NAME_SEP);
+    if (sep === -1)
+        return { name: raw, pairs: [] };
+    const name = raw.slice(0, sep);
+    const annotation = raw.slice(sep + 1);
+    // Annotation is `<version>:<d1>:<u1>;<d2>:<u2>;...`. Split off the version
+    // prefix once: the first colon ends the version token; the remainder is the
+    // `;`-separated pair body.
+    const firstColon = annotation.indexOf(':');
+    if (firstColon === -1 || annotation.slice(0, firstColon) !== REACHING_DEF_REASON_CODEC_VERSION) {
+        return { name, pairs: [] };
+    }
+    const body = annotation.slice(firstColon + 1);
+    const pairs = [];
+    for (const chunk of body.split(PAIR_SEP)) {
+        const parts = chunk.split(':');
+        if (parts.length !== 2)
+            continue; // malformed pair — drop it, keep the rest
+        const defLine = Number(parts[0]);
+        const useLine = Number(parts[1]);
+        if (!isValidPair(defLine, useLine))
+            continue;
+        pairs.push({ defLine, useLine });
+    }
+    if (pairs.length === 0)
+        return { name, pairs: [] };
+    return { name, pairs, defLine: pairs[0].defLine, useLine: pairs[0].useLine };
+}

package/dist/core/ingestion/cfg/reaching-defs-graph.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure graph sub-stages for the reaching-definitions solvers (#2201 review R4).
+ *
+ * Extracted from reaching-defs.ts to keep that module focused on the
+ * orchestrator, the dense oracle, the statement sweep, and the dispatcher.
+ * Everything here is a pure function of plain arrays — no CFG, no harvest, no
+ * solver state — so this module has NO dependency on reaching-defs.ts (a strict
+ * one-way import) and each stage is independently testable. The SSA pipeline
+ * (dominators → dominance frontiers → Tarjan SCC → reach-set condensation)
+ * implements Cooper-Harvey-Kennedy + Cytron + Tarjan; reverse-post-order, the
+ * loop-reachability check, and the def-set/lattice primitives are shared with
+ * the dense GEN/KILL solver and the dispatcher.
+ *
+ * These are held byte-identical to their former inline form by the differential
+ * equivalence fuzz (test/unit/cfg/reaching-defs-equivalence.test.ts) — any diff
+ * after extraction is an extraction bug, never the oracle.
+ */
+export {};