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

package/src/dataflow/ir-cache.js

@@ -0,0 +1,268 @@
+// Cross-scan cache of parsed JavaScript / TypeScript IR (DAG-05, the stage the taint cache does not cover).
+//
+// The dependency-complete taint cache (incremental-session.js) removes most of the cost of the interprocedural
+// engine on a re-scan, and what is left is dominated by parsing every file to IR again. This module keeps one
+// record per source file so an unchanged file is read back instead of parsed. It changes the cost of building
+// the IR and never its content:
+//
+//   * A record is keyed by the SHA-256 of the file's path and text, the analyzer/parser digest (a change to any
+//     source under ir/, dataflow/, graph/ or language/, or to the bundle, invalidates every record) and the
+//     Babel versions the parse ran under. A different file text, parser or toolchain is a miss.
+//   * The IR numbers its CFG nodes from a process-global counter (`n123`). A restored file is given fresh ids
+//     from the same counter, in the same relative order, so an id is as unique across the process as one the
+//     parser made. Ids appear only in the fields remapped below; a file that holds an id anywhere else is
+//     never written.
+//   * A record is written only after the IR has been checked to survive JSON exactly: anything that would not
+//     (an undefined member, a non-finite number, a BigInt, a Map, an object with a foreign prototype, an id
+//     held in a field the remap does not know) is not cached, and that file is parsed every scan. Regular
+//     expressions, which JSON would turn into `{}`, are recorded by path and rebuilt on load.
+//   * Each record carries the SHA-256 of its payload; a truncated, edited or foreign file is a miss, never an
+//     error. Writes go to a temp file and are renamed into place.
+//
+// Scope: JavaScript and TypeScript only (the parser that owns the id counter). Every other language is parsed
+// as before. Trust boundary: the same as the rest of the incremental state under .agentic-security/incremental
+// (digests detect corruption; they are not a signature, so a hostile working tree that plants a consistent
+// record could substitute an IR; a planted record must also match the file's exact text and the analyzer digest).
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+
+import { reserveNodeIds } from '../ir/parser-js.js';
+import { analyzerDigest } from './dep-fingerprint.js';
+import { statePath, stateWritesEnabled } from '../posture/state-dir.js';
+
+const IR_CACHE_FORMAT = 'ir-cache/1';
+const ID_RE = /^n\d+$/;
+const ID_NUM = (s) => Number(s.slice(1));
+
+let _toolchain = null;
+function toolchainDigest() {
+  if (_toolchain) return _toolchain;
+  const parts = [IR_CACHE_FORMAT, analyzerDigest()];
+  try {
+    const req = createRequire(import.meta.url);
+    for (const pkg of ['@babel/core', '@babel/preset-react', '@babel/preset-typescript', '@babel/parser']) {
+      try { parts.push(`${pkg}@${req(`${pkg}/package.json`).version}`); } catch { parts.push(`${pkg}@unresolved`); }
+    }
+  } catch { parts.push('toolchain@unresolved'); }
+  _toolchain = crypto.createHash('sha256').update(parts.join('\n')).digest('hex');
+  return _toolchain;
+}
+
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+// ── id handling ─────────────────────────────────────────────────────────────
+
+/** Every node id of a file's IR, or null when the IR holds something this cache cannot place. */
+function fileIds(ir) {
+  if (!ir || !Array.isArray(ir.functions)) return null;
+  const ids = [];
+  for (const fn of ir.functions) {
+    if (!fn || !fn.cfg || !fn.cfg.nodes || typeof fn.cfg.nodes !== 'object') return null;
+    for (const k of Object.keys(fn.cfg.nodes)) { if (!ID_RE.test(k)) return null; ids.push(k); }
+  }
+  return ids;
+}
+
+/**
+ * Give an IR read back from a record new ids. Throws when a reference names an id the file does not define:
+ * the caller treats that as a miss.
+ */
+function remapIds(ir) {
+  const ids = fileIds(ir);
+  if (!ids) throw new Error('unplaceable ids');
+  ids.sort((a, b) => ID_NUM(a) - ID_NUM(b));
+  const base = reserveNodeIds(ids.length);
+  const map = new Map();
+  ids.forEach((id, i) => map.set(id, `n${base + i + 1}`));
+  const m = (id) => { const v = map.get(id); if (v === undefined) throw new Error(`dangling id ${id}`); return v; };
+  for (const fn of ir.functions) {
+    const cfg = fn.cfg;
+    cfg.entry = m(cfg.entry);
+    cfg.exit = m(cfg.exit);
+    const entries = Object.entries(cfg.nodes);
+    for (const [k, node] of entries) {
+      if (node.id !== k) throw new Error('node id differs from its key');
+      node.id = m(node.id);
+      if (!Array.isArray(node.succ) || !Array.isArray(node.pred)) throw new Error('node without edges');
+      node.succ = node.succ.map(m);
+      node.pred = node.pred.map(m);
+    }
+    cfg.nodes = Object.fromEntries(entries.map(([k, node]) => [m(k), node]));
+    fn.returns = (fn.returns || []).map(m);
+    for (const c of (fn.calls || [])) c.site = m(c.site);
+    for (const list of Object.values(fn.writes || {})) for (const w of list) w.node = m(w.node);
+    for (const list of Object.values(fn.reads || {})) { for (let i = 0; i < list.length; i++) list[i] = m(list[i]); }
+  }
+  return ir;
+}
+
+/**
+ * The IR as text with every node id replaced by its rank among the file's ids, and regular expressions kept
+ * distinct from `{}`. Two IRs that differ only in the ids they were numbered with give the same text. Used by
+ * the tests that prove a restored IR equals a fresh parse.
+ */
+function canonical(ir) {
+  const ids = fileIds(ir);
+  if (!ids) return null;
+  ids.sort((a, b) => ID_NUM(a) - ID_NUM(b));
+  const rank = new Map(ids.map((id, i) => [id, `#${i}`]));
+  const walk = (v) => {
+    if (typeof v === 'string') return rank.has(v) ? rank.get(v) : v;
+    if (v instanceof RegExp) return { $re: [v.source, v.flags] };
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === 'object') {
+      const o = {};
+      for (const [k, x] of Object.entries(v)) o[rank.has(k) ? rank.get(k) : k] = walk(x);
+      return o;
+    }
+    return v;
+  };
+  return JSON.stringify(walk(ir));
+}
+
+/**
+ * One walk over a freshly parsed IR: is it exactly what JSON gives back (plus the regular expressions that are
+ * recorded by path), and does every node id sit in a field the remap knows? Returns { regexes } or null.
+ * `ids` is the set of the file's node ids.
+ */
+function analyze(ir, ids) {
+  const regexes = [];
+  let idLike = 0;
+  const trail = [];
+  const walk = (v) => {
+    switch (typeof v) {
+      case 'string': if (ids.has(v)) idLike++; return true;
+      case 'boolean': return true;
+      case 'number': return Number.isFinite(v);
+      case 'object': break;
+      default: return false; // undefined, function, symbol, bigint
+    }
+    if (v === null) return true;
+    if (v instanceof RegExp) {
+      if (v.lastIndex !== 0) return false;
+      regexes.push([trail.slice(), v.source, v.flags]);
+      return true;
+    }
+    if (Array.isArray(v)) {
+      if (Object.getPrototypeOf(v) !== Array.prototype) return false;
+      for (let i = 0; i < v.length; i++) {
+        if (!(i in v)) return false; // a hole
+        trail.push(i);
+        const ok = walk(v[i]);
+        trail.pop();
+        if (!ok) return false;
+      }
+      return true;
+    }
+    if (Object.getPrototypeOf(v) !== Object.prototype) return false;
+    for (const k of Object.keys(v)) {
+      if (ids.has(k)) idLike++;
+      trail.push(k);
+      const ok = walk(v[k]);
+      trail.pop();
+      if (!ok) return false;
+    }
+    return Object.getOwnPropertySymbols(v).length === 0;
+  };
+  if (!walk(ir)) return null;
+  // The ids the remap handles: entry, exit, each node's key and id and edges, returns, call sites, writes, reads.
+  let known = 0;
+  for (const fn of ir.functions) {
+    known += 2 + (fn.returns || []).length + (fn.calls || []).length;
+    for (const node of Object.values(fn.cfg.nodes)) {
+      if (!Array.isArray(node.succ) || !Array.isArray(node.pred)) return null;
+      known += 2 + node.succ.length + node.pred.length;
+    }
+    for (const list of Object.values(fn.writes || {})) known += list.length;
+    for (const list of Object.values(fn.reads || {})) known += list.length;
+  }
+  return idLike === known ? { regexes } : null;
+}
+
+/** Put the recorded regular expressions back where JSON left `{}` (before ids are remapped: the paths use the old ids). */
+function restoreRegexes(ir, regexes) {
+  for (const [trail, source, flags] of regexes) {
+    let holder = ir;
+    for (let i = 0; i < trail.length - 1; i++) holder = holder[trail[i]];
+    holder[trail[trail.length - 1]] = new RegExp(source, flags);
+  }
+}
+
+// ── the cache ───────────────────────────────────────────────────────────────
+
+/**
+ * Open the cache under `<state>/incremental/ir`. `read` / `write` select what it may do (a scan with state
+ * writes off still reads). Returns an object with `load`, `store` and `stats`.
+ */
+export function openIrCache(scanRoot, { read = true, write = stateWritesEnabled() } = {}) {
+  const dir = statePath(scanRoot, 'incremental', 'ir');
+  const stats = { hits: 0, misses: 0, stored: 0, skipped: 0, rejected: 0, loadMs: 0, storeMs: 0, bytesRead: 0, bytesWritten: 0 };
+  let tool = null;
+  const keyOf = (file, code) => sha(`${tool || (tool = toolchainDigest())}\0${file}\0${code}`);
+  const slotOf = (file) => path.join(dir, `${sha(file).slice(0, 40)}.ir.json`);
+
+  function readRecord(file, key) {
+    let text;
+    try { text = fs.readFileSync(slotOf(file), 'utf8'); } catch { return null; }
+    const nl = text.indexOf('\n');
+    if (nl < 0) return { bad: true };
+    let head;
+    try { head = JSON.parse(text.slice(0, nl)); } catch { return { bad: true }; }
+    if (!head || head.format !== IR_CACHE_FORMAT || head.key !== key) return null; // another file text or toolchain: a plain miss
+    const payload = text.slice(nl + 1);
+    stats.bytesRead += payload.length;
+    if (payload.length !== head.bytes || sha(payload) !== head.sha256 || !Array.isArray(head.regexes)) return { bad: true };
+    return { payload, regexes: head.regexes };
+  }
+
+  function load(file, code) {
+    if (!read) return undefined;
+    const t0 = performance.now();
+    try {
+      const key = keyOf(file, code);
+      const rec = readRecord(file, key);
+      if (!rec) { stats.misses++; return undefined; }
+      if (rec.bad) { stats.rejected++; return undefined; }
+      const parsed = JSON.parse(rec.payload);
+      restoreRegexes(parsed, rec.regexes);
+      const ir = remapIds(parsed);
+      if (!ir || ir.file !== file || !Array.isArray(ir.functions)) { stats.rejected++; return undefined; }
+      stats.hits++;
+      return ir;
+    } catch {
+      stats.rejected++;
+      return undefined;
+    } finally { stats.loadMs += performance.now() - t0; }
+  }
+
+  function store(file, code, ir) {
+    if (!write) return false;
+    const t0 = performance.now();
+    try {
+      const ids = fileIds(ir);
+      const found = ids ? analyze(ir, new Set(ids)) : null;
+      if (!found) { stats.skipped++; return false; }
+      const key = keyOf(file, code);
+      const payload = JSON.stringify(ir);
+      const head = JSON.stringify({ format: IR_CACHE_FORMAT, key, sha256: sha(payload), bytes: payload.length, file, regexes: found.regexes });
+      fs.mkdirSync(dir, { recursive: true });
+      const slot = slotOf(file);
+      const tmp = `${slot}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+      fs.writeFileSync(tmp, `${head}\n${payload}`, { mode: 0o600 });
+      fs.renameSync(tmp, slot);
+      stats.stored++;
+      stats.bytesWritten += payload.length;
+      return true;
+    } catch {
+      stats.skipped++;
+      return false;
+    } finally { stats.storeMs += performance.now() - t0; }
+  }
+
+  return { load, store, stats: () => ({ ...stats }), dir };
+}
+
+export const _internals = { remapIds, canonical, fileIds, analyze, restoreRegexes, toolchainDigest };

package/src/dataflow/privacy-taint.js

@@ -37,6 +37,7 @@ import {
   loadPrivacyTaxonomy, classifyFieldAgainst, severityForClasses,
 } from './privacy-taxonomy.js';
 import { loadPrivacySinkPolicy, isSinkPermitted, permittingRules } from './privacy-sink-policy.js';
+import { isListenCallbackParam } from '../sast/listen-bind-address.js';
 import { GOVERNANCE_FIELDS, governanceRecordFor } from './privacy-governance.js';
 
 const _BUILTIN_COMPILED = compileTaxonomy(DEFAULT_TAXONOMY);
@@ -119,8 +120,14 @@ export function annotatePrivacyTaint(perFileIR, opts = {}) {
     // (evidence locations must cover both ends of a flow, not just the
     // sink) without re-deriving it from piiFields by proximity guessing.
     const declLineByName = new Map();
+    const lineStart = [];
+    { let off = 0; for (const l of lines) { lineStart.push(off); off += l.length + 1; } }
     for (const d of ir.decls || []) {
       const classes = classifyFieldAgainst(d.name, compiled);
+      // The name alone does not make a binding personal data: the `address` a `listen` callback
+      // receives is the bound socket address (see sast/listen-bind-address.js).
+      if (classes.length && Number.isInteger(d.line) && lineStart[d.line - 1] !== undefined
+        && isListenCallbackParam(ir._content, lineStart[d.line - 1] + Math.max(0, (lines[d.line - 1] || '').indexOf(d.name)), d.name)) continue;
       if (classes.length) {
         taintedVars.set(d.name, classes);
         declLineByName.set(d.name, d.line);

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

package/src/dataflow/tabulation.js

@@ -67,53 +67,107 @@ export function enumerateSinks(perFileIR, callGraph) {
 }
 
 /**
- * RHS-lite demand-driven slice. For each sink, walk backward through the
- * intra-procedural CFG via def-use, then ascend via the call graph for
- * each unresolved parameter binding. Returns the set of fn qids that are
- * REACHABLE from the sink (and therefore worth deep-analyzing).
- *
- *   sinks:          enumerateSinks() output
- *   callGraph:      { functions, callers, callees }
- *   maxCallerDepth: bounds reverse-call-graph walk
+ * Canonical caller index: callee qid -> [caller qid]. Built from each
+ * function's recorded `calls` (statement-level call nodes) and resolved with
+ * resolveKnownCallee, never the guessing resolve(). The demand selector
+ * (demand-query.js) extends it with the embedded call sites that `fn.calls`
+ * does not record (assignment right-hand sides, return values, nested
+ * arguments, callback registrations).
  */
-export function reachabilitySliceFromSinks(sinks, callGraph, maxCallerDepth = MAX_CALLER_DEPTH) {
-  const reachableFns = new Set();
-  if (!Array.isArray(sinks) || !callGraph || !callGraph.functions) return reachableFns;
-
-  // Build a reverse callgraph: who calls fn-qid?
+export function buildCallerQidIndex(callGraph) {
   const callersOf = new Map();
+  if (!callGraph || !callGraph.functions) return callersOf;
   for (const fn of callGraph.functions.values()) {
     for (const callee of (fn.calls || [])) {
-      // callee.callee is a SOURCE-LEVEL name ("b.fill"); the worklist below
-      // looks this map up by qid, so keying by the name means the lookup can
-      // never match. Resolve to a qid first.
-      const name = callee && typeof callee === 'object' ? callee.callee : callee;
-      if (!name) continue;
+      // callee.callee is a SOURCE-LEVEL name ("b.fill"); lookups are by qid,
+      // so keying by the name could never match. Resolve to a qid first.
       // resolveKnownCallee (not resolve): callee.callee 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 name = callee && typeof callee === 'object' ? callee.callee : callee;
+      if (!name) continue;
       const qid = callGraph.resolveKnownCallee ? callGraph.resolveKnownCallee(name, fn.file) : null;
       if (!qid) continue;
       if (!callersOf.has(qid)) callersOf.set(qid, []);
       callersOf.get(qid).push(fn.qid);
     }
   }
+  return callersOf;
+}
+
+/**
+ * RHS-lite demand-driven slice. For each sink, walk backward through the
+ * intra-procedural CFG via def-use, then ascend via the call graph for
+ * each unresolved parameter binding. Returns the set of fn qids that are
+ * REACHABLE from the sink (and therefore worth deep-analyzing).
+ *
+ *   sinks:          enumerateSinks() output
+ *   callGraph:      { functions, callers, callees }
+ *   maxCallerDepth: bounds reverse-call-graph walk
+ */
+export function reachabilitySliceFromSinks(sinks, callGraph, maxCallerDepth = MAX_CALLER_DEPTH) {
+  return reachabilitySliceWithCompletion(sinks, callGraph, maxCallerDepth).reachable;
+}
+
+/**
+ * Same walk as reachabilitySliceFromSinks, plus a completion record
+ * (DAG-07 R07.1). A function the walk never reached is skipped by
+ * `shouldAnalyzeUnderRhs`, so a walk that stopped at its worklist cap or its
+ * caller-depth ceiling has silently narrowed what is analyzed; the record
+ * says so, with the number of callers left unexplored.
+ *
+ * Returns { reachable: Set<qid>, completion: { status, reasons,
+ * unexploredFrontierCount, visited, limits } }.
+ */
+export function reachabilitySliceWithCompletion(sinks, callGraph, maxCallerDepth = MAX_CALLER_DEPTH) {
+  const reachableFns = new Set();
+  const completion = {
+    status: 'complete', reasons: [], unexploredFrontierCount: 0, visited: 0,
+    limits: { maxWorklist: MAX_WORKLIST, maxCallerDepth },
+  };
+  if (!Array.isArray(sinks) || !callGraph || !callGraph.functions) {
+    completion.status = 'unavailable';
+    completion.reasons = ['no-call-graph'];
+    return { reachable: reachableFns, completion };
+  }
+
+  // Build a reverse callgraph: who calls fn-qid?
+  // DAG-02: factored into the shared, exported buildCallerQidIndex so the
+  // demand selector (demand-query.js) reuses the same canonical incoming-edge
+  // index. Behaviour is unchanged.
+  const callersOf = buildCallerQidIndex(callGraph);
 
   const work = [];
   for (const s of sinks) work.push({ qid: s.fnQid, depth: 0 });
   let visitedCount = 0;
+  let depthCut = 0;
+  let capped = false;
   while (work.length) {
-    if (++visitedCount > MAX_WORKLIST) break;
+    if (++visitedCount > MAX_WORKLIST) { capped = true; break; }
     const { qid, depth } = work.shift();
     if (reachableFns.has(qid)) continue;
     reachableFns.add(qid);
-    if (depth >= maxCallerDepth) continue;
+    if (depth >= maxCallerDepth) {
+      // Callers of this function exist but are not explored.
+      for (const callerQid of (callersOf.get(qid) || [])) if (!reachableFns.has(callerQid)) depthCut += 1;
+      continue;
+    }
     for (const callerQid of (callersOf.get(qid) || [])) {
       if (!reachableFns.has(callerQid)) work.push({ qid: callerQid, depth: depth + 1 });
     }
   }
-  return reachableFns;
+  completion.visited = visitedCount;
+  if (capped) {
+    completion.reasons.push('worklist-limit');
+    completion.unexploredFrontierCount += work.length;
+  }
+  if (depthCut > 0) {
+    completion.reasons.push('caller-depth-limit');
+    completion.unexploredFrontierCount += depthCut;
+  }
+  if (completion.reasons.length) completion.status = 'partial';
+  return { reachable: reachableFns, completion };
 }
 
 /**
@@ -128,10 +182,12 @@ export function rhsReachableFunctions(perFileIR, callGraph) {
   const sinks = enumerateSinks(perFileIR, callGraph);
   if (!sinks.length) {
     // No sinks → no demand. Return null to signal "analyze all" to caller.
-    return { reachable: null, sinks: [] };
+    // `completion` is an additive property (DAG-07 R07.1); existing callers
+    // destructure only { reachable, sinks }.
+    return { reachable: null, sinks: [], completion: { status: 'complete', reasons: [], unexploredFrontierCount: 0, visited: 0, limits: {}, note: 'no-sinks-analyze-all' } };
   }
-  const reachable = reachabilitySliceFromSinks(sinks, callGraph);
-  return { reachable, sinks };
+  const { reachable, completion } = reachabilitySliceWithCompletion(sinks, callGraph);
+  return { reachable, sinks, completion };
 }
 
 /**