gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/core/ingestion/taint/call-summary-codec.js

@@ -0,0 +1,128 @@
+/**
+ * Call-summary reason codec (PDG FU-C, U-C2) — the ONE shared encoder/decoder
+ * for the bitset carried on persisted `CALL_SUMMARY` edges.
+ *
+ * A `CALL_SUMMARY` edge is a self-loop on a Function/Method/Constructor node
+ * recording that callee's RETURN-VALUE ASCENT: for each formal-parameter index,
+ * whether that parameter flows to the function's return value. The producer
+ * (the whole-program emit phase) writes this; a later consumer phase reads it to
+ * ascend a callee's return effect into the caller continuation. Two hand-rolled
+ * copies of a wire format drift — both sides MUST import from here (the same
+ * discipline `path-codec.ts` documents).
+ *
+ * ## Wire format (version `1`)
+ *
+ * ```
+ * 1|r:<hexbitset>[|<reserved-segment>…]
+ * ```
+ *
+ * - One-character version prefix ({@link CALL_SUMMARY_CODEC_VERSION}), then `|`,
+ *   then a `r:` (return) segment whose payload is the param→return bitset as a
+ *   lowercase hex string (LSB = formal index 0). Bit `i` set ⇒ formal parameter
+ *   `i` flows to the return value. An empty/zero bitset is the absence of any
+ *   return-flow (a sound EMPTY summary — never a false claim).
+ * - FORWARD COMPATIBILITY: the format reserves space for future facts via
+ *   additional trailing `|<tag>:<payload>` segments (planned: `o:` out-params,
+ *   `e:` exception ascent — both deferred: out-params need an alias model,
+ *   exception ascent needs try/catch CDG). The decoder accepts and ignores any
+ *   trailing segment whose tag it does not understand, so a future writer's
+ *   output stays decodable by today's reader (and vice-versa: today's reader
+ *   only requires the `r:` segment). Reserved tags MUST stay disjoint from `r`.
+ *
+ * ## Delimiter / round-trip discipline (mirrors path-codec KTD6)
+ *
+ * Every structural character (`|`, `:`, the version digit, hex digits `[0-9a-f]`)
+ * is printable ASCII, so the encoding survives `escapeCSVField ∘ sanitizeUTF8`
+ * (csv-generator.ts) byte-exact (pinned by the round-trip test). The hex payload
+ * is a non-negative integer rendered via BigInt, so the codec handles functions
+ * with arbitrarily many formal parameters without overflow.
+ *
+ * The decoder NEVER throws — anything malformed yields a typed failure, exactly
+ * like `decodeTaintPath`. A decode failure on the consumer side means "no usable
+ * ascent fact", which is the sound default (never claim a false return-flow).
+ */
+/** One-character format version prefix. Bump on any wire-format change. */
+export const CALL_SUMMARY_CODEC_VERSION = '1';
+/** Return-flow segment tag (`r:<hexbitset>`). */
+const RETURN_TAG = 'r';
+/** Hex payload charset (lowercase). */
+const HEX = /^[0-9a-f]+$/;
+/**
+ * Pack a set of return-flowing formal-parameter indices into a bitset (LSB =
+ * index 0). Negative or non-integer indices are ignored (defensive; the
+ * harvester only ever passes non-negative integers). Returns a `BigInt`.
+ */
+function packReturnBitset(returnFlowParams) {
+    let bits = 0n;
+    for (const idx of returnFlowParams) {
+        if (!Number.isInteger(idx) || idx < 0)
+            continue;
+        bits |= 1n << BigInt(idx);
+    }
+    return bits;
+}
+/**
+ * Encode the param→return ascent into the versioned `reason` wire string.
+ * Deterministic; never throws. `returnFlowParams` is the set of formal indices
+ * that flow to the return value (order/duplication irrelevant — the bitset
+ * canonicalises). An empty set encodes as `r:0` (an explicit empty summary).
+ */
+export function encodeCallSummary(returnFlowParams) {
+    const bits = packReturnBitset(returnFlowParams);
+    return `${CALL_SUMMARY_CODEC_VERSION}|${RETURN_TAG}:${bits.toString(16)}`;
+}
+/**
+ * Decode a `CALL_SUMMARY` reason wire string into its ascent facts. Returns a
+ * typed failure for anything that is not a well-formed version-`1` summary —
+ * never throws. Unknown trailing segments (future facts) are accepted and
+ * ignored (forward compatibility).
+ */
+export function decodeCallSummary(reason) {
+    if (typeof reason !== 'string' || reason.length === 0) {
+        return { ok: false, error: 'empty or non-string reason' };
+    }
+    // Read the version as the substring BEFORE the first '|' (NOT a single char):
+    // the wire format reserves multi-digit future versions, so a `12|…` writer must
+    // degrade to a clean 'unsupported version' typed-failure here, never silently
+    // parse as version '1' with a stray '2' segment. No '|' ⇒ the whole reason is a
+    // bare token with no body, which is malformed.
+    const firstSep = reason.indexOf('|');
+    if (firstSep === -1) {
+        return { ok: false, error: 'malformed body: expected a segment separator after the version' };
+    }
+    const version = reason.slice(0, firstSep);
+    if (version !== CALL_SUMMARY_CODEC_VERSION) {
+        return { ok: false, error: `unsupported call-summary version '${version}'` };
+    }
+    const segments = reason.slice(firstSep + 1).split('|');
+    let returnBits;
+    for (const seg of segments) {
+        const sep = seg.indexOf(':');
+        if (sep === -1) {
+            return { ok: false, error: `malformed segment '${seg}' (expected '<tag>:<payload>')` };
+        }
+        const tag = seg.slice(0, sep);
+        const payload = seg.slice(sep + 1);
+        if (tag === RETURN_TAG) {
+            if (!HEX.test(payload)) {
+                return { ok: false, error: `invalid return bitset '${payload}'` };
+            }
+            returnBits = BigInt(`0x${payload}`);
+        }
+        // Unknown tag (reserved future fact): accept + ignore for forward compat.
+    }
+    if (returnBits === undefined) {
+        return { ok: false, error: "missing required 'r:' return segment" };
+    }
+    // Unpack the bitset into ascending formal indices.
+    const returnFlowParams = [];
+    let bits = returnBits;
+    let idx = 0;
+    while (bits > 0n) {
+        if ((bits & 1n) === 1n)
+            returnFlowParams.push(idx);
+        bits >>= 1n;
+        idx++;
+    }
+    return { ok: true, version, returnFlowParams };
+}

