@clear-capabilities/agentic-security-scanner 0.183.1 → 0.185.0

package/src/lineage/scc-solver.js

@@ -0,0 +1,186 @@
+// Recursive-component solver for the lineage driver (DAG-01, R01.3 to R01.5).
+//
+// Pure: no I/O, no clock of its own (a budget is an injected callback), and
+// no import of any analysis engine. `driver.js` supplies the per-function
+// analysis; tests supply synthetic transfer functions.
+//
+// ## Fact domain (R01.4)
+//
+// A function summary is a finite set of facts:
+//   - `ret:<dataElementId>`                 the return value carries the id
+//   - `mut:<paramPath>:<dataElementId>`     the parameter access path
+//                                           `paramPath` is mutated to carry
+//                                           the id
+// The id universe is the set of data-element ids that appear in the entry
+// states of the analyzed contexts and the program text (finite per run). The
+// path universe is the set of syntactic parameter access paths, additionally
+// BOUNDED by `maxPathDepth` (default 6 segments): a deeper path is folded to
+// its depth-bounded prefix, which only adds the id to a coarser path (an
+// over-approximation) and is recorded as the widening reason
+// `path-depth-cap`.
+//
+// ## Join and monotonicity
+//
+// The join is set union per fact family. The solver stores
+// `next = join(previous, analyze(previous))`, so the per-function summary
+// sequence is an ascending chain in a finite lattice whether or not the
+// underlying analysis is itself monotone. An ascending chain over a finite
+// lattice stabilizes, so the iteration terminates; `maxRounds` is a second,
+// independent safety bound. A fixed point reached here is the least fixed
+// point of the joined transfer function, which is exactly what a naive
+// exhaustive iteration to stability computes (the reference solver in the
+// tests).
+//
+// ## What converged means
+//
+// `converged: true` means a full round changed no member summary AND at least
+// two rounds ran (round one is compared with the bottom seed, which is not an
+// analysis result). It does not mean the program is safe: summaries
+// under-approximate whatever the analysis does not model. If a budget stops
+// the iteration, a round cap is hit, or a member is never analyzed, the
+// result is `converged: false` with the remaining frontier listed, and the
+// last iterate must be treated as partial, never as a conservative proof.
+
+function cmp(a, b) { return a < b ? -1 : a > b ? 1 : 0; }
+
+export const DEFAULT_MAX_PATH_DEPTH = 6;
+export const DEFAULT_MAX_ROUNDS = 32;
+export const DEFAULT_MAX_CHANGED_FACTS = 1000;
+
+function foldPath(path, maxDepth) {
+  const segs = String(path).split('.');
+  if (segs.length <= maxDepth) return null;
+  return segs.slice(0, maxDepth).join('.');
+}
+
+// Joins two field-identity summaries. Returns `{ summary, reasons }`.
+// `reasons` lists widening reasons applied by this join (deterministic order).
+export function joinFieldSummaries(prev, next, opts = {}) {
+  const maxDepth = opts.maxPathDepth ?? DEFAULT_MAX_PATH_DEPTH;
+  const reasons = new Set();
+  const returnFlat = new Set(prev ? prev.returnFlat : []);
+  for (const id of next.returnFlat) returnFlat.add(id);
+
+  const mutatedParams = new Map();
+  const addMut = (path, ids) => {
+    const folded = foldPath(path, maxDepth);
+    const key = folded ?? path;
+    if (folded !== null) reasons.add('path-depth-cap');
+    let set = mutatedParams.get(key);
+    if (!set) { set = new Set(); mutatedParams.set(key, set); }
+    for (const id of ids) set.add(id);
+  };
+  if (prev) for (const [p, ids] of prev.mutatedParams) addMut(p, ids);
+  for (const [p, ids] of next.mutatedParams) addMut(p, ids);
+
+  const returnByPath = new Map();
+  for (const src of [prev && prev.returnByPath, next.returnByPath]) {
+    if (!src) continue;
+    for (const [p, ids] of src) {
+      const set = returnByPath.get(p) ?? new Set();
+      for (const id of ids) set.add(id);
+      returnByPath.set(p, set);
+    }
+  }
+  const summary = { returnFlat, returnByPath, mutatedParams, widenings: next.widenings ?? [] };
+  if (next.degradedReason) summary.degradedReason = next.degradedReason;
+  return { summary, reasons: [...reasons].sort(cmp) };
+}
+
+export function fieldFacts(summary) {
+  const out = [];
+  if (!summary) return out;
+  for (const id of summary.returnFlat) out.push(`ret:${id}`);
+  for (const [p, ids] of summary.mutatedParams) for (const id of ids) out.push(`mut:${p}:${id}`);
+  return out.sort(cmp);
+}
+
+export function bottomFieldSummary() {
+  return { returnFlat: new Set(), returnByPath: new Map(), mutatedParams: new Map(), widenings: [] };
+}
+
+function factsEqual(a, b) {
+  const fa = fieldFacts(a);
+  const fb = fieldFacts(b);
+  if (fa.length !== fb.length) return false;
+  for (let i = 0; i < fa.length; i++) if (fa[i] !== fb[i]) return false;
+  return true;
+}
+
+// Solves one recursive component.
+//
+//   members            sorted qids in the component
+//   analyze(qid)       runs one analysis of `qid` against the currently
+//                      published summaries and returns a RAW summary
+//   publish(qid, s)    makes `s` the summary other members will read
+//   bottom(qid)        initial summary (default: empty)
+//   beforeRound(round) hook, called before each round
+//   shouldStop()       returns a reason string to stop, or a falsy value
+//   maxRounds, maxPathDepth, maxChangedFacts   bounds
+//
+// Returns { converged, rounds, changedFacts, changedFactsTotal,
+//           changedFactsTruncated, wideningReasons, stoppedBy,
+//           remainingFrontier, summaries }.
+export function solveRecursiveComponent(args) {
+  const members = [...args.members].sort(cmp);
+  const maxRounds = args.maxRounds ?? DEFAULT_MAX_ROUNDS;
+  const maxChanged = args.maxChangedFacts ?? DEFAULT_MAX_CHANGED_FACTS;
+  const bottom = args.bottom || (() => bottomFieldSummary());
+  const current = new Map();
+  for (const q of members) {
+    const b = bottom(q);
+    current.set(q, b);
+    args.publish(q, b);
+  }
+  const reasons = new Set();
+  const changedFacts = [];
+  let changedTotal = 0;
+  let rounds = 0;
+  let converged = false;
+  let stoppedBy = null;
+  let analyzedThisRound = new Set();
+
+  while (rounds < maxRounds) {
+    rounds++;
+    if (args.beforeRound) args.beforeRound(rounds);
+    let changedInRound = false;
+    analyzedThisRound = new Set();
+    for (const q of members) {
+      const stop = args.shouldStop ? args.shouldStop() : null;
+      if (stop) { stoppedBy = stop; break; }
+      const prev = current.get(q);
+      const raw = args.analyze(q);
+      analyzedThisRound.add(q);
+      const { summary: joined, reasons: rs } = joinFieldSummaries(prev, raw, { maxPathDepth: args.maxPathDepth });
+      for (const r of rs) reasons.add(r);
+      if (!factsEqual(prev, joined)) {
+        changedInRound = true;
+        const before = new Set(fieldFacts(prev));
+        for (const f of fieldFacts(joined)) {
+          if (before.has(f)) continue;
+          changedTotal++;
+          if (changedFacts.length < maxChanged) changedFacts.push({ round: rounds, qid: q, fact: f });
+        }
+      }
+      current.set(q, joined);
+      args.publish(q, joined);
+    }
+    if (stoppedBy) { rounds = analyzedThisRound.size === 0 && rounds > 0 ? rounds - 1 : rounds; break; }
+    if (!changedInRound && rounds >= 2) { converged = true; break; }
+  }
+  if (!converged && !stoppedBy && rounds >= maxRounds) {
+    reasons.add('round-cap');
+    stoppedBy = 'round-cap';
+  }
+  return {
+    converged,
+    rounds,
+    changedFacts,
+    changedFactsTotal: changedTotal,
+    changedFactsTruncated: changedTotal > changedFacts.length,
+    wideningReasons: [...reasons].sort(cmp),
+    stoppedBy,
+    remainingFrontier: converged ? [] : members.slice(),
+    summaries: current,
+  };
+}

