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

package/src/dataflow/incremental.js

@@ -35,42 +35,77 @@ import { statePath, stateWritesEnabled } from '../posture/state-dir.js';
 
 const FILES_PATH = 'files.json';
 const SUMMARIES_PATH = 'summaries.json';
-const VERSION_PATH = 'version.json';
+const VERSION_PATH = 'version.json';   // the MANIFEST: written last, names and digests every data file
+const DEPS_PATH = 'deps.json';         // DAG-05: dependency model + global components
+const REPLAY_PATH = 'replay.json';     // DAG-05: typed contexts, exit states, per-function findings
+const DATA_FILES = [FILES_PATH, SUMMARIES_PATH, DEPS_PATH, REPLAY_PATH];
 const MAX_PERSISTED_SUMMARIES = 50000;
+// DAG-05 R05.6: bump when the on-disk shape changes; an older or newer record is rejected, never guessed at.
+export const INCREMENTAL_FORMAT = 'incremental-state/2';
 
 /** Compute the content hash used for file-equality detection. */
 export function hashFileContent(stripped) {
   return crypto.createHash('sha256').update(stripped || '').digest('hex');
 }
 
-/** Read the persisted state. Returns a fresh empty state on any error. */
+/**
+ * Read the persisted state. Returns a fresh empty state on any error.
+ *
+ * DAG-05 R05.6: the version file is a manifest that names every data file with
+ * its SHA-256. A state is accepted only when the format is the current one, every
+ * named file exists and matches its digest and parses, so a crash between the
+ * temp write and the rename, a truncated file or a hand edit is rejected as a
+ * whole. A rejection is carried as `state.rejected` (the reason) so the caller
+ * can say why it fell back to cold analysis.
+ */
 export function readIncrementalState(projectRoot) {
   const dir = statePath(projectRoot, 'incremental');
+  const versionFp = path.join(dir, VERSION_PATH);
+  let manifest;
   try {
-    const versionFp = path.join(dir, VERSION_PATH);
     if (!fs.existsSync(versionFp)) return _emptyState();
-    const v = JSON.parse(fs.readFileSync(versionFp, 'utf8'));
-    return {
-      version: v,
-      files: _readJsonOrEmpty(path.join(dir, FILES_PATH), {}),
-      summaries: _readJsonOrEmpty(path.join(dir, SUMMARIES_PATH), {}),
-    };
+    manifest = JSON.parse(fs.readFileSync(versionFp, 'utf8'));
   } catch (_e) {
-    return _emptyState();
+    return _rejected('cache manifest is corrupt (does not parse)');
+  }
+  if (!manifest || typeof manifest !== 'object' || manifest.format !== INCREMENTAL_FORMAT) {
+    return _rejected(`cache format is not ${INCREMENTAL_FORMAT} (found ${manifest && manifest.format ? manifest.format : 'legacy'})`);
+  }
+  const listed = manifest.files && typeof manifest.files === 'object' ? manifest.files : null;
+  if (!listed || !manifest.version || typeof manifest.version !== 'object') return _rejected('cache manifest is incomplete');
+  const parsed = {};
+  for (const name of DATA_FILES) {
+    const entry = listed[name];
+    if (!entry || typeof entry.sha256 !== 'string') return _rejected(`cache manifest does not list ${name}`);
+    let text;
+    try { text = fs.readFileSync(path.join(dir, name), 'utf8'); }
+    catch { return _rejected(`incomplete cache: ${name} is missing`); }
+    const got = crypto.createHash('sha256').update(text).digest('hex');
+    if (got !== entry.sha256) return _rejected(`cache record ${name} failed its integrity digest (interrupted write or corruption)`);
+    try { parsed[name] = JSON.parse(text); }
+    catch { return _rejected(`cache record ${name} does not parse`); }
   }
+  if (!parsed[FILES_PATH] || typeof parsed[FILES_PATH] !== 'object' || Array.isArray(parsed[FILES_PATH])) return _rejected('cache record files.json has the wrong shape');
+  if (!parsed[SUMMARIES_PATH] || typeof parsed[SUMMARIES_PATH] !== 'object') return _rejected('cache record summaries.json has the wrong shape');
+  if (parsed[DEPS_PATH] !== null && (typeof parsed[DEPS_PATH] !== 'object' || (parsed[DEPS_PATH] && parsed[DEPS_PATH].schema !== 'dep-graph/1'))) {
+    return _rejected('cache dependency graph has an incompatible schema');
+  }
+  return {
+    version: manifest.version,
+    generation: manifest.generation || null,
+    files: parsed[FILES_PATH],
+    summaries: parsed[SUMMARIES_PATH],
+    deps: parsed[DEPS_PATH],
+    replay: parsed[REPLAY_PATH],
+  };
 }
 
 function _emptyState() {
-  return { version: null, files: {}, summaries: {} };
+  return { version: null, files: {}, summaries: {}, deps: null, replay: null };
 }
 