package/dist/core/ingestion/taint/call-summary-emit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Call-summary emission (PDG FU-C, U-C3) — materialise `CALL_SUMMARY`.
+ *
+ * Persists each per-callee {@link CallSummary} as ONE `CALL_SUMMARY` self-loop
+ * edge on the callee Function/Method/Constructor node, with the param→return
+ * ASCENT bitset encoded in `reason` via the SHARED {@link call-summary-codec}
+ * (never a second hand-rolled wire format). A later consumer phase decodes it to
+ * ascend a callee's return effect into the caller continuation.
+ *
+ * The self-loop shape matches the schema (Function→Function / Method→Method /
+ * Constructor→Constructor pairs already exist from the M0 TAINT_PATH work — zero
+ * new schema pairs). Like `TAINT_PATH`/`TAINTED`, `CALL_SUMMARY` stays OUT of
+ * `VALID_RELATION_TYPES` and the web schema — it is an internal PDG-engine edge.
+ *
+ * Boundedness mirrors the M4 interproc emit driver: dedup by the deterministic
+ * edge id, an optional per-run cap, and unconditional truncate-and-warn.
+ */
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { CallSummary } from './call-summary-model.js';
+/** Confidence stamped on `CALL_SUMMARY` edges. A summary is a context-
+ *  insensitive whole-parameter abstraction — a coarser signal than a resolved
+ *  `CALLS` edge, so kept below 1.0 (mirrors the interproc TAINT_PATH posture). */
+export declare const CALL_SUMMARY_CONFIDENCE = 0.6;
+/** Default per-run cap on emitted `CALL_SUMMARY` edges. `0` ⇒ unlimited. */
+export declare const DEFAULT_PDG_MAX_CALL_SUMMARY_EDGES = 0;
+export interface CallSummaryEmitLimits {
+    /** Max `CALL_SUMMARY` edges per run (post-dedup). `undefined`/0 ⇒ unlimited. */
+    readonly maxEdges?: number;
+}
+export interface CallSummaryEmitResult {
+    /** CALL_SUMMARY edges persisted. */
+    edgesEmitted: number;
+    /** Summaries dropped by the per-run cap. */
+    edgesDropped: number;
+    /** Summaries skipped because the callee node was missing from the graph. */
+    skippedMissingEndpoint: number;
+}
+/**
+ * Persist per-callee summaries as `CALL_SUMMARY` self-loop edges. `summaries` is
+ * assumed deterministically ordered (the harvest sorts `returnFlowParams`).
+ * Never throws on valid input.
+ */
+export declare function emitCallSummaries(graph: KnowledgeGraph, summaries: readonly CallSummary[], limits?: CallSummaryEmitLimits, onWarn?: (message: string) => void): CallSummaryEmitResult;

