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

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

@@ -0,0 +1,129 @@
+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', 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;
+    }
+    /** 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 } : {}),
+        };
+    }
+}
+/**
+ * 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,97 @@
+/**
+ * ControlFlowContext (issue #2081 M1; finalizer frames added by #2082 M2 U2).
+ *
+ * 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.
+ *
+ * M2 adds FINALIZER frames, interleaved on the SAME stack as loop/switch frames
+ * — interleaving is load-bearing: a jump must route through exactly the
+ * `finally` bodies lexically BETWEEN it and its target (target-relative
+ * threading). A `break` whose loop lives entirely inside the `try` crosses no
+ * finally and must keep its direct edge; re-routing it anyway would force the
+ * only path to the in-try continuation through the finally, letting a finally
+ * redefinition falsely KILL in-loop definitions for the downstream
+ * reaching-defs pass (a taint false negative). A parallel stack cannot express
+ * that between-ness, which is why the frames live here.
+ */
+import type { CfgBuilder } from './cfg-builder.js';
+import type { CfgEdgeKind } from './types.js';
+/** A `finally` whose body any crossing jump must route through. */
+export interface FinalizerFrame {
+    readonly kind: 'finalizer';
+    /** Entry block of the finally body. */
+    readonly entry: number;
+    /**
+     * Completion legs registered by jumps that crossed this finally: once the
+     * owning try pops the frame, it wires `finally-exits → to` with `kind` for
+     * each entry. Mutated by the jump handlers via {@link ControlFlowContext}.
+     */
+    readonly pending: {
+        to: number;
+        kind: CfgEdgeKind;
+    }[];
+}
+/** A resolved jump: its ultimate target + the finallys it crosses (inner→outer). */
+export interface JumpResolution {
+    readonly target: number;
+    readonly finalizers: readonly FinalizerFrame[];
+}
+export declare class ControlFlowContext {
+    private readonly stack;
+    pushLoop(continueTo: number, breakTo: number, labels?: readonly string[]): void;
+    pushSwitch(breakTo: number, labels?: readonly string[]): void;
+    /** Push a labeled non-loop statement's break-target frame. */
+    pushLabeledBlock(breakTo: number, labels: readonly string[]): void;
+    /**
+     * Push a finalizer frame and return it — the owning `visitTry` keeps the
+     * reference to wire {@link FinalizerFrame.pending} after popping it.
+     */
+    pushFinalizer(entry: number): FinalizerFrame;
+    pop(): void;
+    /**
+     * 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?: string): JumpResolution | undefined;
+    /** Resolve a `continue`: like {@link resolveBreak} but only loop frames match. */
+    resolveContinue(label?: string): JumpResolution | undefined;
+    /** Every active finalizer, innermost first — what a `return` must cross. */
+    finalizersForReturn(): readonly FinalizerFrame[];
+    /**
+     * 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?: string): number | undefined;
+    /** Target block for a `continue` — same caveat as {@link breakTarget}. */
+    continueTarget(label?: string): number | undefined;
+    private resolve;
+}
+/**
+ * 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.
+ */
+export declare function wireJumpThroughFinalizers(builder: CfgBuilder, from: number, finalizers: readonly FinalizerFrame[], target: number, kind: 'return' | 'break' | 'continue'): void;
+/**
+ * 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.
+ */
+export declare function drainFinalizerPending(builder: CfgBuilder, frame: FinalizerFrame, finallyExits: readonly number[]): void;

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

@@ -0,0 +1,113 @@
+export 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);
+    }
+    /** 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;
+    }
+}
+/**
+ * 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.
+ */
+export 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.
+ */
+export function drainFinalizerPending(builder, frame, finallyExits) {
+    for (const p of frame.pending) {
+        builder.connect(finallyExits, p.to, p.kind);
+    }
+}

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

