@clear-capabilities/agentic-security-scanner 0.184.0 → 0.186.1

package/src/dataflow/engine.js

@@ -2130,6 +2130,8 @@ function _unionAnnotationTaint(fn, entrySet) {
   if (seeds && seeds.size && Array.isArray(fn.params) && _REQ_PARAM.test(fn.params[0] || '')) {
     entrySet = new Set([...entrySet, ...[...seeds].map((f) => `${fn.params[0]}.${f}`)]);
   }
+  // DAG-08: access paths seeded by a bound boundary contract (lineage/boundary-contract.js). Absent unless a contract bound to this function.
+  if (Array.isArray(fn.boundarySeeds) && fn.boundarySeeds.length) entrySet = new Set([...entrySet, ...fn.boundarySeeds]);
   if (!fn.paramAnnotations || !fn.paramAnnotations.length) return entrySet;
   const extra = matchAnnotationParams(fn.paramAnnotations, fn.file);
   if (!extra.size) return entrySet;
@@ -2359,9 +2361,9 @@ function stateEq(a, b) {
 // that runs out used to leave a result that looked complete; now `runTaintEngine`'s return value carries `analysisIncomplete`, and the scan
 // reports it as `deepStatus.incomplete`.
 let _incomplete = new Map();
-function _noteIncomplete(reason, detail) {
+function _noteIncomplete(reason, detail, n = 1) {
   const cur = _incomplete.get(reason);
-  if (cur) cur.count += 1; else _incomplete.set(reason, { reason, count: 1, example: String(detail ?? '').slice(0, 160) });
+  if (cur) cur.count += n; else _incomplete.set(reason, { reason, count: n, example: String(detail ?? '').slice(0, 160) });
 }
 export const INCOMPLETE_REASONS = Object.freeze({
   'summary-budget': 'the interprocedural summary budget ran out; later callees were treated as having no effect',
@@ -2369,6 +2371,10 @@ export const INCOMPLETE_REASONS = Object.freeze({
   'function-limit': 'more functions than the per-scan function limit; the rest were not analysed',
   'higher-order-limit': 'more callback invocations than the per-function limit; the rest were not analysed',
   'analysis-error': 'the analysis of a function threw and its result was discarded',
+  // DAG-07 R07.3
+  'context-cap-fallback': 'a call under a tainted argument shape was answered with the empty-entry summary because the per-function context cap was reached',
+  'recursion-nonconverged': 'a recursive summary was still changing when its refinement rounds ran out',
+  'incremental-empty-entry-reuse': 'a summary restored from a previous scan stood in for a tainted call context',
 });
 
 export function runTaintEngine(perFileIR, callGraph, opts = {}) {
@@ -2401,6 +2407,9 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
   // v0.69 — opts.summaryCache lets the caller (runDeepAnalysis with
   // incremental mode) hand in a pre-seeded cache from persisted state.
   const summaryCache = opts.summaryCache || new SummaryCache();
+  // DAG-05: cross-scan reuse. `_replay` (incremental-replay.js) records what each function
+  // contributed and, for a function the dependency plan proved clean, replays it.
+  const _replay = opts._replay || null;
 
   // Deterministic ordering (Sentinel-parity §9.2): sort functions by qid so
   // cache-cold runs produce the same finding sequence run-over-run.
@@ -2408,6 +2417,7 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
     a.qid < b.qid ? -1 : a.qid > b.qid ? 1 : 0
   );
   _buildRegexNames(fnList);
+  if (_replay) _replay.setMainLoop(new Set(fnList.slice(0, fnLimit).map((f) => f.qid))); // DAG-05
   _buildRequestFieldSeeds(fnList, callGraph, opts, deadlineMs);
   // PRD W0.1 (SARD_80_F1_EXECUTION_PRD.md) — the main per-function loop below
   // silently `break`s once `n > fnLimit` (default 5000), which for a single
@@ -2438,6 +2448,7 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
   // unbounded blowup). v0.66 — the inner ctx now records mutatedParams
   // via _mutatedParamsOut so cross-function param mutation propagates.
   const MAX_FP_ITERS = 3;
+  let _fpConverged = false; // DAG-05: did the pre-pass reach a fixed point within MAX_FP_ITERS
   // qid -> this function's own exit-state (every tainted access path at
   // return, from the LAST pre-pass iteration only — see the class-field
   // cross-taint pass below for why this must be a real, already-observed
@@ -2452,6 +2463,13 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
     let changedThisIter = false;
     for (const fn of fnList) {
       if (Date.now() > deadlineMs) break;
+      // DAG-05 begin: a function proved clean is not re-walked; its recorded exit state and findings stand in.
+      if (_replay && _replay.canSkip(fn.qid)) {
+        exitStateByQid.set(fn.qid, _replay.exitState(fn.qid));
+        if (it === 0) _replayFindings(fn.qid);
+        continue;
+      }
+      // DAG-05 end
       const entry = new Set();
       const key = fn.qid + '::empty';
       const existing = summaryCache.get(fn.qid, entry);
@@ -2506,8 +2524,11 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
     // write, silently delivering 2 rounds of fixed-point refinement instead
     // of the MAX_FP_ITERS=3 this code and dataflow/CLAUDE.md both promise.
     // `changedThisIter` tracks actual value changes instead.
-    if (!changedThisIter) break;
+    if (!changedThisIter) { _fpConverged = true; break; }
   }
+  // DAG-05 begin
+  if (_replay) { _replay.recordExitStates(exitStateByQid); _replay.noteConverged(_fpConverged); }
+  // DAG-05 end
   // Class-field cross-taint pass (SARD_80_F1_SCANNER_PRD.md — Juliet flow
   // variants 45/65-68: a method writes a tainted value to a static or
   // instance field and a SIBLING method of the same class reads it into a
@@ -2836,6 +2857,9 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
     if (++n > fnLimit) { _noteIncomplete('function-limit', `limit ${fnLimit}`); break; }
     if (Date.now() > deadlineMs) { _noteIncomplete('deadline', 'main function loop'); break; }  // global timeout
     if (onProgress) onProgress({ current: n, total: _progressTotal });
+    // DAG-05 begin: replayed in the pre-pass; idempotent here for a pre-pass cut short.
+    if (_replay && _replay.canSkip(fn.qid)) { _replayFindings(fn.qid); continue; }
+    // DAG-05 end
     // Module-level functions: analyze with an empty entry state. The function
     // discovers its own sources from req.body/process.env/etc. as it walks.
     const callContext = {
@@ -2934,6 +2958,7 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
   }
   Object.defineProperty(all, '_summaryCache', { value: summaryCache, enumerable: false });
   if (summaryCache._budgetHits) _noteIncomplete('summary-budget', `${summaryCache._budgetHits} summary requests after ${summaryCache._maxIter} computations`);
+  if (typeof summaryCache.completionNotes === 'function') for (const n of summaryCache.completionNotes()) _noteIncomplete(n.reason, n.example, n.count);
   Object.defineProperty(all, 'analysisIncomplete', { value: [..._incomplete.values()].sort((a, b) => (a.reason < b.reason ? -1 : 1)), enumerable: false });
   _collapseNestedHsSinks(all);
   return all;
@@ -2963,10 +2988,13 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
       // this fix.
       const file = f.file || attributedFn.file;
       const key = `${f.sinkId}:${file}:${f.line}${f.siteKey ? ':' + f.siteKey : ''}`;
-      if (seen.has(key)) continue;
+      // DAG-05: a duplicate is still part of what THIS function contributed (the first
+      // collector may be a function that later changes), so it is recorded; it is not re-emitted.
+      const _dup = seen.has(key);
+      if (_dup && !_replay) continue;
       seen.add(key);
       const fn = attributedFn;
-      all.push({
+      const _mapped = {
         id: `ir-taint:${file}:${f.line}:${f.sinkId}${f.siteKey ? ':' + f.siteKey : ''}`,
         ...(f.siteKey ? { siteKey: f.siteKey } : {}),
         file,
@@ -3049,7 +3077,21 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
         chain: (f.trace || []).map(t => ({
           file: fn.file, line: t.line, label: t.sourceLabel, provenance: t.provenance || null,
         })),
-      });
+      };
+      if (_replay) _replay.record(attributedFn.qid, key, _mapped);
+      if (!_dup) all.push(_mapped);
+    }
+  }
+
+  // DAG-05: emit a replayed function's recorded findings through the same
+  // de-duplication the collector applies, so a replayed finding and a recomputed
+  // one for the same sink are one finding.
+  function _replayFindings(qid) {
+    for (const { key, obj } of _replay.findingsFor(qid)) {
+      if (seen.has(key)) continue;
+      seen.add(key);
+      all.push(obj);
+      _replay.noteReused(obj.id);
     }
   }
 

package/src/dataflow/exploit-prover.js

@@ -22,8 +22,13 @@
 //
 // We do NOT attempt to prove ARBITRARY satisfiability — the v2 use case.
 
+import { createRequire } from 'node:module';
 import { provablyMatches, safeSanitizerOutputRegex } from './string-domain.js';
 
+// Optional package, loaded at first use through a runtime require so a bundler keeps it external and a
+// build without it fails here (caught below), never at start-up.
+const require = createRequire(import.meta.url);
+
 // CWE → canonical exploit input. Conservative payloads safe to display.
 const EXPLOIT_INPUTS = {
   'CWE-89':   `1' OR '1'='1`,                                        // SQL injection
@@ -93,8 +98,7 @@ async function _maybeLoadZ3() {
   if (_z3Loaded) return _z3;
   _z3Loaded = true;
   try {
-    const mod = await import('z3-solver').catch(() => null);
-    _z3 = mod || null;
+    _z3 = require('z3-solver') || null;
   } catch { _z3 = null; }
   return _z3;
 }

package/src/dataflow/ifds-precise.js

@@ -158,6 +158,28 @@ export function backwardSlice(callGraph, finding, opts = {}) {
   return out.reverse(); // source-first
 }
 
+/**
+ * Same walk as backwardSlice, plus a completion record in the shared
+ * vocabulary (DAG-02 R02.5): a chain cut at MAX_SLICE_DEPTH is a prefix of the
+ * real predecessor chain, so it reports `partial` with the depth limit as its
+ * reason and can never license a negative claim. backwardSlice itself is
+ * unchanged.
+ */
+export function backwardSliceWithCompletion(callGraph, finding, opts = {}) {
+  const slice = backwardSlice(callGraph, finding, opts);
+  const capped = slice.some((s) => s && s.reason === 'slice-depth-cap');
+  return {
+    slice,
+    completion: {
+      status: capped ? 'partial' : 'complete',
+      reasons: capped ? ['slice-depth-limit'] : [],
+      unexploredFrontierCount: capped ? 1 : 0,
+      visited: slice.length,
+      limits: { maxDepth: MAX_SLICE_DEPTH },
+    },
+  };
+}
+
 // ── Persistent cross-scan summary cache ────────────────────────────────────
 
 function _cachePath(scanRoot) {

package/src/dataflow/incremental-replay.js

@@ -0,0 +1,118 @@
+// DAG-05: the engine-facing half of cross-scan reuse.
+//
+// `ReplayHooks` is handed to `runTaintEngine` as `opts._replay`. It does two jobs:
+//
+//   * RECORD (every run): for each function, the findings it contributed to the
+//     result (every pass, after the same de-duplication key the engine uses) and
+//     its pre-pass exit state, so the next scan has something to reuse.
+//   * REPLAY (warm run): for a function the plan proved clean, hand the engine its
+//     recorded exit state and findings instead of re-walking its body.
+//
+// A function is replayable only when every one of these holds: the dependency
+// plan says clean (own body, resolution, the whole closure and its cycle are
+// unchanged), a complete record exists for it, and the record came from an
+// analysis that converged. Anything less and the engine analyses it as before.
+
+import { jsonSafeFinding } from './incremental.js';
+
+const MAX_EXIT_PATHS = 4000;
+
+export class ReplayHooks {
+  /**
+   * @param {object} o
+   * @param {Set<string>} [o.clean]            qids that may be replayed (empty or absent: record only)
+   * @param {Map<string,object>} [o.records]   prior records: qid -> { exit:[...], findings:[{key,obj}] }
+   * @param {string} [o.generation]            generation id of the cache the records came from
+   * @param {Map<string,string>} [o.closure]   qid -> closure fingerprint (for provenance)
+   */
+  constructor({ clean, records, generation, closure } = {}) {
+    this.clean = clean || new Set();
+    this.records = records || new Map();
+    this.generation = generation || null;
+    this.closure = closure || new Map();
+    this._found = new Map();        // qid -> Map(key -> obj)   recorded this run
+    this._unrecordable = new Set(); // qids whose findings could not be serialised
+    this._exits = new Map();        // qid -> [path] recorded this run
+    this.converged = false;
+    this.mainLoop = null;           // Set<qid>: the functions this run's main loop covers (the first fnLimit by qid)
+    this.replayed = new Set();      // qids actually skipped this run
+    this.reusedFindingIds = new Set();
+  }
+
+  /**
+   * The engine's main loop covers only the first `fnLimit` functions by qid, so a record
+   * made while a function was outside it lacks that loop's findings. Replay needs the same
+   * membership now as when the record was made.
+   */
+  setMainLoop(qids) { this.mainLoop = qids; }
+
+  canSkip(qid) {
+    if (!this.clean.has(qid)) return false;
+    const r = this.records.get(qid);
+    if (!r) return false;
+    return !this.mainLoop || r.inMain === this.mainLoop.has(qid);
+  }
+
+  exitState(qid) {
+    const r = this.records.get(qid);
+    return new Set((r && r.exit) || []);
+  }
+
+  /** Recorded findings for a replayed function, cloned so the engine may mutate them. */
+  findingsFor(qid) {
+    const r = this.records.get(qid);
+    if (!r) return [];
+    this.replayed.add(qid);
+    const out = [];
+    for (const { key, obj } of r.findings || []) {
+      const c = JSON.parse(JSON.stringify(obj));
+      out.push({ key, obj: c });
+    }
+    return out;
+  }
+
+  noteReused(id) { this.reusedFindingIds.add(id); }
+
+  /** Called from the engine's finding collector for every mapped finding. */
+  record(qid, key, obj) {
+    if (!qid) return;
+    let m = this._found.get(qid);
+    if (!m) { m = new Map(); this._found.set(qid, m); }
+    if (m.has(key)) return;
+    const c = jsonSafeFinding(obj);
+    if (c === null) { this._unrecordable.add(qid); return; }
+    m.set(key, c);
+  }
+
+  recordExitStates(exitByQid) {
+    for (const [qid, set] of exitByQid) {
+      const arr = [...set].filter((p) => typeof p === 'string').sort();
+      this._exits.set(qid, arr);
+    }
+  }
+
+  noteConverged(v) { this.converged = !!v; }
+
+  /**
+   * The records to persist for the next scan: a clean function carries its prior
+   * record forward, every other function gets what was recorded this run. A
+   * function with an unserialisable finding or an oversized exit state gets no
+   * record, which makes it always recompute.
+   */
+  buildRecords(qids) {
+    const out = {};
+    for (const qid of qids) {
+      if (this.replayed.has(qid)) {
+        const r = this.records.get(qid);
+        if (r) out[qid] = r;
+        continue;
+      }
+      if (this._unrecordable.has(qid)) continue;
+      const exit = this._exits.get(qid);
+      if (!exit || exit.length > MAX_EXIT_PATHS) continue;
+      const found = this._found.get(qid) || new Map();
+      out[qid] = { exit, inMain: this.mainLoop ? this.mainLoop.has(qid) : true, findings: [...found].map(([key, obj]) => ({ key, obj })) };
+    }
+    return out;
+  }
+}

package/src/dataflow/incremental-session.js

@@ -0,0 +1,257 @@
+// DAG-05: one incremental session per deep-analysis run.
+//
+//   begin   read the persisted state, fingerprint the current project, decide warm
+//           or cold (and say why), restore the typed contexts of clean functions
+//   finish  stamp cache provenance on the findings, persist the new generation
+//           atomically, and describe what was reused versus recomputed
+//
+// The decision is made from CONTENT (dep-fingerprint.js). Any doubt is cold:
+// an unreadable, corrupt, incomplete or incompatible cache, a changed global
+// input, an unsupported option, a prior analysis that was cut short or did not
+// converge. A cold run is a full analysis and reports `mode: 'cold'` with the
+// reason, so a missing speed-up is never silent and a wrong answer never
+// results from a cache that could not be trusted.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+import { SummaryCache } from './summaries.js';
+import {
+  readIncrementalState, validateIncrementalState, hashFileContent, diffFileHashes,
+  serializeContexts, restoreContexts, commitIncrementalState, CONTEXT_SCHEMA,
+} from './incremental.js';
+import { ReplayHooks } from './incremental-replay.js';
+import {
+  buildDependencyModel, globalComponents, planIncremental, countByReason, diffComponents, DEP_GRAPH_SCHEMA,
+} from './dep-fingerprint.js';
+import { loadProjectStubs } from '../ir/type-stubs.js';
+
+const REPLAY_SCHEMA = 'replay/1';
+
+// Options whose effect on a function's result is not captured by the function's own
+// fingerprint, so reuse under them is refused rather than guessed.
+const UNSUPPORTED_FOR_REPLAY = [
+  ['AGENTIC_SECURITY_POINTS_TO', 'a whole-program points-to graph feeds every function'],
+  ['AGENTIC_SECURITY_RHS', 'reachability slicing restricts which functions are analysed'],
+  ['AGENTIC_SECURITY_KCFA_CALLSTRING', 'call-string contexts key summaries by caller'],
+  ['AGENTIC_SECURITY_BACKWARD_SLICE', 'the backward slicer needs live IR references a stored finding does not have'],
+  ['AGENTIC_SECURITY_SYMEXEC', 'the exploit prover needs live IR references a stored finding does not have'],
+];
+// Reasons that make a finished run's records untrustworthy for reuse.
+const BLOCKING_INCOMPLETE = new Set(['deadline', 'analysis-error', 'summary-budget']);
+
+let _scannerVersion = null;
+function scannerVersion() {
+  if (_scannerVersion) return _scannerVersion;
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    for (const rel of ['../../package.json', '../package.json', './package.json']) {
+      try { const v = JSON.parse(fs.readFileSync(path.resolve(here, rel), 'utf8')).version; if (v) { _scannerVersion = v; return v; } } catch { /* next */ }
+    }
+  } catch { /* fall through */ }
+  _scannerVersion = 'unknown';
+  return _scannerVersion;
+}
+
+/** Reverse call graph (callee -> callers) from the dependency model's own edges. */
+function callersFrom(model) {
+  const callers = {};
+  for (const [qid, f] of Object.entries(model.functions)) {
+    for (const c of f.callees) (callers[c] ||= []).push(qid);
+  }
+  return callers;
+}
+
+/**
+ * Start a session. Returns null when incremental analysis is not enabled or the
+ * caller supplied no scan root / file contents (nothing could be persisted).
+ */
+export function beginIncrementalSession({ enabled, opts, perFileIR, callGraph, cha, env = process.env, now = Date.now }) {
+  if (!enabled || !opts || !opts.scanRoot || !opts.fileContents) return null;
+  const t0 = now();
+  const fileHashes = {};
+  for (const [fp, content] of Object.entries(opts.fileContents)) fileHashes[fp] = hashFileContent(content);
+  const global = globalComponents({
+    scanRoot: opts.scanRoot, fileContents: opts.fileContents, opts, env,
+    stubsProvider: opts._stubsProvider || ((root) => (root ? loadProjectStubs(root) : null)),
+  });
+  const rulesDigest = crypto.createHash('sha256').update(`${global.catalog}${global.sanitizers}`).digest('hex').slice(0, 16);
+  const version = { scanner: opts.scannerVersion || scannerVersion(), rules: opts.rulesDigest || `content:${rulesDigest}` };
+  const tRead = now();
+  const prior = readIncrementalState(opts.scanRoot);
+  const readMs = now() - tRead;
+  const t1 = now();
+  const reuse = prior.deps && prior.deps.global && prior.deps.global.analyzers === global.analyzers
+    ? { functions: prior.deps.functions, priorFiles: prior.files, curFiles: fileHashes } : null;
+  const model = buildDependencyModel({ perFileIR, callGraph, cha, fileContents: opts.fileContents, reuse });
+  const fingerprintMs = (t1 - t0) + (now() - t1);
+  const session = {
+    root: opts.scanRoot, version, global, model, fileHashes, prior, callGraph,
+    mode: 'cold', reason: null, plan: null, cache: null, hooks: null,
+    restored: { contexts: 0, rejected: 0 }, fingerprintMs, priorGeneration: prior.generation || null,
+    fileDiff: null, io: opts._incrementalIo || {}, timing: { fingerprintMs, readMs, planMs: 0, restoreMs: 0 },
+  };
+  const decide = () => {
+    const unsupported = UNSUPPORTED_FOR_REPLAY.find(([name]) => env[name] === '1');
+    if (unsupported) return `replay unsupported under ${unsupported[0]}: ${unsupported[1]}`;
+    if (!Object.keys(model.functions).length) return 'no analysable functions in this project, so there is nothing to reuse';
+    const valid = validateIncrementalState(prior, version);
+    if (!valid.valid) {
+      // name the content that moved when the version string alone does not
+      const moved = prior.deps && prior.deps.global ? diffComponents(prior.deps.global, global) : [];
+      return moved.length && /rule-pack/.test(valid.reason) ? `${valid.reason} (${moved.join(', ')})` : valid.reason;
+    }
+    if (!prior.deps) return 'prior state has no dependency model';
+    if (!prior.replay || prior.replay.schema !== REPLAY_SCHEMA) return 'prior state has no replay records';
+    if (!prior.replay.complete) return `prior analysis was incomplete (${(prior.replay.reasons || []).join(', ') || 'unspecified'})`;
+    if (!prior.replay.converged) return 'prior fixed point did not converge';
+    if (prior.deps.schema !== DEP_GRAPH_SCHEMA) return 'prior dependency graph has an incompatible schema';
+    return null;
+  };
+  const why = decide();
+  session.fileDiff = diffFileHashes(prior.files || {}, fileHashes);
+  if (why) {
+    session.reason = why;
+    session.hooks = new ReplayHooks();
+    return session;
+  }
+  const tPlan = now();
+  const records = new Map(Object.entries(prior.replay.records || {}));
+  const plan = planIncremental(
+    { global: prior.deps.global || {}, deps: prior.deps, hasRecord: (q) => records.has(q) },
+    { global, model },
+  );
+  if (plan.mode === 'cold') {
+    session.reason = plan.reason;
+    session.plan = plan;
+    session.hooks = new ReplayHooks();
+    return session;
+  }
+  session.timing.planMs = now() - tPlan;
+  const tRestore = now();
+  const cache = new SummaryCache();
+  const stats = restoreContexts(cache, { schema: CONTEXT_SCHEMA, contexts: prior.replay.contexts }, plan.clean);
+  // A clean function whose empty-entry context could not be restored cannot be replayed.
+  for (const q of [...plan.clean]) {
+    if (!cache.has(q, new Set())) { plan.clean.delete(q); plan.dirty.set(q, 'context-not-restorable'); }
+  }
+  session.timing.restoreMs = now() - tRestore;
+  const closure = new Map(Object.entries(model.functions).map(([q, f]) => [q, f.closure]));
+  session.mode = 'warm';
+  session.plan = plan;
+  session.cache = cache;
+  session.restored = stats;
+  session.hooks = new ReplayHooks({ clean: plan.clean, records, generation: prior.generation, closure });
+  return session;
+}
+
+/** Options to merge into the runTaintEngine call. */
+export function engineOptionsFor(session) {
+  if (!session) return {};
+  return { _replay: session.hooks, ...(session.cache ? { summaryCache: session.cache } : {}) };
+}
+
+/**
+ * Finish: stamp provenance, persist the new generation, return the stats object
+ * to attach to the findings array.
+ */
+export function finishIncrementalSession(session, findings, { now = Date.now } = {}) {
+  if (!session) return null;
+  const hooks = session.hooks;
+  const model = session.model;
+  // provenance on every finding
+  const gen = session.priorGeneration;
+  let reused = 0; let recomputed = 0;
+  for (const f of findings) {
+    if (hooks && hooks.reusedFindingIds.has(f.id)) {
+      f.cacheProvenance = { state: 'reused', generation: gen, closureFingerprint: model.functions[f._funcQid]?.closure ?? null };
+      reused++;
+    } else {
+      f.cacheProvenance = { state: 'recomputed' };
+      recomputed++;
+    }
+  }
+  const incomplete = Array.isArray(findings.analysisIncomplete) ? findings.analysisIncomplete : [];
+  const blocking = incomplete.filter((x) => BLOCKING_INCOMPLETE.has(x.reason)).map((x) => x.reason);
+  const nonConverged = incomplete.some((x) => x.reason === 'recursion-nonconverged');
+  const cache = findings._summaryCache;
+  const t0 = now();
+  let committed = false;
+  let commitError = null;
+  const persistPhases = {};
+  let lapT = now();
+  const lap = (n) => { const x = now(); persistPhases[n] = x - lapT; lapT = x; };
+  try {
+    const ctx = serializeContexts(cache);
+    lap('serialize-contexts');
+    const records = hooks.buildRecords(Object.keys(model.functions));
+    lap('build-records');
+    const replay = {
+      schema: REPLAY_SCHEMA,
+      complete: blocking.length === 0,
+      reasons: [...new Set(blocking)].sort(),
+      converged: hooks.converged && !nonConverged,
+      contexts: ctx.contexts, contextsNotPersisted: ctx.skipped, records,
+    };
+    const deps = {
+      schema: DEP_GRAPH_SCHEMA, global: session.global, chaDigest: model.chaDigest,
+      functions: model.functions, fileSymbols: model.fileSymbols, sccs: model.sccs,
+    };
+    lap('assemble');
+    committed = commitIncrementalState(session.root, {
+      files: session.fileHashes,
+      // the typed contexts live in replay.json; summaries.json keeps the legacy reverse call graph only
+      summaries: {},
+      callers: callersFrom(model),
+      deps, replay,
+    }, session.version, session.io);
+    lap('commit');
+    if (!committed) commitError = 'state not written (state writes disabled, unwritable directory, or an interrupted write)';
+  } catch (e) { commitError = String((e && e.message) || e); }
+  const persistMs = now() - t0;
+
+  const plan = session.plan;
+  const cleanN = plan && plan.clean ? plan.clean.size : 0;
+  const replayed = hooks ? hooks.replayed.size : 0;
+  const fnTotal = Object.keys(model.functions).length;
+  return {
+    // legacy fields the existing tests and consumers read
+    seeded: session.restored.restored ?? 0, reusable: replayed, discardedLegacy: 0,
+    mode: session.mode,
+    reason: session.mode === 'cold' ? session.reason : null,
+    priorGeneration: gen,
+    provenance: {
+      reusedFunctions: replayed,
+      recomputedFunctions: Math.max(0, fnTotal - replayed),
+      reusedFindings: reused,
+      recomputedFindings: recomputed,
+      restoredContexts: session.restored.restored ?? 0,
+      contextsRejected: session.restored.rejected ?? 0,
+    },
+    invalidation: plan ? {
+      cleanFunctions: cleanN,
+      dirtyFunctions: plan.dirty.size,
+      dirtyByReason: countByReason(plan.dirty),
+      // the first 500 recomputed functions and why, so a reader can see what the edit reached
+      dirty: [...plan.dirty].sort((a, b) => (a[0] < b[0] ? -1 : 1)).slice(0, 500).map(([qid, reason]) => ({ qid, reason })),
+      removedSymbols: plan.removed,
+      removedFiles: plan.removedFiles || [],
+      movedOrRenamedSymbols: plan.renamed || [],
+      sccWidened: plan.widened || 0,
+      changedGlobalComponents: plan.changedComponents || [],
+    } : null,
+    files: { changed: session.fileDiff.changed.length, added: session.fileDiff.added.length, removed: session.fileDiff.removed.length, unchanged: session.fileDiff.unchanged.length },
+    model: { ...model.stats, fingerprintMs: session.fingerprintMs },
+    timing: session.timing,
+    persisted: { committed, error: commitError, ms: persistMs, phaseMs: persistPhases },
+    // DAG-07 R07.3 shape: reuse proven equivalent by fingerprint is complete; a cold fallback is a full analysis.
+    completion: {
+      status: 'complete',
+      reasons: [],
+      emptyEntryReusedForTaintedContexts: 0,
+      summariesWithTruncatedFindings: 0,
+    },
+  };
+}