package/dist/core/ingestion/taint/call-summary-emit.js

@@ -0,0 +1,70 @@
+/**
+ * Call-summary emission (PDG FU-C, U-C3) — materialise `CALL_SUMMARY`.
+ *
+ * Persists each per-callee {@link CallSummary} as ONE `CALL_SUMMARY` self-loop
+ * edge on the callee Function/Method/Constructor node, with the param→return
+ * ASCENT bitset encoded in `reason` via the SHARED {@link call-summary-codec}
+ * (never a second hand-rolled wire format). A later consumer phase decodes it to
+ * ascend a callee's return effect into the caller continuation.
+ *
+ * The self-loop shape matches the schema (Function→Function / Method→Method /
+ * Constructor→Constructor pairs already exist from the M0 TAINT_PATH work — zero
+ * new schema pairs). Like `TAINT_PATH`/`TAINTED`, `CALL_SUMMARY` stays OUT of
+ * `VALID_RELATION_TYPES` and the web schema — it is an internal PDG-engine edge.
+ *
+ * Boundedness mirrors the M4 interproc emit driver: dedup by the deterministic
+ * edge id, an optional per-run cap, and unconditional truncate-and-warn.
+ */
+import { encodeCallSummary } from './call-summary-codec.js';
+/** Confidence stamped on `CALL_SUMMARY` edges. A summary is a context-
+ *  insensitive whole-parameter abstraction — a coarser signal than a resolved
+ *  `CALLS` edge, so kept below 1.0 (mirrors the interproc TAINT_PATH posture). */
+export const CALL_SUMMARY_CONFIDENCE = 0.6;
+/** Default per-run cap on emitted `CALL_SUMMARY` edges. `0` ⇒ unlimited. */
+export const DEFAULT_PDG_MAX_CALL_SUMMARY_EDGES = 0;
+/**
+ * Persist per-callee summaries as `CALL_SUMMARY` self-loop edges. `summaries` is
+ * assumed deterministically ordered (the harvest sorts `returnFlowParams`).
+ * Never throws on valid input.
+ */
+export function emitCallSummaries(graph, summaries, limits, onWarn) {
+    const result = {
+        edgesEmitted: 0,
+        edgesDropped: 0,
+        skippedMissingEndpoint: 0,
+    };
+    const maxEdges = limits?.maxEdges && limits.maxEdges > 0 ? limits.maxEdges : Infinity;
+    const seen = new Set();
+    for (const summary of summaries) {
+        if (result.edgesEmitted >= maxEdges) {
+            result.edgesDropped++;
+            continue;
+        }
+        const node = graph.getNode(summary.fnId);
+        if (!node) {
+            result.skippedMissingEndpoint++;
+            continue;
+        }
+        // One self-loop edge per callee; dedup by the callee id (the harvest already
+        // produces at most one summary per resolved fnId, but a same-line anchor
+        // could in principle map two CFGs to one id — the Set keeps it idempotent).
+        const id = `rel:CALL_SUMMARY:${summary.fnId}`;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        graph.addRelationship({
+            id,
+            sourceId: summary.fnId,
+            targetId: summary.fnId,
+            type: 'CALL_SUMMARY',
+            confidence: CALL_SUMMARY_CONFIDENCE,
+            reason: encodeCallSummary(summary.returnFlowParams),
+        });
+        result.edgesEmitted++;
+    }
+    if (result.edgesDropped > 0) {
+        onWarn?.(`[call-summary] ${result.edgesDropped} CALL_SUMMARY edge(s) dropped by the ` +
+            `per-run cap (${maxEdges})`);
+    }
+    return result;
+}