@@ -0,0 +1,144 @@
+/**
+ * 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 { BindingEntry, 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;
+/**
+ * Default per-function REACHING_DEF edge cap (#2082 M2 KTD9). 4000 mirrors
+ * Joern's per-method `maxNumberOfDefinitions` — the closest production prior
+ * art — but truncates-and-warns instead of silently skipping the function.
+ * Counts (defBlock, useBlock, binding) DEDUPED edges, not statement-level
+ * facts. `0` ⇒ unlimited; `undefined` ⇒ this default.
+ */
+export declare const DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION = 4000;
+/**
+ * Fact-materialization headroom over the edge cap (#2082 M2 U3/F3): facts are
+ * O(defs×uses) BY SPEC in merge-heavy code, and the edge cap alone bounds the
+ * GRAPH, not the per-function memory spike of materializing facts before
+ * dedup. {@link emitFileReachingDefs} hands `edgeCap × this` to
+ * `computeReachingDefs` as `maxFacts` (unlimited when the edge cap is 0) —
+ * single source of truth; the DEFAULT constant below is derived, never the
+ * mechanism.
+ */
+export declare const REACHING_DEF_FACTS_PER_EDGE_CAP = 4;
+/** Derived emit-path fact limit at the default edge cap (bench/doc anchor). */
+export declare const DEFAULT_PDG_MAX_REACHING_DEF_FACTS_PER_FUNCTION: number;
+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;
+}
+/**
+ * The single BasicBlock id template (module doc). Exported for the M3 taint
+ * emit path (taint/emit.ts), whose TAINTED/SANITIZES edges must address the
+ * SAME persisted block nodes — a re-derived copy of this template would
+ * silently dangle the moment either drifted.
+ */
+export declare const basicBlockId: (filePath: string, functionStartLine: number, functionStartColumn: number, blockIndex: number) => string;
+/**
+ * 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;
+/**
+ * Whether a structurally-valid CFG's M2 statement facts are safe to feed to
+ * the reaching-defs solver + REACHING_DEF id templating (#2082 U1/U4): the
+ * binding table's name/declLine/declColumn template into edge ids, and
+ * statement def/use indices must stay IN RANGE of the table (an escaping
+ * index would fabricate `undefined`-keyed ids). Deliberately SEPARATE from
+ * {@link isEmitSafeCfg}: malformed facts must cost only the function's
+ * REACHING_DEF projection — degrading to M1 behavior (CFG emitted, no facts)
+ * — never the BasicBlock/CFG layer itself.
+ */
+export declare const hasEmitSafeFacts: (cfg: FunctionCfg) => boolean;
+/**
+ * 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;
+export interface ReachingDefEmitResult {
+    /** Deduped (defBlock, useBlock, binding) edges persisted. */
+    edges: number;
+    /** Deduped edges dropped by the per-function edge cap. */
+    droppedEdges: number;
+    cappedFunctions: number;
+    /** Functions whose FACT materialization hit the solver's maxFacts limit. */
+    truncatedFunctions: number;
+    /** Functions whose facts failed {@link hasEmitSafeFacts} (CFG kept, facts skipped). */
+    malformedFactFunctions: number;
+    /** Total statement-level facts the solver produced (pre-dedup telemetry). */
+    facts: number;
+}
+/**
+ * Stable identity for a binding inside edge ids (#2082 M2 KTD3/KTD9):
+ * `name:declLine:declCol` for declared bindings, `name@module` for synthetic
+ * ones. Distinct same-name bindings never share a key; identifier characters
+ * cannot contain the id separators. Exported for the M3 taint emit path —
+ * TAINTED/SANITIZES ids key bindings with the same discipline.
+ */
+export declare const bindingKey: (b: BindingEntry) => string;
+/**
+ * Compute reaching definitions per function and persist the bounded
+ * REACHING_DEF projection (#2082 M2 U4).
+ *
+ * Facts are DEDUPED to (defBlock, useBlock, binding) before budgeting — the
+ * persisted columns (`from,to,type,confidence,reason,step`; relationship ids
+ * are in-memory-only, the CodeRelation table has no id column) cannot
+ * distinguish finer rows, so statement-indexed ids would only manufacture
+ * byte-identical duplicate rows that burn budget. Statement granularity lives
+ * in the in-memory {@link computeReachingDefs} result, which the M3 taint
+ * engine recomputes on demand — the budget here governs only this projection
+ * and can never drop a taint fact.
+ *
+ * R7 (no silent truncation) covers BOTH layers: the per-function edge cap AND
+ * the solver's fact-materialization limit (which can fire without the edge
+ * cap ever being reached, since dedup is many-to-one) each produce one
+ * unconditional `onWarn`. The edge-cap warn names the top bindings by fact
+ * count — overflow is almost always one variable, which is exactly the datum
+ * M3 tuning wants.
+ */
+export declare function emitFileReachingDefs(graph: KnowledgeGraph, cfgs: readonly FunctionCfg[], maxEdgesPerFunction?: number, onWarn?: (message: string) => void): ReachingDefEmitResult;