package/src/lineage/smt-orchestrator.js

@@ -0,0 +1,138 @@
+//
+// smt-orchestrator.js: the optional solver path for witness conditions (DAG-04, R04.3 / R04.4).
+//
+// The bounded abstract domains in path-predicates.js decide first. A solver is consulted only when they
+// say `unknown`, and only through this module, which makes the call:
+//   * awaited: the caller gets one settled result, never a dangling promise;
+//   * time-bounded: a deadline races the solver, and a solver that ignores it is still released;
+//   * cancellable: an AbortSignal from the caller and the module's own deadline both abort the solver's
+//     signal, and a late settlement from an abandoned solver is swallowed;
+//   * honest: no solver reports `unsupported`, a deadline reports `timeout`, a malformed or failing solver
+//     reports `unknown`. None of these ever drops or downgrades the finding. The abstract result is kept.
+//
+// No solver ships here and no dependency is added. `noSolver` is the default stub. A real solver is an
+// object with `{ name, version?, available?, check(problem, { signal }) -> Promise<{ result }> }` where
+// `result` is 'sat' | 'unsat' | 'unknown'. `problem` is the solver-neutral view from `toSolverProblem`.
+// Satisfiability never implies exploitability.
+
+import { evaluateWitnessConditions, toSolverProblem, PATH_PREDICATE_VERSION, SATISFIABILITY_NOTE } from './path-predicates.js';
+
+export const SOLVER_DEFAULT_TIMEOUT_MS = 1000;
+export const SOLVER_TIMEOUT_MAX_MS = 60_000;
+
+/** The default: a solver that is not there. */
+export const noSolver = Object.freeze({
+  name: 'none', version: null, available: false,
+  async check() { return { result: 'unsupported' }; },
+});
+
+const MAP = Object.freeze({ sat: 'feasible-model', unsat: 'infeasible-under-model', unknown: 'unknown' });
+
+/** Render the problem as SMT-LIB 2 text for a solver adapter that wants text. Opaque predicates become comments. */
+export function toSmtLib(problem) {
+  const lines = ['(set-logic ALL)'];
+  const sym = (s) => `|${String(s).replace(/\|/g, '_')}|`;
+  const num = (side) => (side.var ? sym(side.var) : String(side.const));
+  for (const v of problem.vars) lines.push(`(declare-const ${sym(v)} Int)`);
+  for (const a of problem.assertions) {
+    const alts = a.alternatives.map((alt) => {
+      const parts = alt.map((l) => {
+        if (l.t === 'num') {
+          const op = { '<': '<', '<=': '<=', '>': '>', '>=': '>=', '==': '=', '===': '=', '!=': 'distinct', '!==': 'distinct' }[l.op];
+          return `(${op} ${num(l.left)} ${num(l.right)})`;
+        }
+        if (l.t === 'eq') return `(${l.equal ? '=' : 'distinct'} ${sym(l.var)} ${JSON.stringify(l.value)})`;
+        if (l.t === 'bool') return l.truth ? 'true' : 'false';
+        return 'true';
+      });
+      return parts.length === 1 ? parts[0] : `(and ${parts.join(' ') || 'true'})`;
+    });
+    lines.push(`; ${a.ref}`);
+    lines.push(`(assert ${alts.length === 0 ? 'false' : alts.length === 1 ? alts[0] : `(or ${alts.join(' ')})`})`);
+  }
+  lines.push('(check-sat)');
+  return lines.join('\n');
+}
+
+function boundedTimeout(ms) {
+  if (ms === undefined) return SOLVER_DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(ms) || ms < 0 || ms > SOLVER_TIMEOUT_MAX_MS) return null;
+  return Math.floor(ms);
+}
+
+/**
+ * Ask a solver about the collected conditions. Always resolves; never throws.
+ *
+ * @returns {Promise<{status:string, reasons:string[], solver:object, elapsedMs:number, semanticsVersion:string, limitations:string[]}>}
+ */
+export async function checkWithSolver(collected, { solver = noSolver, timeoutMs, signal, now = Date.now } = {}) {
+  const started = now();
+  const info = { name: solver?.name ?? 'unknown', version: solver?.version ?? null };
+  const out = (status, reasons, extra = {}) => ({
+    status, reasons, solver: info, elapsedMs: now() - started, semanticsVersion: PATH_PREDICATE_VERSION,
+    satisfiabilityNote: SATISFIABILITY_NOTE,
+    limitations: ['A solver result is relative to the encoded conditions, not to the running program.', ...(extra.limitations ?? [])],
+    ...(extra.model ? { model: extra.model } : {}),
+  });
+  const tmo = boundedTimeout(timeoutMs);
+  if (tmo === null) return out('unknown', ['invalid-timeout']);
+  if (!solver || solver.available === false || typeof solver.check !== 'function') return out('unsupported', ['no-solver']);
+  if (signal?.aborted) return out('unknown', ['cancelled']);
+
+  const ac = new AbortController();
+  let timer; let onAbort;
+  const timeoutP = new Promise((resolve) => { timer = setTimeout(() => resolve({ __timeout: true }), tmo); });
+  const cancelP = new Promise((resolve) => {
+    if (!signal) return;
+    onAbort = () => resolve({ __cancelled: true });
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+  let solverP;
+  try {
+    solverP = Promise.resolve(solver.check(toSolverProblem(collected), { signal: ac.signal }));
+  } catch {
+    clearTimeout(timer);
+    return out('unknown', ['solver-error']);
+  }
+  // A solver that settles after we gave up must not become an unhandled rejection.
+  solverP.catch(() => {});
+  try {
+    const r = await Promise.race([solverP, timeoutP, cancelP]);
+    if (r && r.__timeout) { ac.abort(); return out('timeout', ['solver-deadline']); }
+    if (r && r.__cancelled) { ac.abort(); return out('unknown', ['cancelled']); }
+    const status = isObjectWithResult(r) ? MAP[r.result] : undefined;
+    if (r?.result === 'unsupported') return out('unsupported', ['solver-declined']);
+    if (!status) return out('unknown', ['solver-malformed']);
+    return out(status, [`solver-${r.result}`], r.result === 'sat' && r.model && typeof r.model === 'object' ? { model: r.model } : {});
+  } catch {
+    return out('unknown', ['solver-error']);
+  } finally {
+    clearTimeout(timer);
+    if (signal && onAbort) signal.removeEventListener('abort', onAbort);
+  }
+}
+
+function isObjectWithResult(r) { return typeof r === 'object' && r !== null && typeof r.result === 'string'; }
+
+/**
+ * The full decision: abstract domains first, then the solver only when the abstract answer is `unknown`.
+ * The abstract answer stays on the result, so a timeout or an unsupported solver never erases what the
+ * cheap model already established, and the finding stays visible as unknown/partial.
+ */
+export async function evaluateWitnessConditionsAsync(collected, o = {}) {
+  const abstract = evaluateWitnessConditions(collected, o);
+  if (abstract.status !== 'unknown') return { ...abstract, abstractStatus: abstract.status, solverConsulted: false };
+  const s = await checkWithSolver(collected, o);
+  if (s.status === 'unsupported') return { ...abstract, abstractStatus: abstract.status, solverConsulted: false, solver: s.solver, solverStatus: 'unsupported' };
+  if (s.status === 'timeout') {
+    return { ...abstract, status: 'timeout', reasons: [...abstract.reasons, 'solver-deadline'], abstractStatus: abstract.status, solverConsulted: true, solver: s.solver, solverStatus: 'timeout', elapsedMs: s.elapsedMs };
+  }
+  if (s.status === 'unknown') {
+    return { ...abstract, abstractStatus: abstract.status, solverConsulted: true, solver: s.solver, solverStatus: 'unknown', reasons: [...abstract.reasons, ...s.reasons], elapsedMs: s.elapsedMs };
+  }
+  return {
+    ...abstract, status: s.status, reasons: s.reasons, abstractStatus: abstract.status, solverConsulted: true, solver: s.solver, solverStatus: s.status,
+    limitations: [...abstract.limitations, ...s.limitations], elapsedMs: s.elapsedMs,
+    contradiction: s.status === 'infeasible-under-model' ? { kind: 'solver-unsat', refs: abstract.clauseRefs } : null,
+  };
+}

package/src/lineage/source-seeding.js

@@ -125,6 +125,11 @@ function seedPathFor(expr, parentOf) {
 // from seed records, must not surface a literal `*` name to a user
 // without translating it into an honest "dynamic key" disclosure.
 
+// DAG-07 R07.5: generous defaults so an ordinary project never reaches them;
+// they exist so a pathological input cannot make the planner unbounded.
+export const DEFAULT_MAX_SEEDS = 1000000;
+export const DEFAULT_MAX_NODES = 20000000;
+
 // ── §3.3/§3.4: planSeeds ────────────────────────────────────────────────────
 
 /**
@@ -144,11 +149,29 @@ function seedPathFor(expr, parentOf) {
  * A matched expression with NO access path (`accessPathOf` → `null`) is
  * recorded in `unseedable[]` — never silently dropped (§3.3).
  */
-export function planSeeds(callGraph, { repository } = {}) {
+export function planSeeds(callGraph, { repository, maxSeeds, maxNodes, signal, deadline } = {}) {
   const seeds = [];
   const unseedable = [];
+  // DAG-07 R07.1: a completion record for the seeding step. A function the
+  // planner did not reach has no seeds, which looks identical to "this
+  // function reads no sources"; the record is what tells them apart.
+  const seedCap = Number.isInteger(maxSeeds) && maxSeeds >= 0 ? maxSeeds : DEFAULT_MAX_SEEDS;
+  const nodeCap = Number.isInteger(maxNodes) && maxNodes >= 0 ? maxNodes : DEFAULT_MAX_NODES;
+  let functionsTotal = 0;
+  let functionsScanned = 0;
+  let nodesVisited = 0;
+  let stopReason = null;
+  const shouldStop = () => !!(signal && signal.aborted) || (Number.isFinite(deadline) && Date.now() > deadline);
   for (const fn of callGraph.functions.values()) {
+    functionsTotal += 1;
+    if (stopReason) continue;
+    if (shouldStop()) { stopReason = 'cancelled'; continue; }
+    if (seeds.length >= seedCap) { stopReason = 'seeding-limit'; continue; }
+    if (nodesVisited >= nodeCap) { stopReason = 'seeding-limit'; continue; }
+    functionsScanned += 1;
     for (const [nid, node] of Object.entries(fn.cfg?.nodes ?? {})) {
+      nodesVisited += 1;
+      if (seeds.length >= seedCap) { stopReason = 'seeding-limit'; break; }
       const parentOf = new Map();
       for (const root of exprRoots(node)) walkExpr(root, (e, p) => { if (p) parentOf.set(e, p); });
       for (const root of exprRoots(node)) {
@@ -182,7 +205,18 @@ export function planSeeds(callGraph, { repository } = {}) {
       }
     }
   }
-  return { seeds, unseedable };
+  const notScanned = functionsTotal - functionsScanned;
+  const completion = {
+    status: stopReason === 'cancelled' ? 'cancelled' : stopReason ? 'partial' : 'complete',
+    reasons: stopReason ? [stopReason] : [],
+    functionsTotal,
+    functionsScanned,
+    functionsNotScanned: notScanned,
+    seeds: seeds.length,
+    unseedable: unseedable.length,
+    limits: { maxSeeds: seedCap, maxNodes: nodeCap, nodesVisited },
+  };
+  return { seeds, unseedable, completion };
 }
 
 // ── §3.5: seedEntryStateFactory — the driver.js opts.seedEntryState hook ──

package/src/lineage/summaries.js

@@ -1,5 +1,8 @@
 import { hashState, emptyState, addIdentity } from './field-identity.js';
-import { resolveExprIdentities, residualFlat, analyzeFunctionFieldIdentity } from './engine.js';
+import {
+  resolveExprIdentities, residualFlat, analyzeFunctionFieldIdentity,
+  argumentContext, callInvocationId, calleeRecorder,
+} from './engine.js';
 import { accessPathOf } from '../dataflow/access-paths.js';
 import { functionRecord } from '../ir/callgraph.js';
 
@@ -51,6 +54,13 @@ export class FieldIdentitySummaryCache {
     this._stack = new Set();
     this._contextsByQid = new Map();
     this._maxContextsPerFn = maxContextsPerFn;
+    // DAG-07 R07.3: degradations and unfinished refinements, recorded so a
+    // caller can tell a precise result from one that fell back. Append-only.
+    this._notes = [];
+  }
+
+  completionNotes() {
+    return this._notes.slice();
   }
 
   _key(qid, entryState) {
@@ -74,6 +84,21 @@ export class FieldIdentitySummaryCache {
   }
 
   compute(qid, entryState, analyzeFn) {
+    // While `qid` is marked by `refreshing()` (SCC solver only, driver.js): re-run `analyzeFn` for an
+    // entry that is ALREADY seeded in the cache, without the recursion-stub
+    // stack and without the bounded refinement loop. A self-call or a call
+    // to another member of the same component inside `analyzeFn` therefore
+    // reads the previous round's cached summary instead of a bottom stub.
+    // Never marked => behavior is byte-identical to before. The mark lives on
+    // the cache (not an argument) so wrappers around compute() stay valid.
+    if (this._refreshing && this._refreshing.get(qid) === hashState(entryState)) {
+      // Consume the mark: a nested call to the same context (a self-call)
+      // must take the normal path and hit the cached previous-round summary.
+      this._refreshing.delete(qid);
+      const refreshed = analyzeFn(entryState);
+      this.set(qid, entryState, refreshed);
+      return refreshed;
+    }
     // Ordering matches dataflow/summaries.js's own compute() exactly:
     // cache-hit checked FIRST, before the `_stack`-based recursion guard.
     // This is load-bearing, not incidental — B5's whole point is that a
@@ -130,6 +155,7 @@ export class FieldIdentitySummaryCache {
       // every later reader of the empty-entry context too.
       const base = this._cache.get(this._key(qid, emptyState())) ?? emptyFieldSummary();
       const fallback = { ...base, degradedReason: 'context-cap' };
+      this._notes.push({ qid, reason: 'context-cap' });
       this.set(qid, entryState, fallback);
       return fallback;
     }
@@ -219,12 +245,16 @@ export class FieldIdentitySummaryCache {
       // round) mirrors dataflow/summaries.js's own compute() exactly.
       if (this._hitRecursion) {
         const FP_MAX = 3;
+        let converged = false;
         for (let fp = 0; fp < FP_MAX; fp++) {
           const prev = summary;
           summary = analyzeFn(entryState);
-          if (fieldSummaryEq(prev, summary)) break;
+          if (fieldSummaryEq(prev, summary)) { converged = true; break; }
           this.set(qid, entryState, summary);
         }
+        // R07.3/R01.5: still changing after the last round means the
+        // summary is an under-approximation, not a fixed point.
+        if (!converged) this._notes.push({ qid, reason: 'recursion-nonconverged', rounds: FP_MAX });
       }
       // Defensive strip, mirroring dataflow's own equivalent: analyzeFn's
       // real return shape here never actually carries `_recursive` under
@@ -238,6 +268,28 @@ export class FieldIdentitySummaryCache {
     }
   }
 
+  // Marks `qid` as being refreshed by the SCC solver for the duration of `fn`.
+  // Only the exact `entryState` context is refreshed; any other context of
+  // `qid` reached meanwhile (e.g. a call-site argument state) takes the normal
+  // guarded path, so recursion through it still terminates.
+  refreshing(qid, entryState, fn) {
+    (this._refreshing ||= new Map()).set(qid, hashState(entryState));
+    try { return fn(); } finally { this._refreshing.delete(qid); }
+  }
+
+  // Forgets every cached context of `qid` except those whose state hash is in
+  // `keepHashes` (a Set). Used by the SCC solver between rounds so a context
+  // computed against an earlier round's summaries is never reused.
+  dropContexts(qid, keepHashes = new Set()) {
+    const seen = this._contextsByQid.get(qid);
+    if (!seen) return;
+    for (const h of [...seen]) {
+      if (keepHashes.has(h)) continue;
+      this._cache.delete(`${qid}::${h}`);
+      seen.delete(h);
+    }
+  }
+
   size() {
     return this._cache.size;
   }
@@ -326,11 +378,11 @@ export function entryStateFromCall(paramNames, callArgs, callerState, ctx) {
   // call site) is load-bearing, not stylistic — it means no future second
   // caller of entryStateFromCall can reintroduce the hazard by passing the
   // full ctx through a different path.
-  const argCtx = ctx?.recordHop ? { recordHop: ctx.recordHop } : undefined;
   let entryState = emptyState();
   const n = Math.min(paramNames.length, callArgs.length);
   for (let i = 0; i < n; i++) {
     const paramName = paramNames[i];
+    const argCtx = argumentContext(ctx, i);
     const resolved = resolveExprIdentities(callerState, callArgs[i], argCtx);
     const residual = residualFlat(resolved.flat, resolved.byPath);
     for (const id of residual) entryState = addIdentity(entryState, paramName, id);
@@ -409,6 +461,12 @@ export function createCallSummaryResolver(cache, lookupCallee) {
             fromPath: null, toPath: path, dataElementId: id,
             syntacticPath: null, widenReason: null, lossReason: null,
             peerScope: qid, peerContext: calleeContext,
+            ...(ctx.correlationVersion === 2 ? {
+              callRole: 'bind', invocationId: callInvocationId(ctx),
+              formalPosition: fn.params.indexOf(path.split('.')[0]),
+              relPath: path.includes('.') ? path.slice(path.indexOf('.') + 1) : '',
+              toVersion: 'entry',
+            } : null),
           });
         }
       }
@@ -444,7 +502,11 @@ export function createCallSummaryResolver(cache, lookupCallee) {
       // deepest call always wins). Passing a `context` field here would be
       // silently overwritten and is dead code.
       const calleeCtx = ctx?.recordHop
-        ? { resolveCallSummary, recordHop: ctx.recordHop }
+        ? {
+            resolveCallSummary,
+            recordHop: ctx.correlationVersion === 2 ? calleeRecorder(ctx) : ctx.recordHop,
+            ...(ctx.correlationVersion === 2 ? { correlationVersion: 2 } : null),
+          }
         : { resolveCallSummary };
       const result = analyzeFunctionFieldIdentity(fn, es, calleeCtx);
       return summaryFromAnalysisResult(result);

package/src/lineage/value-versions.js

@@ -0,0 +1,130 @@
+//
+// value-versions.js: SSA-like definition identities for the lineage engine
+// (DAG-03, R03.3).
+//
+// A reaching-definitions pass over one function's CFG that answers: "which
+// definitions of this state path can reach the entry of this CFG node?" The
+// answer is a SET, so a merge keeps both alternatives (a phi) instead of
+// pretending they co-occur or picking one, and a later strong write kills the
+// earlier definition of that path and everything under it, whether or not
+// the written value carried any identity (a clean literal is still a kill).
+//
+// Definition ids are the CFG node ids of the writing `assign`, plus the
+// reserved id 'entry' for a value that was live on function entry (a
+// parameter, a seeded source, anything no assignment has overwritten).
+//
+// The pass is purely structural. It does not read or change the field
+// identity state, so it cannot alter an analysis result; it only labels the
+// provenance halves the engine emits when correlation version 2 is on.
+//
+export const ENTRY_VERSION = 'entry';
+
+function nodeEntries(nodes) {
+  if (nodes instanceof Map) return [...nodes.entries()];
+  return Object.entries(nodes ?? {});
+}
+
+function pathHasWildcard(path) {
+  return path.split('.').includes('*');
+}
+
+function definitePrefix(path) {
+  const segs = path.split('.');
+  const idx = segs.indexOf('*');
+  if (idx <= 0) return null;
+  return segs.slice(0, idx).join('.');
+}
+
+/** The definitions recorded for the longest self-or-ancestor key of `path` in `st`, or {entry}. */
+function lookup(st, path) {
+  let p = path;
+  for (;;) {
+    const hit = st.get(p);
+    if (hit) return hit;
+    const i = p.lastIndexOf('.');
+    if (i === -1) return null;
+    p = p.slice(0, i);
+  }
+}
+
+function join(a, b) {
+  const out = new Map();
+  const keys = new Set([...a.keys(), ...b.keys()]);
+  for (const k of keys) {
+    const sa = a.get(k) ?? lookup(a, k) ?? new Set([ENTRY_VERSION]);
+    const sb = b.get(k) ?? lookup(b, k) ?? new Set([ENTRY_VERSION]);
+    out.set(k, new Set([...sa, ...sb]));
+  }
+  return out;
+}
+
+function equal(a, b) {
+  if (a.size !== b.size) return false;
+  for (const [k, sa] of a) {
+    const sb = b.get(k);
+    if (!sb || sb.size !== sa.size) return false;
+    for (const d of sa) if (!sb.has(d)) return false;
+  }
+  return true;
+}
+
+function transfer(nid, node, st) {
+  if (node.kind !== 'assign' || typeof node.target !== 'string') return st;
+  const out = new Map(st);
+  if (pathHasWildcard(node.target)) {
+    // A computed-key write is a WEAK update: it adds a definition to the
+    // container and kills nothing.
+    const container = definitePrefix(node.target);
+    if (container) {
+      const prior = out.get(container) ?? lookup(st, container) ?? new Set([ENTRY_VERSION]);
+      out.set(container, new Set([...prior, nid]));
+    }
+    return out;
+  }
+  const t = node.target;
+  for (const k of [...out.keys()]) {
+    if (k === t || k.startsWith(`${t}.`)) out.delete(k);
+  }
+  out.set(t, new Set([nid]));
+  return out;
+}
+
+/**
+ * @param {{cfg:{entry:string, nodes:Map|object}, params?:string[]}} fn
+ * @returns {{versionsAt:(nodeId:string, path:string)=>string[]}}
+ */
+export function computeReachingDefinitions(fn) {
+  const nodes = new Map(nodeEntries(fn.cfg?.nodes));
+  const inStates = new Map();
+  const entry = new Map();
+  for (const p of fn.params ?? []) entry.set(p, new Set([ENTRY_VERSION]));
+  inStates.set(fn.cfg.entry, entry);
+  const work = [fn.cfg.entry];
+  const outStates = new Map();
+  let guard = 0;
+  const cap = Math.max(10000, nodes.size * 64);
+  while (work.length && guard++ < cap) {
+    const nid = work.shift();
+    const node = nodes.get(nid);
+    if (!node) continue;
+    const out = transfer(nid, node, inStates.get(nid) ?? new Map());
+    const prev = outStates.get(nid);
+    if (prev && equal(prev, out)) continue;
+    outStates.set(nid, out);
+    for (const s of node.succ ?? []) {
+      const pi = inStates.get(s);
+      const ni = pi ? join(pi, out) : out;
+      if (!pi || !equal(pi, ni)) {
+        inStates.set(s, ni);
+        work.push(s);
+      }
+    }
+  }
+  return {
+    versionsAt(nodeId, path) {
+      const st = inStates.get(nodeId);
+      const hit = st ? lookup(st, path) : null;
+      return hit ? [...hit].sort() : [ENTRY_VERSION];
+    },
+  };
+}