package/dist/core/ingestion/taint/call-summary-harvest.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Per-function dependence-SUMMARY harvest (PDG FU-C, U-C2).
+ *
+ * Pure, deterministic derivation of one function's RETURN-VALUE ASCENT — which
+ * formal-parameter indices flow to the function's return value — from the SAME
+ * substrate the M2/M3 passes consume: the reaching-definition facts
+ * (`computeReachingDefs`) over the function's CFG. No graph, no I/O, no logger;
+ * mirrors the {@link harvestFunctionSummary} (taint) contract so snapshot tests
+ * and the version stamp stay stable. Runs IN-PHASE inside the scope-resolution
+ * pdg window where the RD facts are materialised (reusing them — zero new
+ * worker/CFG work, so NO parse-cache pdg:N bump).
+ *
+ * ## Return-site identification (language-agnostic, soundness-first)
+ *
+ * Return statements are identified STRUCTURALLY via the M2 edge-kind invariant:
+ * the SOURCE block of every CFG edge of kind `return` terminates in the return
+ * jump, so that block's LAST statement is the `return <expr>` — its `uses` are
+ * the returned bindings. A `return;` with no value has empty uses (contributes
+ * nothing). For languages whose visitor models IMPLICIT returns (arrow-function
+ * expression bodies, Python last-expression), the CFG emits a `return` edge to
+ * EXIT whose source block's last statement carries the returned expression's
+ * `uses`, so those flow through the same path with no language-specific code.
+ *
+ * SOUNDNESS = never claim a false return-flow: when a function has NO `return`
+ * CFG edge (a language/shape with no robust exit notion modelled, or a void
+ * function), `returnUseStmtKeys` is empty and the harvest emits an EMPTY summary
+ * — the absence of a fact, never a wrong one.
+ *
+ * ## Param → return reachability
+ *
+ * Each formal parameter is seeded as a value at its entry def point(s); forward
+ * reachability over the def→use facts marks the param's index as return-flowing
+ * the moment a tainted binding it produced (under the M3 statement-level floor:
+ * a statement using a value taints all of its defs/mayDefs) is among a
+ * return-use statement's `uses`. The recorded edge is from an ACTUAL binding
+ * occurrence in a return's uses — never the floor — keeping the recorded fact
+ * precise even though onward propagation over-approximates.
+ *
+ * ## Formal-position soundness — destructured / rest params
+ *
+ * The consumer reads `returnFlowParams` POSITIONALLY (call-site arg position →
+ * same-index formal → bitset), so each recorded index MUST be the 0-based
+ * ENCLOSING FORMAL position, never the flattened binding ordinal. A
+ * destructured/rest formal binds several names: `function f({a, b}, c)` flattens
+ * to bindings a, b, c, whose ORDINALS are 0, 1, 2 — but the formal positions are
+ * 0, 0, 1. Recording an ordinal would misattribute `b`'s return-flow to formal
+ * `c` (a FALSE return-flow claim, not a miss). To stay sound we key every
+ * recorded index on {@link BindingEntry.formalIndex} (the producer-supplied
+ * enclosing-formal position, identical for every inner name of one formal).
+ *
+ * CONSERVATIVE FALLBACK: a producer that does not yet supply `formalIndex` on
+ * its param bindings leaves the harvest unable to prove the ordinal equals the
+ * formal slot, so the harvest emits an EMPTY summary for that function — a
+ * documented MISS (loses ascent), NEVER a false claim. Functions whose every
+ * param binding carries `formalIndex` get the precise formal positions.
+ */
+import type { FunctionCfg } from '../cfg/types.js';
+import { type FunctionDefUse } from '../cfg/reaching-defs.js';
+/** The own-facts portion of a call summary (fnId/anchor added by the caller). */
+export interface HarvestedCallSummaryFacts {
+    readonly paramCount: number;
+    /** Sorted, de-duplicated formal-parameter indices that flow to the return. */
+    readonly returnFlowParams: readonly number[];
+}
+export interface CallSummaryHarvestResult {
+    /** `computed` — facts derived; `coverage-gap` — the RD solver was not
+     *  `computed`, so no summary is produced (consistent with the taint harvest). */
+    readonly status: 'computed' | 'coverage-gap';
+    readonly gapReason?: FunctionDefUse['status'];
+    readonly facts: HarvestedCallSummaryFacts;
+}
+/**
+ * Harvest the RETURN-VALUE ASCENT facts for one function. PRECONDITION: `cfg`
+ * is `isEmitSafeCfg`-filtered and `defUse` was computed from it (the caller
+ * gates exactly as the taint harvest path does).
+ */
+export declare function harvestCallSummary(cfg: FunctionCfg, defUse: FunctionDefUse): CallSummaryHarvestResult;