-function _readJsonOrEmpty(fp, fallback) {
-  try {
-    if (!fs.existsSync(fp)) return fallback;
-    return JSON.parse(fs.readFileSync(fp, 'utf8'));
-  } catch (_e) {
-    return fallback;
-  }
+function _rejected(reason) {
+  return { ..._emptyState(), rejected: reason };
 }
 
 /**
@@ -78,6 +113,7 @@ function _readJsonOrEmpty(fp, fallback) {
  * Returns `{ valid: boolean, reason?: string }`.
  */
 export function validateIncrementalState(state, currentVersion) {
+  if (state && state.rejected) return { valid: false, reason: state.rejected };
   if (!state || !state.version) return { valid: false, reason: 'no prior state' };
   if (!currentVersion) return { valid: false, reason: 'no current version' };
   if (state.version.scanner !== currentVersion.scanner) return { valid: false, reason: 'scanner version changed' };
@@ -163,7 +199,19 @@ export function seedSummaryCache(summaryCache, persisted, reusableQids) {
       mutatedThisFields: new Set(s.mutatedThisFields || []),
       taintedGlobals: new Set(s.taintedGlobals || []),
       findings: Array.isArray(s.findings) ? s.findings : [],
+      // DAG-07 R07.3: provenance of a restored summary. Never serialized
+      // (serializeSummaries copies named fields only), so it cannot leak back
+      // into the persisted state; SummaryCache reads it to tell a restored
+      // empty-entry summary standing in for a tainted context from a computed one.
+      _incrementalSeed: true,
     };
+    if (Number.isInteger(s.findingsTruncated) && s.findingsTruncated > 0) {
+      // Findings beyond the persist cap were dropped when this was saved, so
+      // reuse is a partial replay of what the function reported.
+      summary._findingsTruncated = s.findingsTruncated;
+      if (summaryCache._incrementalFindingsTruncated === undefined) summaryCache._incrementalFindingsTruncated = 0;
+      summaryCache._incrementalFindingsTruncated += 1;
+    }
     // Use the bottom taint-state key — these are summaries that DON'T depend
     // on entry taint state (e.g., pure functions). Higher-fidelity reuse
     // would require persisting the entry-state hash too; deferred.
@@ -198,59 +246,213 @@ export function seedSummaryCache(summaryCache, persisted, reusableQids) {
 export function serializeSummaries(summaryCache) {
   const out = {};
   if (!summaryCache || !summaryCache._cache) return out;
+  // DAG-07 R07.3. The cache key is `<qid>::<entryHash>[@caller][::receiver]`
+  // and a qid itself contains `::`, so the old `key.split('::')[0]` reduced
+  // every key to its FILE and let whichever entry context was written last
+  // stand for the whole file. Only the EMPTY-entry summary is a statement
+  // about what a function does when nothing tainted flows in; a summary
+  // computed under a tainted entry must never be restored as that. Parse the
+  // key from the right, persist the empty-entry summary under the real qid,
+  // and count what was not persisted so reuse can be reported honestly.
+  const EMPTY_SUFFIX = '::empty';
   let count = 0;
+  const skippedContexts = new Map();
   for (const [key, summary] of summaryCache._cache) {
-    if (count >= MAX_PERSISTED_SUMMARIES) break;
     if (!summary || summary._budgetExceeded || summary._recursive) continue;
-    const qid = key.split('::')[0];
+    if (!key.endsWith(EMPTY_SUFFIX)) {
+      const m = /^(.*?::[^:]*@\d+)::/.exec(key);
+      const q = m ? m[1] : key;
+      skippedContexts.set(q, (skippedContexts.get(q) || 0) + 1);
+      continue;
+    }
+    const qid = key.slice(0, -EMPTY_SUFFIX.length);
     if (!qid) continue;
+    if (count >= MAX_PERSISTED_SUMMARIES) break;
+    const findings = Array.isArray(summary.findings) ? summary.findings : [];
     out[qid] = {
       returnTainted: !!summary.returnTainted,
       mutatedParams: [...(summary.mutatedParams || [])],
       mutatedThisFields: [...(summary.mutatedThisFields || [])],
       taintedGlobals: [...(summary.taintedGlobals || [])],
-      findings: Array.isArray(summary.findings) ? summary.findings.slice(0, 50) : [],
+      findings: findings.slice(0, 50),
+      entryContext: 'empty',
+      ...(findings.length > 50 ? { findingsTruncated: findings.length - 50 } : {}),
     };
     count++;
   }
+  for (const [q, n] of skippedContexts) if (out[q]) out[q].contextsNotPersisted = n;
   return out;
 }
 
+// ── DAG-05 R05.3: typed, context-keyed persistence ──────────────────────────
+
+/**
+ * A copy of a finding that survives JSON. An expression-object `callee` is kept as a structural copy:
+ * it is plain data, equal by value to the original, and only the backward slicer compares it by
+ * reference (replay is refused under that option). Returns null when the value cannot be serialised
+ * at all (a cycle), which makes the owner non-replayable rather than lossy.
+ */
+export function jsonSafeFinding(f) {
+  try { return JSON.parse(JSON.stringify(f)); } catch { return null; }
+}
+
+export const CONTEXT_SCHEMA = 'summary-context/1';
+const MAX_FINDINGS_PER_CONTEXT = 200;
+
+/**
+ * Every computed context of every function, each under its COMPLETE key: qid,
+ * the canonical entry-taint list, the state hash derived from it and the
+ * receiver hash. A context is either persisted whole or counted in `skipped`
+ * with the reason; it is never reduced to the empty-entry slot.
+ *
+ *   { schema, contexts: { qid: [ { entry:[...], stateHash, recv, summary } ] }, skipped: { reason: n } }
+ */
+export function serializeContexts(summaryCache) {
+  const contexts = {};
+  const skipped = {};
+  const note = (r) => { skipped[r] = (skipped[r] || 0) + 1; };
+  if (!summaryCache || !summaryCache._cache) return { schema: CONTEXT_SCHEMA, contexts, skipped };
+  const meta = summaryCache._meta;
+  let count = 0;
+  for (const [key, summary] of summaryCache._cache) {
+    if (!summary) continue;
+    if (summary._budgetExceeded) { note('budget-exceeded'); continue; }
+    if (summary._recursive) { note('recursion-stub'); continue; }
+    const m = meta && meta.get(key);
+    if (!m) { note('no-key-metadata'); continue; }
+    const findings = Array.isArray(summary.findings) ? summary.findings : [];
+    if (findings.length > MAX_FINDINGS_PER_CONTEXT) { note('findings-over-cap'); continue; }
+    const safe = [];
+    let ok = true;
+    for (const f of findings) { const c = jsonSafeFinding(f); if (c === null) { ok = false; break; } safe.push(c); }
+    if (!ok) { note('findings-not-serialisable'); continue; }
+    if (count >= MAX_PERSISTED_SUMMARIES) { note('persist-cap'); continue; }
+    (contexts[m.qid] ||= []).push({
+      entry: m.entry, stateHash: m.stateHash, recv: m.recv || null,
+      summary: {
+        returnTainted: !!summary.returnTainted,
+        mutatedParams: [...(summary.mutatedParams || [])].sort(),
+        mutatedThisFields: [...(summary.mutatedThisFields || [])].sort(),
+        taintedGlobals: [...(summary.taintedGlobals || [])].sort(),
+        findings: safe,
+      },
+    });
+    count++;
+  }
+  for (const q of Object.keys(contexts)) contexts[q].sort((a, b) => (a.stateHash + (a.recv || '') < b.stateHash + (b.recv || '') ? -1 : 1));
+  return { schema: CONTEXT_SCHEMA, contexts, skipped };
+}
+
+/**
+ * Restore persisted contexts for the given function ids. Each record is checked
+ * (shape, entry list reproduces its state hash) before it is stored under its
+ * real key; a record that fails is counted and ignored, so the function simply
+ * recomputes that context. Returns { restored, rejected }.
+ */
+export function restoreContexts(summaryCache, persisted, qids) {
+  let restored = 0; let rejected = 0;
+  if (!summaryCache || !persisted || persisted.schema !== CONTEXT_SCHEMA || !persisted.contexts) return { restored, rejected };
+  for (const qid of qids) {
+    for (const rec of persisted.contexts[qid] || []) {
+      const s = rec && rec.summary;
+      if (!s || !Array.isArray(rec.entry) || typeof rec.stateHash !== 'string' || !Array.isArray(s.findings)) { rejected++; continue; }
+      const summary = {
+        returnTainted: !!s.returnTainted,
+        mutatedParams: new Set(s.mutatedParams || []),
+        mutatedThisFields: new Set(s.mutatedThisFields || []),
+        taintedGlobals: new Set(s.taintedGlobals || []),
+        findings: s.findings,
+      };
+      if (summaryCache.restoreContext(qid, rec.entry, rec.recv || null, rec.stateHash, summary)) restored++; else rejected++;
+    }
+  }
+  return { restored, rejected };
+}
+
 /**
- * Commit incremental state to disk. Idempotent — safe to call from anywhere.
+ * Commit incremental state to disk. Idempotent: safe to call from anywhere.
  *
  *   state.files       { filepath: sha256 }
  *   state.summaries   { qid: summary }      (output of serializeSummaries)
  *   state.callers     { qid: [callerQid] }  (reverse call-graph)
+ *   state.deps        DAG-05 dependency model + global components (or null)
+ *   state.replay      DAG-05 typed contexts / exit states / findings (or null)
  *   currentVersion    { scanner, rules }
+ *
+ * DAG-05 R05.6: atomic. Every data file is written to a uniquely named temp file
+ * and fsynced, then renamed over its final name, and the manifest (version.json,
+ * which holds each file's SHA-256) is renamed LAST. A crash anywhere in that
+ * sequence leaves either the previous manifest with data it no longer matches, or
+ * a half-renamed set; `readIncrementalState` rejects both whole, so the next scan
+ * is cold, never a mixture of two generations. `io` is a seam for tests that
+ * simulate the crash (`io.renameSync`).
  */
-export function commitIncrementalState(projectRoot, state, currentVersion) {
+export function commitIncrementalState(projectRoot, state, currentVersion, io = {}) {
   if (!projectRoot) return false;
   const dir = statePath(projectRoot, 'incremental');
+  const rename = io.renameSync || fs.renameSync;
+  const gen = crypto.randomBytes(6).toString('hex');
+  const temps = [];
   try {
-    if (!stateWritesEnabled()) return;
-  fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, VERSION_PATH), JSON.stringify(currentVersion, null, 2));
-    fs.writeFileSync(path.join(dir, FILES_PATH), JSON.stringify(state.files || {}, null, 2));
-    const payload = {
-      summaries: state.summaries || {},
-      callers: state.callers || {},
+    if (!stateWritesEnabled()) return false;
+    fs.mkdirSync(dir, { recursive: true });
+    const payloads = {
+      [FILES_PATH]: state.files || {},
+      [SUMMARIES_PATH]: { summaries: state.summaries || {}, callers: state.callers || {} },
+      [DEPS_PATH]: state.deps || null,
+      [REPLAY_PATH]: state.replay || null,
     };
-    fs.writeFileSync(path.join(dir, SUMMARIES_PATH), JSON.stringify(payload));
+    const listed = {};
+    for (const name of DATA_FILES) {
+      const text = JSON.stringify(payloads[name]);
+      listed[name] = { sha256: crypto.createHash('sha256').update(text).digest('hex'), bytes: Buffer.byteLength(text) };
+      const tmp = path.join(dir, `${name}.tmp-${gen}`);
+      temps.push(tmp);
+      _writeFileTemp(tmp, text);
+    }
+    const manifest = { format: INCREMENTAL_FORMAT, generation: gen, version: currentVersion, files: listed };
+    const manifestTmp = path.join(dir, `${VERSION_PATH}.tmp-${gen}`);
+    temps.push(manifestTmp);
+    _writeFileTemp(manifestTmp, JSON.stringify(manifest, null, 2));
+    for (const name of DATA_FILES) rename(path.join(dir, `${name}.tmp-${gen}`), path.join(dir, name));
+    rename(manifestTmp, path.join(dir, VERSION_PATH));
+    _sweepTemps(dir, gen);
     return true;
   } catch (_e) {
+    // Leave whatever the crash left: the reader rejects an inconsistent set. Only
+    // our own temp files are removed, and only the ones not yet renamed.
+    for (const t of temps) { try { if (fs.existsSync(t)) fs.unlinkSync(t); } catch { /* best effort */ } }
     return false;
   }
 }
 
-/** Drop persisted state — used when a version mismatch is detected. */
+// No fsync, on purpose: the reader checks the SHA-256 of every file the manifest names, so a write
+// that did not reach the disk (power loss) is detected and rejected whole and the next scan is cold.
+// Durability is not what protects the cache; the digest check is. An fsync per file cost more than
+// the analysis it saved on a small edit.
+function _writeFileTemp(fp, text) {
+  fs.writeFileSync(fp, text, { mode: 0o600 });
+}
+
+/** Remove temp files left by an earlier interrupted commit (never the current one's). */
+function _sweepTemps(dir, keepGen) {
+  try {
+    for (const n of fs.readdirSync(dir)) {
+      if (/\.tmp-[0-9a-f]+$/.test(n) && !n.endsWith(`.tmp-${keepGen}`)) { try { fs.unlinkSync(path.join(dir, n)); } catch { /* best effort */ } }
+    }
+  } catch { /* best effort */ }
+}
+
+/** Drop persisted state, used when a version mismatch is detected. */
 export function dropIncrementalState(projectRoot) {
   const dir = statePath(projectRoot, 'incremental');
   try {
     if (!fs.existsSync(dir)) return true;
-    for (const fn of [VERSION_PATH, FILES_PATH, SUMMARIES_PATH]) {
-      const fp = path.join(dir, fn);
-      if (fs.existsSync(fp)) fs.unlinkSync(fp);
+    for (const fn of fs.readdirSync(dir)) {
+      if (DATA_FILES.includes(fn) || fn === VERSION_PATH || /\.tmp-[0-9a-f]+$/.test(fn)) {
+        const fp = path.join(dir, fn);
+        if (fs.existsSync(fp)) fs.unlinkSync(fp);
+      }
     }
     return true;
   } catch (_e) {

package/src/dataflow/index.js

@@ -6,11 +6,9 @@ import { applyPathFeasibility, buildConstantFnMap } from './path-feasibility.js'
 import { SummaryCache, entryStateFromCall } from './summaries.js';
 import { rhsReachableFunctions, shouldAnalyzeUnderRhs } from './tabulation.js';
 import { annotateBackwardSlices } from './backward.js';
-import {
-  readIncrementalState, validateIncrementalState, diffFileHashes,
-  hashFileContent, pickReusableSummaries, seedSummaryCache,
-  serializeSummaries, commitIncrementalState,
-} from './incremental.js';
+// DAG-05: dependency-complete incremental analysis (see incremental-session.js).
+import { beginIncrementalSession, engineOptionsFor, finishIncrementalSession } from './incremental-session.js';
+import { demandEnabled, runDemandQueries } from './demand-query.js'; // DAG-02
 import { buildPointsTo } from './points-to.js';
 import { buildClassHierarchy, annotateRTA } from '../ir/class-hierarchy.js';
 import { annotateSoftTaint } from './soft-taint.js';
@@ -34,57 +32,15 @@ export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
   // P2.1 — RHS-lite reachability slice. When AGENTIC_SECURITY_RHS=1 the
   // engine narrows analysis to sink-reachable functions. Default OFF
   // because it changes the finding-set composition.
+  let rhsCompletion = null;
   if (process.env.AGENTIC_SECURITY_RHS === '1') {
     const ctx = rhsReachableFunctions(perFileIR, callGraph);
+    rhsCompletion = ctx.completion || null;
     if (ctx.reachable) {
       opts = { ...opts, _rhsReachable: ctx.reachable, _rhsCheck: shouldAnalyzeUnderRhs };
     }
   }
-  // v0.69 — cross-scan incremental cache (AGENTIC_SECURITY_INCREMENTAL=1).
-  // Read persisted state, seed the SummaryCache with summaries from files
-  // whose content hasn't changed, then hand it to runTaintEngine. After,
-  // serialize the cache and commit to disk.
   const incrementalEnabled = process.env.AGENTIC_SECURITY_INCREMENTAL === '1';
-  let preSeededCache = null;
-  let priorState = null;
-  let currentFileHashes = null;
-  if (incrementalEnabled && opts.scanRoot && opts.fileContents) {
-    priorState = readIncrementalState(opts.scanRoot);
-    const currentVersion = {
-      scanner: opts.scannerVersion || 'unknown',
-      rules: opts.rulesDigest || `catalog:${_catalogSize()}`,
-    };
-    // Compute current file hashes UNCONDITIONALLY — the first scan (and any
-    // scan after a version/rule invalidation) must persist a baseline so the
-    // NEXT scan has something to reuse. This previously lived inside the
-    // valid-state branch, so a cold cache never committed and incremental was
-    // a permanent no-op (the commit guard at the bottom keys on currentFileHashes).
-    currentFileHashes = {};
-    for (const [fp, content] of Object.entries(opts.fileContents)) {
-      currentFileHashes[fp] = hashFileContent(content);
-    }
-    const valid = validateIncrementalState(priorState, currentVersion);
-    if (valid.valid) {
-      const diff = diffFileHashes(priorState.files || {}, currentFileHashes);
-      const changedQids = new Set();
-      // Map a changed file to the qids it owns. perFileIR exposes file→fns.
-      for (const fp of [...diff.changed, ...diff.added, ...diff.removed]) {
-        const ir = perFileIR[fp];
-        if (!ir) continue;
-        for (const fn of (ir.functions || [])) changedQids.add(fn.qid);
-      }
-      const persistedPayload = (priorState.summaries && priorState.summaries.summaries) || priorState.summaries || {};
-      const callerOfQid = (priorState.summaries && priorState.summaries.callers) || {};
-      const { reusable } = pickReusableSummaries(persistedPayload, callerOfQid, changedQids);
-      preSeededCache = new SummaryCache();
-      const seededN = seedSummaryCache(preSeededCache, persistedPayload, reusable);
-      preSeededCache._incrementalSeeded = seededN;
-      preSeededCache._incrementalReusable = reusable.size;
-    } else {
-      // Stale → caller should drop; we just don't seed.
-      priorState = null;
-    }
-  }
   // PRD R6/R11 (docs/DETECTION_GAP_REMEDIATION_PRD.md): Class Hierarchy
   // Analysis. Built once per scan (mirrors the points-to graph immediately
   // below) and threaded through opts so the taint engine can (a) narrow
@@ -119,12 +75,18 @@ export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
   // Runs the formal Reps-Horwitz-Sagiv tabulation in parallel with the
   // worklist engine. We MERGE findings — the IFDS solver may catch
   // context-sensitive flows the k=2 cache joined out. Deduped by sink+line.
+  // DAG-05: the session decides warm or cold from content fingerprints (it needs the
+  // call graph and class hierarchy built above) and restores typed contexts.
+  const incrementalSession = beginIncrementalSession({ enabled: incrementalEnabled, opts, perFileIR, callGraph, cha: classHierarchy });
   let findings = runTaintEngine(perFileIR, callGraph, {
     ...opts,
-    summaryCache: preSeededCache || undefined,
+    ...engineOptionsFor(incrementalSession),
     _pointsTo: pointsToGraph || undefined,
     _cha: classHierarchy || undefined,
   });
+  const engineOutput = findings;
+  // DAG-05: provenance + persistence happen right after the engine, on the engine's own array.
+  const incrementalStats = finishIncrementalSession(incrementalSession, engineOutput);
   if (process.env.AGENTIC_SECURITY_IFDS === '1') {
     try {
       const ifdsFindings = runIfdsTaintEngine(perFileIR, callGraph, opts);
@@ -152,16 +114,20 @@ export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
       }
     } catch { /* privacy-deep failure should not fail the scan */ }
   }
+  // DAG-02 begin (demand-driven sink queries; opt-in, additive, never changes `findings`)
+  if (demandEnabled() && Array.isArray(opts.demandQueries) && opts.demandQueries.length) {
+    try {
+      const demandResults = runDemandQueries(perFileIR, callGraph, opts.demandQueries, { ...(opts.demandOpts || {}), engineOpts: { ...opts, _cha: classHierarchy || undefined, _pointsTo: pointsToGraph || undefined } });
+      Object.defineProperty(findings, '_demandResults', { value: demandResults, enumerable: false });
+    } catch { /* demand queries must never fail the scan */ }
+  }
+  // DAG-02 end
   for (const f of findings) f._pathFeasibilityPruned = totalPruned;
-  if (preSeededCache) {
-    Object.defineProperty(findings, '_incrementalStats', {
-      value: {
-        seeded: preSeededCache._incrementalSeeded || 0,
-        reusable: preSeededCache._incrementalReusable || 0,
-      },
-      enumerable: false,
-    });
+  if (incrementalStats) {
+    Object.defineProperty(findings, '_incrementalStats', { value: incrementalStats, enumerable: false });
+    if (findings !== engineOutput) Object.defineProperty(engineOutput, '_incrementalStats', { value: incrementalStats, enumerable: false });
   }
+  if (rhsCompletion) Object.defineProperty(findings, '_rhsCompletion', { value: rhsCompletion, enumerable: false });
   // P1.4 — backward slice (opt-in via AGENTIC_SECURITY_BACKWARD_SLICE=1).
   // Next-gen taint capability #5 (SMT path-feasibility rebuild): ALSO run
   // this when AGENTIC_SECURITY_SYMEXEC=1 is set, even if the operator never
@@ -221,43 +187,8 @@ export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
       }
     } catch { /* prover failure should not fail the scan */ }
   }
-  // v0.69 — commit incremental state after a successful scan.
-  if (incrementalEnabled && opts.scanRoot && currentFileHashes) {
-    const cache = findings._summaryCache;
-    const summaries = cache ? serializeSummaries(cache) : {};
-    // Reverse call-graph (qid → callers) — derive from callGraph.
-    const callers = {};
-    if (callGraph && callGraph.functions) {
-      for (const fn of callGraph.functions.values()) {
-        if (!Array.isArray(fn.calls)) continue;
-        for (const c of fn.calls) {
-          // fn.calls entries are objects ({site, callee, args, line}); using one
-          // as an object key stringifies it to "[object Object]" and collapses
-          // every entry into a single bogus bucket. Key by the RESOLVED qid so
-          // this map is queryable by the qids the worklist actually uses.
-          const name = c && typeof c === 'object' ? c.callee : c;
-          if (!name) continue;
-          // resolveKnownCallee (not resolve): a raw fn.calls name may be a
-          // flattened member-call string ("loader.read"); the plain
-          // resolve() would guess via its bare-tail fallback and invent an
-          // edge to an unrelated same-named function. See callgraph.js.
-          const qid = callGraph.resolveKnownCallee ? callGraph.resolveKnownCallee(name, fn.file) : null;
-          if (!qid) continue;
-          if (!callers[qid]) callers[qid] = [];
-          callers[qid].push(fn.qid);
-        }
-      }
-    }
-    commitIncrementalState(opts.scanRoot, {
-      files: currentFileHashes,
-      summaries,
-      callers,
-    }, {
-      scanner: opts.scannerVersion || 'unknown',
-      rules: opts.rulesDigest || `catalog:${_catalogSize()}`,
-    });
-  }
   return findings;
 }
 
+export { demandEnabled, runDemandQueries } from './demand-query.js'; // DAG-02
 export { runTaintEngine, CATALOG, matchSource, matchSinkOrSanitizer, _catalogSize, applyPathFeasibility, buildConstantFnMap, SummaryCache, entryStateFromCall, rhsReachableFunctions, shouldAnalyzeUnderRhs, annotateBackwardSlices };

package/src/dataflow/summaries.js

@@ -52,12 +52,22 @@ function _hashState(taintedParams) {
   return crypto.createHash('sha256').update(sorted).digest('hex').slice(0, 12);
 }
 
+// DAG-05 R05.3: the canonical entry list a key was derived from, so a persisted
+// context can carry its COMPLETE key (qid, entry state, receiver) and be checked
+// on reload rather than trusted by hash alone.
+function entryListOf(taintedParams) {
+  if (!taintedParams || taintedParams.size === 0) return [];
+  return [...canonicalizeAccessSet(taintedParams)].sort();
+}
+
 export class SummaryCache {
   constructor() {
     this._cache = new Map(); // qid::hash → summary
     this._stack = new Set(); // qids currently being analyzed (recursion guard)
     this._iter = 0;
-    this._maxIter = 5000;
+    // Computation budget for one scan. AGENTIC_SECURITY_SUMMARY_BUDGET raises (or lowers) it; the default is unchanged.
+    const envBudget = Number(process.env.AGENTIC_SECURITY_SUMMARY_BUDGET);
+    this._maxIter = Number.isFinite(envBudget) && envBudget > 0 ? Math.floor(envBudget) : 5000;
     // FR-SEM-2 (roadmap #2): the engine computes a distinct summary per
     // entry-taint-state (value-context sensitivity), computed lazily at call
     // sites. To stop that from blowing up when a hot helper is reached under
@@ -70,6 +80,13 @@ export class SummaryCache {
     const envCap = Number(process.env.AGENTIC_SECURITY_KCFA_MAX_CONTEXTS);
     this._maxContextsPerFn = Number.isFinite(envCap) && envCap >= 0 ? envCap : 16;
     this._contextCapHits = 0;
+    // DAG-07 R07.3: append-only record of every place a result is coarser
+    // than a fresh analysis would give: a tainted entry answered with the
+    // empty-entry summary (context cap), a recursion refinement that was still
+    // changing when its rounds ran out, and the subset of cap fallbacks whose
+    // empty-entry summary was restored from a previous scan rather than
+    // computed in this one.
+    this._notes = [];
     // R2 (PRD §5): bounded k=1 call-string sensitivity. OPT-IN (default OFF).
     // When on, the cache key is extended with the immediate caller's qid, so two
     // call paths reaching a helper with the SAME tainted-arg shape get DISTINCT
@@ -78,6 +95,9 @@ export class SummaryCache {
     // before, so no behavior change for the shipped engine.
     this._callString = process.env.AGENTIC_SECURITY_KCFA_CALLSTRING === '1';
     this._callerCtx = null;
+    // DAG-05 R05.3: key -> { qid, entry:[...], stateHash, recv } for every key this
+    // cache has produced, so cross-scan persistence can store typed contexts.
+    this._meta = new Map();
   }
 
   // Set the immediate-caller qid for call-string keying; returns the previous
@@ -111,8 +131,38 @@ export class SummaryCache {
     // caller dimension there only ever narrows an already-isolated lookup,
     // never disconnects a shared one.
     if (this._callString && this._callerCtx && stateHash !== 'empty') base = `${base}@${this._callerCtx}`;
-    if (!receiverType) return base;
-    return `${base}::${hashReceiverType(receiverType)}`;
+    const finalKey = receiverType ? `${base}::${hashReceiverType(receiverType)}` : base;
+    if (!this._meta.has(finalKey)) {
+      this._meta.set(finalKey, {
+        qid, entry: entryListOf(taintedParams), stateHash,
+        recv: receiverType ? hashReceiverType(receiverType) : null,
+      });
+    }
+    return finalKey;
+  }
+
+  /**
+   * DAG-05 R05.3: restore a persisted context under its REAL key. Never writes
+   * the empty-entry slot on behalf of a tainted context: the key is rebuilt from
+   * the persisted entry list and refused unless it reproduces the persisted hash.
+   * Returns false (nothing stored) on any mismatch.
+   */
+  restoreContext(qid, entryList, recv, stateHash, summary) {
+    if (!qid || !Array.isArray(entryList) || !summary) return false;
+    const entry = new Set(entryList);
+    const h = _hashState(entry);
+    if (h !== stateHash) return false;
+    if (this._callString && h !== 'empty') return false;
+    const base = `${qid}::${h}`;
+    const key = recv ? `${base}::${recv}` : base;
+    this._cache.set(key, summary);
+    this._meta.set(key, { qid, entry: entryListOf(entry), stateHash: h, recv: recv || null });
+    if (h !== 'empty') {
+      let ctxs = this._contextsByQid.get(qid);
+      if (!ctxs) { ctxs = new Set(); this._contextsByQid.set(qid, ctxs); }
+      ctxs.add(h);
+    }
+    return true;
   }
 
   get(qid, taintedParams, receiverType) {
@@ -156,7 +206,11 @@ export class SummaryCache {
       if (!ctxs.has(stateHash) && ctxs.size >= this._maxContextsPerFn) {
         this._contextCapHits++;
         const base = this._cache.get(this._key(qid, new Set()));
-        if (base && !base._recursive) return base;
+        if (base && !base._recursive) {
+          this._notes.push({ reason: 'context-cap-fallback', qid });
+          if (base._incrementalSeed) this._notes.push({ reason: 'incremental-empty-entry-reuse', qid });
+          return base;
+        }
         // No base summary yet → fall through and compute this one (we need a
         // result), but don't grow the context set.
       } else {
@@ -178,13 +232,15 @@ export class SummaryCache {
       this._cache.set(k, summary);
       if (this._hitRecursion) {
         const FP_MAX = 3;
+        let converged = false;
         for (let fp = 0; fp < FP_MAX; fp++) {
           if (++this._iter > this._maxIter) break;
           const prev = summary;
           summary = analyze(qid, taintedParams);
-          if (_summaryEq(prev, summary)) break;
+          if (_summaryEq(prev, summary)) { converged = true; break; }
           this._cache.set(k, summary);
         }
+        if (!converged) this._notes.push({ reason: 'recursion-nonconverged', qid });
       }
       if (summary._recursive) delete summary._recursive;
       return summary;
@@ -224,7 +280,17 @@ export class SummaryCache {
   }
 
   size() { return this._cache.size; }
-  clear() { this._cache.clear(); this._iter = 0; this._contextsByQid.clear(); this._contextCapHits = 0; }
+  clear() { this._cache.clear(); this._iter = 0; this._contextsByQid.clear(); this._contextCapHits = 0; this._notes = []; }
+
+  /** DAG-07 R07.3: [{reason, count, example}] over everything recorded in `_notes`, sorted by reason. */
+  completionNotes() {
+    const byReason = new Map();
+    for (const n of this._notes) {
+      const cur = byReason.get(n.reason);
+      if (cur) cur.count += 1; else byReason.set(n.reason, { reason: n.reason, count: 1, example: String(n.qid ?? '').slice(0, 160) });
+    }
+    return [...byReason.values()].sort((a, b) => (a.reason < b.reason ? -1 : 1));
+  }
 }
 
 // Stage 3 correctness audit (detection depth): this compared mutatedParams