package/dist/core/ingestion/taint/call-summary-harvest.js

@@ -0,0 +1,179 @@
+/**
+ * Per-function dependence-SUMMARY harvest (PDG FU-C, U-C2).
+ *
+ * Pure, deterministic derivation of one function's RETURN-VALUE ASCENT — which
+ * formal-parameter indices flow to the function's return value — from the SAME
+ * substrate the M2/M3 passes consume: the reaching-definition facts
+ * (`computeReachingDefs`) over the function's CFG. No graph, no I/O, no logger;
+ * mirrors the {@link harvestFunctionSummary} (taint) contract so snapshot tests
+ * and the version stamp stay stable. Runs IN-PHASE inside the scope-resolution
+ * pdg window where the RD facts are materialised (reusing them — zero new
+ * worker/CFG work, so NO parse-cache pdg:N bump).
+ *
+ * ## Return-site identification (language-agnostic, soundness-first)
+ *
+ * Return statements are identified STRUCTURALLY via the M2 edge-kind invariant:
+ * the SOURCE block of every CFG edge of kind `return` terminates in the return
+ * jump, so that block's LAST statement is the `return <expr>` — its `uses` are
+ * the returned bindings. A `return;` with no value has empty uses (contributes
+ * nothing). For languages whose visitor models IMPLICIT returns (arrow-function
+ * expression bodies, Python last-expression), the CFG emits a `return` edge to
+ * EXIT whose source block's last statement carries the returned expression's
+ * `uses`, so those flow through the same path with no language-specific code.
+ *
+ * SOUNDNESS = never claim a false return-flow: when a function has NO `return`
+ * CFG edge (a language/shape with no robust exit notion modelled, or a void
+ * function), `returnUseStmtKeys` is empty and the harvest emits an EMPTY summary
+ * — the absence of a fact, never a wrong one.
+ *
+ * ## Param → return reachability
+ *
+ * Each formal parameter is seeded as a value at its entry def point(s); forward
+ * reachability over the def→use facts marks the param's index as return-flowing
+ * the moment a tainted binding it produced (under the M3 statement-level floor:
+ * a statement using a value taints all of its defs/mayDefs) is among a
+ * return-use statement's `uses`. The recorded edge is from an ACTUAL binding
+ * occurrence in a return's uses — never the floor — keeping the recorded fact
+ * precise even though onward propagation over-approximates.
+ *
+ * ## Formal-position soundness — destructured / rest params
+ *
+ * The consumer reads `returnFlowParams` POSITIONALLY (call-site arg position →
+ * same-index formal → bitset), so each recorded index MUST be the 0-based
+ * ENCLOSING FORMAL position, never the flattened binding ordinal. A
+ * destructured/rest formal binds several names: `function f({a, b}, c)` flattens
+ * to bindings a, b, c, whose ORDINALS are 0, 1, 2 — but the formal positions are
+ * 0, 0, 1. Recording an ordinal would misattribute `b`'s return-flow to formal
+ * `c` (a FALSE return-flow claim, not a miss). To stay sound we key every
+ * recorded index on {@link BindingEntry.formalIndex} (the producer-supplied
+ * enclosing-formal position, identical for every inner name of one formal).
+ *
+ * CONSERVATIVE FALLBACK: a producer that does not yet supply `formalIndex` on
+ * its param bindings leaves the harvest unable to prove the ordinal equals the
+ * formal slot, so the harvest emits an EMPTY summary for that function — a
+ * documented MISS (loses ascent), NEVER a false claim. Functions whose every
+ * param binding carries `formalIndex` get the precise formal positions.
+ */
+import { pointKey } from '../cfg/reaching-defs.js';
+const EMPTY_FACTS = { paramCount: 0, returnFlowParams: [] };
+/**
+ * Harvest the RETURN-VALUE ASCENT facts for one function. PRECONDITION: `cfg`
+ * is `isEmitSafeCfg`-filtered and `defUse` was computed from it (the caller
+ * gates exactly as the taint harvest path does).
+ */
+export function harvestCallSummary(cfg, defUse) {
+    if (defUse.status !== 'computed') {
+        return { status: 'coverage-gap', gapReason: defUse.status, facts: EMPTY_FACTS };
+    }
+    const bindings = defUse.bindings;
+    // ── param bindings → ENCLOSING FORMAL position ────────────────────────────
+    // SOUNDNESS (FU-C): the consumer joins `returnFlowParams` positionally against
+    // call-site arg positions, so each index MUST be the 0-based enclosing formal
+    // position — `BindingEntry.formalIndex`, which a destructured/rest formal hands
+    // identically to every inner name. The flattened binding ORDINAL is NOT a safe
+    // substitute (`function f({a, b}, c)` ⇒ b's ordinal 1 collides with formal c).
+    const paramBindings = bindings
+        .map((b, idx) => ({ b, idx }))
+        .filter((e) => e.b.kind === 'param')
+        .sort((a, b) => a.b.declLine - b.b.declLine || a.b.declColumn - b.b.declColumn);
+    // CONSERVATIVE FALLBACK: build binding-index → enclosing-formal-position only
+    // while every param binding supplies `formalIndex` (narrowed per-entry, no
+    // assertion). If ANY lacks it, the ordinal-vs-formal mapping is unprovable, so
+    // the summary degrades to EMPTY below (a documented MISS, never a false claim).
+    const paramCount = paramBindings.length;
+    const paramFormalOf = new Map();
+    let missingFormalIndex = false;
+    for (const e of paramBindings) {
+        const formalIndex = e.b.formalIndex;
+        if (formalIndex === undefined) {
+            missingFormalIndex = true;
+            break;
+        }
+        paramFormalOf.set(e.idx, formalIndex);
+    }
+    // ── return points: source block of every `return` CFG edge ────────────────
+    // The M2 edge-kind invariant: a `return` edge's SOURCE block terminates in the
+    // return jump, so its LAST statement is `return <expr>` — its `uses` are the
+    // returned bindings. (`return;` with no value has empty uses.) No `return`
+    // edge ⇒ empty set ⇒ EMPTY summary (sound — never a false return-flow claim).
+    const returnUseStmtKeys = new Set();
+    for (const e of cfg.edges) {
+        if (e.kind !== 'return')
+            continue;
+        const block = cfg.blocks[e.from];
+        const stmts = block?.statements;
+        if (!stmts || stmts.length === 0)
+            continue;
+        returnUseStmtKeys.add(`${e.from}:${stmts.length - 1}`);
+    }
+    // Fast exit: no params, no return sites, or an unprovable formal mapping
+    // (conservative fallback) ⇒ nothing safely flows to the return.
+    if (paramCount === 0 || returnUseStmtKeys.size === 0 || missingFormalIndex) {
+        return { status: 'computed', facts: { paramCount, returnFlowParams: [] } };
+    }
+    const stmtAt = (p) => cfg.blocks[p.blockIndex]?.statements?.[p.stmtIndex];
+    // ── def→use index ─────────────────────────────────────────────────────────
+    const factsByDef = new Map();
+    for (const f of defUse.facts) {
+        const key = `${f.bindingIdx}:${pointKey(f.def)}`;
+        const list = factsByDef.get(key);
+        const entry = { bindingIdx: f.bindingIdx, use: f.use };
+        if (list)
+            list.push(entry);
+        else
+            factsByDef.set(key, [entry]);
+    }
+    // ── seeds: each param at its entry def point(s) ────────────────────────────
+    const queue = [];
+    const visited = new Set();
+    const enqueue = (v) => {
+        const key = `${v.paramIdx}:${v.bindingIdx}:${pointKey(v.point)}`;
+        if (visited.has(key))
+            return;
+        visited.add(key);
+        queue.push(v);
+    };
+    for (const { idx } of paramBindings) {
+        // 0-based ENCLOSING formal position — guaranteed present (the missing-formal
+        // case returned EMPTY above), but guard rather than assert to stay `any`-free.
+        const paramIdx = paramFormalOf.get(idx);
+        if (paramIdx === undefined)
+            continue;
+        for (const f of defUse.facts) {
+            if (f.bindingIdx === idx && f.def.blockIndex === cfg.entryIndex) {
+                enqueue({ bindingIdx: idx, point: f.def, paramIdx });
+            }
+        }
+    }
+    // ── forward reachability ──────────────────────────────────────────────────
+    const returnFlow = new Set();
+    let head = 0;
+    while (head < queue.length) {
+        const v = queue[head++];
+        const b = v.bindingIdx;
+        for (const fact of factsByDef.get(`${b}:${pointKey(v.point)}`) ?? []) {
+            const useStmt = stmtAt(fact.use);
+            if (!useStmt)
+                continue;
+            const useKey = `${fact.use.blockIndex}:${fact.use.stmtIndex}`;
+            // (1) return reach: the param's value is among a return-use's `uses`.
+            if (returnUseStmtKeys.has(useKey) && useStmt.uses.includes(b)) {
+                returnFlow.add(v.paramIdx);
+            }
+            // (2) onward floor: this statement's defs/mayDefs carry the value onward.
+            for (const d of [...useStmt.defs, ...(useStmt.mayDefs ?? [])]) {
+                enqueue({
+                    bindingIdx: d,
+                    point: {
+                        blockIndex: fact.use.blockIndex,
+                        stmtIndex: fact.use.stmtIndex,
+                        line: useStmt.line,
+                    },
+                    paramIdx: v.paramIdx,
+                });
+            }
+        }
+    }
+    const returnFlowParams = [...returnFlow].sort((a, b) => a - b);
+    return { status: 'computed', facts: { paramCount, returnFlowParams } };
+}

package/dist/core/ingestion/taint/call-summary-model.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-callee dependence SUMMARY model (PDG FU-C, U-C2).
+ *
+ * A {@link CallSummary} is the compact, context-insensitive abstraction of one
+ * function's RETURN-VALUE ASCENT: which formal-parameter indices flow to the
+ * function's return value. It is the data-dependence twin of the M4
+ * {@link FunctionSummary} (taint), but for the *slicing* engine rather than the
+ * taint engine — a later consumer phase uses it to ascend a callee's return
+ * effect into the caller continuation (the documented no-ascent false negative).
+ *
+ * ## Scope (first cut — RETURN-VALUE ONLY)
+ *
+ * WHOLE-PARAMETER granularity. Ports are `param i` → `return`. Out-params /
+ * mutated args (need an alias model) and exception ascent (need try/catch CDG)
+ * are DEFERRED — the {@link call-summary-codec} reserves wire-format space for
+ * them so they can land without a cache-namespace bump.
+ *
+ * ## Plain-data discipline
+ *
+ * A summary is a JSON-plain value type (no functions, class instances, Maps, or
+ * Symbols) so it survives `RunScopeResolutionStats` → `ScopeResolutionOutput`
+ * threading unchanged — the same `Cloneable` constraint the CFG side channel and
+ * the taint {@link FunctionSummary} obey.
+ */
+/** Source-relative parameter index (0-based, declaration order). */
+export type ParamIndex = number;
+/**
+ * The dependence abstraction of one function. The resolved Function/Method/
+ * Constructor graph node id this summary describes, plus the set of formal
+ * parameters whose value flows to the return.
+ */
+export interface CallSummary {
+    /** The resolved `Function`/`Method`/`Constructor` graph node id. */
+    readonly fnId: string;
+    /** Repo-relative source path (carried for diagnostics + the anchor join). */
+    readonly filePath: string;
+    /** 1-based function start line (mirrors `FunctionCfg.functionStartLine`). */
+    readonly startLine: number;
+    /** Number of declared formal parameters (port arity). */
+    readonly paramCount: number;
+    /**
+     * Sorted, de-duplicated formal-parameter indices that flow to the function's
+     * return value (ascending). Empty ⇒ no parameter reaches the return (a sound
+     * EMPTY summary — never a false claim).
+     */
+    readonly returnFlowParams: readonly ParamIndex[];
+}

package/dist/core/ingestion/taint/call-summary-model.js

@@ -0,0 +1,25 @@
+/**
+ * Per-callee dependence SUMMARY model (PDG FU-C, U-C2).
+ *
+ * A {@link CallSummary} is the compact, context-insensitive abstraction of one
+ * function's RETURN-VALUE ASCENT: which formal-parameter indices flow to the
+ * function's return value. It is the data-dependence twin of the M4
+ * {@link FunctionSummary} (taint), but for the *slicing* engine rather than the
+ * taint engine — a later consumer phase uses it to ascend a callee's return
+ * effect into the caller continuation (the documented no-ascent false negative).
+ *
+ * ## Scope (first cut — RETURN-VALUE ONLY)
+ *
+ * WHOLE-PARAMETER granularity. Ports are `param i` → `return`. Out-params /
+ * mutated args (need an alias model) and exception ascent (need try/catch CDG)
+ * are DEFERRED — the {@link call-summary-codec} reserves wire-format space for
+ * them so they can land without a cache-namespace bump.
+ *
+ * ## Plain-data discipline
+ *
+ * A summary is a JSON-plain value type (no functions, class instances, Maps, or
+ * Symbols) so it survives `RunScopeResolutionStats` → `ScopeResolutionOutput`
+ * threading unchanged — the same `Cloneable` constraint the CFG side channel and
+ * the taint {@link FunctionSummary} obey.
+ */
+export {};