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

package/src/lineage/engine.js

@@ -1,4 +1,8 @@
 import { accessPathOf, pathIsCoveredByPrefix } from '../dataflow/access-paths.js';
+import {
+  CORRELATION_VERSION_2, deriveChild, relPathOf, invocationIdOf, scopeForSubPath,
+} from './correlation.js';
+import { computeReachingDefinitions, ENTRY_VERSION } from './value-versions.js';
 import { identitiesAt, emptyState, removeIdentitiesAt, addIdentity, joinStates, statesEqual, hashState } from './field-identity.js';
 
 function noIdentity() {
@@ -57,6 +61,68 @@ function pathHasWildcard(path) {
   return path.split('.').includes('*');
 }
 
+// --- Correlation version 2 (DAG-03) -------------------------------------
+// Everything below is inert unless the caller set `ctx.correlationVersion`
+// to 2 AND attached a recorder. With either missing, `sub` returns the ctx it
+// was given (the same reference), no field is added to any hop, and the
+// analysis result and the hop stream are byte-identical to version 1.
+function isV2(ctx) {
+  return ctx?.correlationVersion === CORRELATION_VERSION_2 && typeof ctx.recordHop === 'function';
+}
+
+// Enters one sub-expression: every hop emitted at or below it is stamped with
+// the derivation path of the level that emitted it (the innermost stamp
+// wins, because an inner wrapper's fields are already on the hop when the
+// outer wrapper sees it).
+function sub(ctx, seg, stamp) {
+  if (!isV2(ctx)) return ctx;
+  const derivation = deriveChild(ctx.derivation, seg);
+  const base = ctx.recordHop;
+  return { ...ctx, derivation, recordHop: (h) => base({ derivationId: derivation, ...stamp, ...h }) };
+}
+
+// The invocation id of the call expression currently being resolved.
+function currentInvocation(ctx) {
+  const site = ctx?.siteInfo;
+  return invocationIdOf({ scope: site?.scope, nodeId: site?.nodeId, context: site?.context, derivation: ctx?.derivation });
+}
+
+// Recorder-only context for resolving the `position`-th ACTUAL argument of a
+// call during parameter binding (summaries.js). Version 1: exactly the
+// recorder-only derivation it always was. Version 2: the argument subtree is
+// stamped with the invocation, its actual position and its derivation, so an
+// argument read can pair only with the binding of the same invocation and
+// formal position.
+export function argumentContext(ctx, position) {
+  if (!ctx?.recordHop) return undefined;
+  if (!isV2(ctx)) return { recordHop: ctx.recordHop };
+  const base = {
+    recordHop: ctx.recordHop, correlationVersion: ctx.correlationVersion,
+    derivation: ctx.derivation, siteInfo: ctx.siteInfo,
+  };
+  return sub(base, `arg${position}`, { callRole: 'arg', invocationId: currentInvocation(ctx), argPosition: position });
+}
+
+/** The invocation id of the call expression a call-level ctx is resolving (version 2). */
+export function callInvocationId(ctx) {
+  return isV2(ctx) ? currentInvocation(ctx) : null;
+}
+
+/** The recorder a callee's own analysis must be handed (see `rawRecordHop`). */
+export function calleeRecorder(ctx) {
+  return ctx?.rawRecordHop ?? ctx?.recordHop;
+}
+
+// The out-half correlation stamp for a write of byPath entry `subPath` of the
+// value built by `source` (rooted at derivation `root`).
+function outStamp(ctx, source, subPath, root) {
+  if (!isV2(ctx)) return null;
+  const { scope, rest } = scopeForSubPath(source, subPath, root);
+  const allocKind = source?.kind === 'object' ? 'object'
+    : (source?.kind === 'ident' || source?.kind === 'member') ? 'alias' : null;
+  return { derivationScope: scope, relPath: rest, allocKind };
+}
+
 // --- Path provenance hop recording (Sub-project C, increment 1) ---------
 // See DESIGN_PATH_PROVENANCE.md for the full design. Only two helpers below
 // are new; everything else in this file is unchanged in shape, and the
@@ -132,6 +198,7 @@ export function resolveExprIdentities(state, expr, ctx) {
               fromPath: key, toPath: null, dataElementId: id,
               syntacticPath: key === path ? null : path,
               widenReason: null, lossReason: null,
+              ...(isV2(ctx) ? { relPath: relPathOf(key, path) } : null),
             });
           }
         }
@@ -199,6 +266,7 @@ export function resolveExprIdentities(state, expr, ctx) {
                 fromPath: key, toPath: null, dataElementId: id,
                 syntacticPath: key === path ? null : path,
                 widenReason: null, lossReason: null,
+                ...(isV2(ctx) ? { relPath: relPathOf(key, path) } : null),
               });
             }
           }
@@ -218,7 +286,7 @@ export function resolveExprIdentities(state, expr, ctx) {
       // `assign`/`object` already use) — a coarse/ancestor-level fact on the
       // base conservatively applies to every field read off it, same
       // reasoning as `identitiesAt`'s ancestor coverage for state-backed reads.
-      const base = resolveExprIdentities(state, expr.object, ctx);
+      const base = resolveExprIdentities(state, expr.object, sub(ctx, 'base'));
       if (expr.prop === '*') {
         // Same reasoning as the path-succeeds branch above: unknown key on a
         // non-path base — conservatively use everything the base carries
@@ -282,7 +350,7 @@ export function resolveExprIdentities(state, expr, ctx) {
       const flat = new Set();
       const byPath = new Map();
       for (const prop of expr.props) {
-        const r = resolveExprIdentities(state, prop.value, ctx);
+        const r = resolveExprIdentities(state, prop.value, sub(ctx, prop.spread ? 'sp' : `p:${prop.key}`));
         for (const id of r.flat) flat.add(id);
         // Path provenance (Sub-project C, increment 1, Task 2 instrumented
         // site 2 of 4): one production/object in-half per id this property
@@ -358,8 +426,10 @@ export function resolveExprIdentities(state, expr, ctx) {
 
     case 'array': {
       const flat = new Set();
+      let ei = 0;
       for (const el of expr.elements) {
-        const r = resolveExprIdentities(state, el, ctx);
+        ei += 1;
+        const r = resolveExprIdentities(state, el, sub(ctx, `e${ei}`));
         for (const id of r.flat) flat.add(id);
       }
       // Path provenance (§10.1 `array` row): structure-flattening by
@@ -380,8 +450,10 @@ export function resolveExprIdentities(state, expr, ctx) {
 
     case 'tpl': {
       const flat = new Set();
+      let pi = 0;
       for (const part of expr.parts) {
-        const r = resolveExprIdentities(state, part, ctx);
+        pi += 1;
+        const r = resolveExprIdentities(state, part, sub(ctx, `t${pi}`));
         for (const id of r.flat) flat.add(id);
       }
       // Path provenance (§10.1 `tpl` row): transformation-bearing — the
@@ -404,8 +476,8 @@ export function resolveExprIdentities(state, expr, ctx) {
       // structure-flattening by design, not a gap. See
       // DESIGN_INTRAPROCEDURAL.md §4's "structure-preserving vs.
       // structure-flattening" invariant.
-      const left = resolveExprIdentities(state, expr.left, ctx);
-      const right = resolveExprIdentities(state, expr.right, ctx);
+      const left = resolveExprIdentities(state, expr.left, sub(ctx, 'l'));
+      const right = resolveExprIdentities(state, expr.right, sub(ctx, 'r'));
       const flat = new Set([...left.flat, ...right.flat]);
       // Path provenance (§10.1 `binary` row): same as `tpl` — deliberately
       // a separate case (not shared) per ADR §4, but the hop shape agrees.
@@ -428,8 +500,8 @@ export function resolveExprIdentities(state, expr, ctx) {
       // byPath, merged per sub-path across both operands, the same way
       // `union` merges per sub-path across branches. See
       // DESIGN_INTRAPROCEDURAL.md §4.
-      const left = resolveExprIdentities(state, expr.left, ctx);
-      const right = resolveExprIdentities(state, expr.right, ctx);
+      const left = resolveExprIdentities(state, expr.left, sub(ctx, 'l'));
+      const right = resolveExprIdentities(state, expr.right, sub(ctx, 'r'));
       const flat = new Set([...left.flat, ...right.flat]);
       const byPath = new Map();
       for (const r of [left, right]) {
@@ -461,8 +533,10 @@ export function resolveExprIdentities(state, expr, ctx) {
       // collapse into one coarse flat blob. See DESIGN_INTRAPROCEDURAL.md §4.
       const flat = new Set();
       const byPath = new Map();
+      let bi = 0;
       for (const branch of expr.branches) {
-        const r = resolveExprIdentities(state, branch, ctx);
+        bi += 1;
+        const r = resolveExprIdentities(state, branch, sub(ctx, `b${bi}`));
         for (const id of r.flat) flat.add(id);
         for (const [subPath, ids] of r.byPath) {
           const existing = byPath.get(subPath) ?? new Set();
@@ -529,6 +603,7 @@ export function resolveExprIdentities(state, expr, ctx) {
                 fromPath: null, toPath: null, dataElementId: id,
                 syntacticPath: null, widenReason: null, lossReason: null,
                 peerScope: summary.resolvedQid ?? null, peerContext: summary.resolvedContext ?? null,
+                ...(isV2(ctx) ? { callRole: 'return', invocationId: currentInvocation(ctx), relPath: '' } : null),
               });
             }
           }
@@ -577,11 +652,13 @@ export function resolveExprIdentities(state, expr, ctx) {
           for (const id of identitiesAt(state, receiverPath)) flat.add(id);
         }
       } else if (expr.callee?.kind === 'member' && expr.callee.object) {
-        const receiver = resolveExprIdentities(state, expr.callee.object, ctx);
+        const receiver = resolveExprIdentities(state, expr.callee.object, sub(ctx, 'recv', { receiver: true }));
         for (const id of receiver.flat) flat.add(id);
       }
+      let ai = 0;
       for (const arg of expr.args ?? []) {
-        const r = resolveExprIdentities(state, arg, ctx);
+        const r = resolveExprIdentities(state, arg, sub(ctx, `a${ai}`));
+        ai += 1;
         for (const id of r.flat) flat.add(id);
       }
       // Path provenance (§10.1 `call` unresolved row): an unresolved call's
@@ -608,7 +685,7 @@ export function resolveExprIdentities(state, expr, ctx) {
       // A simple pass-through of whatever the assignment's source resolves
       // to (structure-preserving), so its byPath is forwarded directly, not
       // dropped. See DESIGN_INTRAPROCEDURAL.md §4.
-      const r = resolveExprIdentities(state, expr.source, ctx);
+      const r = resolveExprIdentities(state, expr.source, sub(ctx, 'v'));
       // Path provenance (§10.1 `assign-expr` row): pure pass-through — the
       // source's own recursion already emitted its own in-halves; this hop
       // forwards the source's `widened` flag, so it forwards an approximate
@@ -694,7 +771,7 @@ function step(node, stateIn, widenings, ctx) {
         // `ctx?.recordHop` — mirroring Decision 1's own "extra computation
         // is fine to skip, but only when it is genuinely side-effect-free"
         // intent, which this call never actually satisfied.
-        const resolved = resolveExprIdentities(stateIn, node.source, ctx);
+        const resolved = resolveExprIdentities(stateIn, node.source, sub(ctx, 'src'));
         if (ctx?.recordHop) {
           const allIds = new Set([...residualFlat(resolved.flat, resolved.byPath), ...[...resolved.byPath.values()].flatMap((s) => [...s])]);
           for (const id of allIds) {
@@ -707,7 +784,7 @@ function step(node, stateIn, widenings, ctx) {
         }
         return { state: stateIn, returnFact: null };
       }
-      const resolved = resolveExprIdentities(stateIn, node.source, ctx);
+      const resolved = resolveExprIdentities(stateIn, node.source, sub(ctx, 'src'));
       if (pathHasWildcard(node.target)) {
         // A computed-key write (`obj[k] = ...`) must be a WEAK update (add to
         // whatever the container already carries, never clear it first) — a
@@ -739,6 +816,7 @@ function step(node, stateIn, widenings, ctx) {
                 kind: 'write-out', subKind: 'assign-weak',
                 fromPath: null, toPath: containerPath, dataElementId: id,
                 syntacticPath: node.target, widenReason: 'dynamic-property-key', lossReason: null,
+                ...outStamp(ctx, node.source, '', '/src'),
               });
             }
           }
@@ -783,6 +861,7 @@ function step(node, stateIn, widenings, ctx) {
             kind: 'write-out', subKind: 'assign',
             fromPath: null, toPath: node.target, dataElementId: id,
             syntacticPath: null, widenReason: assignWidenReason, lossReason: null,
+            ...outStamp(ctx, node.source, '', '/src'),
           });
         }
       }
@@ -795,6 +874,7 @@ function step(node, stateIn, widenings, ctx) {
               kind: 'write-out', subKind: 'assign',
               fromPath: null, toPath, dataElementId: id,
               syntacticPath: null, widenReason: assignWidenReason, lossReason: null,
+              ...outStamp(ctx, node.source, subPath, '/src'),
             });
           }
         }
@@ -819,8 +899,10 @@ function step(node, stateIn, widenings, ctx) {
       // itself does with the result (still only checks `r.flat` for a
       // widening event) — it only lets a nested `call` sub-expression
       // resolve precisely when `ctx` makes that possible.
+      let argIdx = -1;
       for (const arg of node.args ?? []) {
-        const r = resolveExprIdentities(stateIn, arg, ctx);
+        argIdx += 1;
+        const r = resolveExprIdentities(stateIn, arg, sub(ctx, `a${argIdx}`));
         if (r.flat.size > 0) {
           widenings.push({ atPath: null, dataElementIds: [...r.flat], reason: 'unresolved-call-arg', line: node.line });
         }
@@ -836,6 +918,7 @@ function step(node, stateIn, widenings, ctx) {
               kind: 'write-out', subKind: 'call-arg',
               fromPath: null, toPath: null, dataElementId: id,
               syntacticPath: null, widenReason: null, lossReason: null,
+              ...(isV2(ctx) ? { derivationScope: `/a${argIdx}`, relPath: '' } : null),
             });
           }
         }
@@ -844,7 +927,7 @@ function step(node, stateIn, widenings, ctx) {
     }
 
     case 'return': {
-      const resolved = node.value ? resolveExprIdentities(stateIn, node.value, ctx) : { flat: new Set(), widened: false };
+      const resolved = node.value ? resolveExprIdentities(stateIn, node.value, sub(ctx, 'val')) : { flat: new Set(), widened: false };
       if (resolved.widened && resolved.flat.size > 0) {
         widenings.push({ atPath: null, dataElementIds: [...resolved.flat], reason: 'unresolved-call', line: node.line });
       }
@@ -863,6 +946,7 @@ function step(node, stateIn, widenings, ctx) {
             kind: 'write-out', subKind: 'return',
             fromPath: null, toPath: null, dataElementId: id,
             syntacticPath: null, widenReason: returnWidenReason, lossReason: null,
+            ...(isV2(ctx) ? { derivationScope: '/val', relPath: '' } : null),
           });
         }
       }
@@ -892,6 +976,26 @@ function step(node, stateIn, widenings, ctx) {
 // not a load-bearing part of the termination proof.
 const ITER_BUDGET = 5000;
 
+// Version 2 labels for one hop: the definitions reaching a read, and the
+// definition a local write creates. A write into another function's
+// namespace (a call-arg-bind) is labelled by the resolver instead.
+function versionStamp(reaching, nid, h, entryState) {
+  const out = {};
+  if (typeof h.fromPath === 'string') {
+    let vs = reaching.versionsAt(nid, h.fromPath);
+    // The entry value is an alternative only if the entry state really
+    // carried this id at this path; a merge with an unwritten branch must
+    // not invent an origin for it.
+    if (vs.includes(ENTRY_VERSION) && !entryState.get(h.fromPath)?.has(h.dataElementId)) {
+      const rest = vs.filter((v) => v !== ENTRY_VERSION);
+      if (rest.length > 0) vs = rest;
+    }
+    out.fromVersions = vs;
+  }
+  if (h.kind === 'write-out' && typeof h.toPath === 'string' && h.peerScope == null) out.toVersion = nid;
+  return out;
+}
+
 export function analyzeFunctionFieldIdentity(fn, entryState, ctx) {
   const nodes = fn.cfg.nodes;
   const work = [fn.cfg.entry];
@@ -900,6 +1004,16 @@ export function analyzeFunctionFieldIdentity(fn, entryState, ctx) {
   const widenings = [];
   const returnFactsByNode = new Map();
   let iterations = 0;
+  // Completion record (DAG-07 R07.1): a budget-exhausted run used to fall
+  // out of the loop with a bare `break` and return an empty exit state that
+  // was indistinguishable from "analyzed, nothing flows". `maxIterations`
+  // is overridable through ctx so the limit is testable without building a
+  // 5,000-node CFG; a non-integer or non-positive override is ignored.
+  const maxIterations = Number.isInteger(ctx?.maxIterations) && ctx.maxIterations > 0
+    ? ctx.maxIterations : ITER_BUDGET;
+  let budgetExhausted = false;
+  let cancelled = false;
+  const shouldStop = typeof ctx?.shouldStop === 'function' ? ctx.shouldStop : null;
   // Path provenance (Sub-project C, increment 1, Decision 7.2): stamped
   // once for the whole analysis, since resolveExprIdentities never sees the
   // enclosing function.
@@ -912,9 +1026,17 @@ export function analyzeFunctionFieldIdentity(fn, entryState, ctx) {
   // two hops share a `context` iff the cache would consider them the same
   // context.
   const context = ctx?.recordHop ? hashState(entryState) : null;
+  // Correlation version 2 (DAG-03): one reaching-definitions pass per
+  // analysis run; hops are labelled with the definitions their read paths
+  // see and the definition their write creates.
+  const v2 = ctx?.correlationVersion === CORRELATION_VERSION_2 && typeof ctx.recordHop === 'function';
+  const reaching = v2 ? computeReachingDefinitions(fn) : null;
 
   while (work.length) {
-    if (++iterations > ITER_BUDGET) break;
+    if (++iterations > maxIterations) { budgetExhausted = true; break; }
+    // R07.7: cooperative cancellation, polled every 64 iterations so a
+    // deadline costs next to nothing on the common path.
+    if (shouldStop && (iterations & 63) === 1 && shouldStop()) { cancelled = true; break; }
     const nid = work.shift();
     const node = nodes[nid];
     if (!node) continue;
@@ -927,12 +1049,24 @@ export function analyzeFunctionFieldIdentity(fn, entryState, ctx) {
     // both). With no recorder present, `stepCtx` is the SAME `ctx` reference
     // — no allocation, nothing for a backward-compatibility test to catch
     // (Decision 7.2's "true by construction" point).
-    const stepCtx = ctx?.recordHop
-      ? { ...ctx, recordHop: (h) => ctx.recordHop({
+    const stepRecord = ctx?.recordHop
+      ? (h) => ctx.recordHop({
           scope, nodeId: nid, line: node.line ?? null,
           context, peerScope: null, peerContext: null,
+          ...(v2 ? versionStamp(reaching, nid, h, entryState) : null),
           ...h,
-        }) }
+        })
+      : null;
+    // `rawRecordHop` (version 2 only) is this level's recorder BELOW the
+    // per-expression derivation wrappers, which is what a callee's analysis
+    // must be handed: the callee's hops carry their own derivation ids and
+    // must not inherit the caller's expression-tree stamps.
+    const stepCtx = stepRecord
+      ? {
+          ...ctx,
+          ...(v2 ? { siteInfo: { scope, nodeId: nid, context }, rawRecordHop: stepRecord } : null),
+          recordHop: stepRecord,
+        }
       : ctx;
     const { state: out, returnFact } = step(node, incoming, widenings, stepCtx);
     if (returnFact && returnFact.size > 0) {
@@ -988,5 +1122,16 @@ export function analyzeFunctionFieldIdentity(fn, entryState, ctx) {
     if (ids.size > 0) mutatedParams.set(param, ids);
   }
 
-  return { exitState, returnFacts, mutatedParams, widenings };
+  const completion = (budgetExhausted || cancelled)
+    ? {
+        status: cancelled ? 'cancelled' : 'partial',
+        reasons: [cancelled ? 'cancelled' : 'analysis-iteration-budget'],
+        iterations: maxIterations,
+        maxIterations,
+        unfinishedWork: work.length,
+        exitReached: outStates.has(fn.cfg.exit),
+      }
+    : { status: 'complete', reasons: [], iterations, maxIterations, unfinishedWork: 0, exitReached: outStates.has(fn.cfg.exit) };
+
+  return { exitState, returnFacts, mutatedParams, widenings, completion };
 }

package/src/lineage/export-json.js

@@ -14,6 +14,7 @@
 // (the `agentic-security scan` and `agentic-security ci` commands). This
 // module computes its own content digest instead of reusing either.
 
+import { completionOfGraph } from './completion.js';
 import * as crypto from 'node:crypto';
 import { _redactGraph } from './redact-graph.js';
 
@@ -232,6 +233,10 @@ export function exportGraphJSON(graph, opts = {}) {
     scope: graph?.scope ?? null,
     coverage: graph?.coverage ?? null,
     limitations: graph?.limitations ?? [],
+    // DAG-07 R07.2: the completion envelope, derived from the source graph
+    // so it is the same for any filter/redaction of one scan. Top-level and
+    // additive: the digests above cover `graph`, which is unchanged.
+    completion: completionOfGraph(graph),
     confidential: true,
     graph: body,
   };

package/src/lineage/graph-builder.js

@@ -133,6 +133,8 @@ import { emptyProtection, aggregateVerdicts } from './protection.js';
 import * as ids from './ids.js';
 import { planSeeds, seedEntryStateFactory, exprRoots, walkExpr } from './source-seeding.js';
 import { RECIPIENT_FACT_FIELDS } from './recipient-profile.js';
+import { pathEvidenceEnabled, evaluatePathEvidence, summarizeFlowEvidence } from './path-evidence.js';
+import { sinkFamilyOf } from './control-credit.js';
 
 // =========================================================================
 // §4.2 / §4.3 — registry-backed sink enumeration, multi-candidate resolution
@@ -438,16 +440,46 @@ const nodeLabel = (kind, category, reason) => (category
  */
 export function buildDataFlowGraph(callGraph, opts = {}) {
   const repository = opts.repository ?? 'repo';
-  const { seeds, unseedable } = planSeeds(callGraph, { repository });
+  const { seeds, unseedable, completion: seedingCompletion } = planSeeds(callGraph, {
+    repository,
+    ...(opts.seeding ?? {}),
+    ...(opts.signal ? { signal: opts.signal } : {}),
+    ...(opts.deadline === undefined ? {} : { deadline: opts.deadline }),
+  });
   const hops = [];
-  runFieldIdentityAnalysis(callGraph, {
+  const analysis = runFieldIdentityAnalysis(callGraph, {
     recordHop: (h) => hops.push(h),
     seedEntryState: seedEntryStateFactory(seeds),
     ...(opts.maxContextsPerFn === undefined ? {} : { maxContextsPerFn: opts.maxContextsPerFn }),
+    ...(opts.maxIterations === undefined ? {} : { maxIterations: opts.maxIterations }),
+    // DAG-03: provenance correlation version 2 (off unless requested).
+    ...(opts.correlationVersion === undefined ? {} : { correlationVersion: opts.correlationVersion }),
+    ...(opts.signal ? { signal: opts.signal } : {}),
+    ...(opts.deadline === undefined ? {} : { deadline: opts.deadline }),
     ...(opts.onProgress ? { onProgress: opts.onProgress } : {}),
   });
-  const store = new PathStore();
+  const store = new PathStore({}, { correlationVersion: opts.correlationVersion });
   store.addHops(hops);
+  // DAG-07 R07.2: an analysis unit that hit its budget has no hop
+  // representation (DESIGN_PATH_PROVENANCE.md section 14.8), so it reaches
+  // the store through the out-of-band channel built for exactly this. Units
+  // that emitted nothing stay visible through `analysisCompletion` below.
+  const analysisCompletion = { ...analysis.completion };
+  const _storeLimits = store.limitStatus();
+  if (_storeLimits.hit) {
+    analysisCompletion.storeLimits = _storeLimits;
+    if (analysisCompletion.status === 'complete') analysisCompletion.status = 'partial';
+  }
+  // R07.1: the seeding step's own record. Seeds the planner never reached
+  // mean functions whose sources were never looked for.
+  if (seedingCompletion.status !== 'complete') {
+    analysisCompletion.seeding = seedingCompletion;
+    if (seedingCompletion.status === 'cancelled') analysisCompletion.status = 'cancelled';
+    else if (analysisCompletion.status === 'complete') analysisCompletion.status = 'partial';
+  }
+  for (const u of analysisCompletion.incomplete) {
+    store.markTruncated(u.qid, u.context, u.reasons[0] ?? 'analysis-incomplete');
+  }
 
   const cfgByQid = new Map();
   for (const fn of callGraph.functions.values()) cfgByQid.set(fn.qid, { fn, nodes: fn.cfg?.nodes ?? {} });
@@ -740,7 +772,7 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
         // key by design and therefore never splits a flow.
         const flowKey = [src.id, snk.id, de.id, p.shape, g.grade, sortedT.join(',')].join('|');
         if (!groupsByFlowKey.has(flowKey)) groupsByFlowKey.set(flowKey, []);
-        groupsByFlowKey.get(flowKey).push({ p, g, src, snk, de, edgeIdStr, sortedT, site, unattributed, truncated: r.truncated, truncationReasons: r.truncationReasons });
+        groupsByFlowKey.get(flowKey).push({ p, g, src, snk, de, edgeIdStr, sortedT, site, unattributed, truncated: r.truncated, truncationReasons: r.truncationReasons, result: r });
       }
     }
     site.connected = connected;
@@ -750,6 +782,22 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
     sinkNodeFor(site);
   }
 
+  // DAG-04: opt-in path predicates and control credit (see path-evidence.js).
+  const pathEvidenceOn = pathEvidenceEnabled(opts);
+  const _fnOf = (q) => cfgByQid.get(q)?.fn ?? null;
+  const pathEvidenceFor = (group) => {
+    const paths = group.map((x) => x.p);
+    const family = sinkFamilyOf(group[0].site.entry);
+    const evidences = paths.map((p) => evaluatePathEvidence({ path: p, nodeOf: (id) => store.getNode(id), fnOf: _fnOf, sinkFamily: family }));
+    const results = [...new Set(group.map((x) => x.result))];
+    const merged = {
+      status: results.every((x) => x.status === 'complete') ? 'complete' : 'partial',
+      truncated: results.some((x) => x.truncated), droppedPathCount: results.reduce((n, x) => n + (x.droppedPathCount ?? 0), 0),
+      analysisTruncated: results.some((x) => x.analysisTruncated), resumed: results.some((x) => x.resumed),
+    };
+    return summarizeFlowEvidence({ result: merged, paths, evidences });
+  };
+
   for (const [, group] of [...groupsByFlowKey.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
     const { p, g, src, snk, de, edgeIdStr, sortedT, site } = group[0];
     const fId = ids.flowId(src.id, snk.id, [de.id], [p.shape, g.grade, sortedT.join(',')]);
@@ -927,7 +975,16 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
       limitations,
       evidenceGrade: g.grade,
       handling: handlingResult,
+      // DAG-04 (default OFF; fields exist only when enabled, so default graphs and digests do not move):
+      // per-path branch conditions, feasibility under the bounded model, and control credit for the sink
+      // family. Alternatives stay distinct; infeasible-under-model paths are listed, not dropped.
+      ...(pathEvidenceOn ? { pathEvidence: pathEvidenceFor(group) } : {}),
     });
+    if (pathEvidenceOn) {
+      const fe = edgesById.get(edgeIdStr);
+      const refs = [...new Set(flowsById.get(fId).pathEvidence.alternatives.flatMap((a) => a.predicateRefs.map((x) => x.ref)))].sort();
+      if (fe && refs.length) fe.predicateRefs = [...new Set([...(fe.predicateRefs ?? []), ...refs])].sort();
+    }
   }
 
   // Milestone 2, Sub-project D, increment 2 (FR-307): appliesToAllPaths.
@@ -1105,15 +1162,35 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
     },
     degradedTerminals: degraded.length,
     paths: { enumerated: stats.pathsEnumerated, projected: stats.pathsProjected, truncatedQueries: stats.truncatedQueries },
-    provenance: { hops: hops.length, pnodes: store.stats().nodes, pedges: store.stats().edges },
+    provenance: {
+      hops: hops.length, pnodes: store.stats().nodes, pedges: store.stats().edges,
+      ...(store.correlationVersion() === 2 ? { correlationVersion: 2 } : null),
+    },
+    ...(analysisCompletion.status === 'complete' ? {} : { analysisCompletion }),
   };
   graph.limitations = [
     'Protection verdicts are not assessed in Milestone 1: every edge carries not_assessed/none on all three dimensions.',
     'Policy verdicts are not evaluated in Milestone 1.',
     'External destinations are not resolved (FR-202 is Milestone 2); protocol.destinationResolution is "unknown" on every edge.',
   ];
-  graph.scanHealth = { status: 'complete', reason: 'lineage-graph-builder' };
+  graph.scanHealth = analysisCompletion.status === 'complete'
+    ? { status: 'complete', reason: 'lineage-graph-builder', analysisCompletion }
+    : {
+        status: analysisCompletion.status === 'cancelled' ? 'cancelled' : 'partial',
+        reason: analysisCompletion.status === 'cancelled' ? 'analysis-cancelled' : 'analysis-incomplete',
+        analysisCompletion,
+      };
+  if (analysisCompletion.status !== 'complete') {
+    const parts = [];
+    if (analysisCompletion.incomplete.length) parts.push(`field analysis stopped early in ${analysisCompletion.incomplete.length} of ${analysisCompletion.functionsAnalyzed} function(s) (iteration budget)`);
+    if (analysisCompletion.status === 'cancelled') parts.push(`analysis was cancelled; ${analysisCompletion.functionsNotAnalyzed} function(s) were never analyzed`);
+    if (analysisCompletion.storeLimits) parts.push('provenance construction limits were reached, so some flows were not materialized');
+    if (analysisCompletion.seeding) parts.push(`source seeding stopped early (${analysisCompletion.seeding.reasons.join(', ')}); ${analysisCompletion.seeding.functionsNotScanned} function(s) were not searched for sources`);
+    if (analysisCompletion.incremental) parts.push('a cached summary stood in for a tainted entry context');
+    if (analysisCompletion.degraded.length) parts.push(`${analysisCompletion.degraded.length} call context(s) fell back to a coarser summary (context cap or unconverged recursion)`);
+    graph.limitations.push(`${parts.join('; ')}; absence of a flow from those functions is not evidence that none exists.`);
+  }
   graph.taxonomy = { version: '1.0.0', source: 'built-in + CONFIDENTIAL extension' };
 
-  return { graph, store, hops, seeds, unseedable, sites, nonStatementSites, degraded, stats, decisionsByNodeId };
+  return { graph, store, hops, analysisCompletion, seeds, unseedable, sites, nonStatementSites, degraded, stats, decisionsByNodeId };
 }

package/src/lineage/haskell-view.js

@@ -317,3 +317,62 @@ export function adaptCallGraphForLineage(callGraph) {
   const resolveKnownCallee = callGraph.resolveKnownCallee ? (...a) => swap(callGraph.resolveKnownCallee(...a)) : undefined;
   return { ...callGraph, functions, ...(resolve ? { resolve } : {}), ...(resolveKnownCallee ? { resolveKnownCallee } : {}), lineageView: { haskell: true, functions: clones.size } };
 }
+
+// ── DAG-08: boundary view (record and monadic bindings, unresolved higher-order constructs) ──────────────────────────────
+// A boundary contract that names a Haskell consumer (a function and one of its parameters) is bound by
+// lineage/boundary-contract.js against the same parser-resolved functions this view clones. These helpers add what a consumer
+// binding needs from this layer and must not hide:
+//   * the ORIGINAL source location of the bound function next to the lineage-view clone's location (both kept, neither invented);
+//   * every higher-order construct (`mapM_ f xs`, `forM_ xs k`, `traverse_`, `>>=` with a function value) whose function
+//     argument the Haskell resolver could not resolve to a project function. Taint through such a construct is not followed, so it
+//     is listed instead of being treated as resolved.
+const HIGHER_ORDER_VIA = /^(?:mapM_?|forM_?|traverse_?|for_|foldM_?|foldr|foldl'?|fmap|<\$>|>>=|=<<|bracket_?|handle|catch|forever|when|unless|zipWithM_?)$/;
+
+/**
+ * @param {object} callGraph the Haskell call graph (original or lineage-adapted)
+ * @returns {{functions: object[], unresolvedHigherOrder: object[], notInlined: object[]}}
+ */
+export function describeHaskellBoundaries(callGraph) {
+  const out = { functions: [], unresolvedHigherOrder: [], notInlined: [] };
+  if (!callGraph || typeof callGraph.functions?.values !== 'function') return out;
+  for (const fn of callGraph.functions.values()) {
+    if (!isHsFile(fn.file) || !fn.cfg) continue;
+    out.functions.push({
+      qid: fn.qid, name: fn.name, file: fn.file, line: fn.line,
+      view: fn.hs && fn.hs.lineageView ? { adapted: true, inlinedCalls: fn.hs.lineageInlinedCalls || 0 } : { adapted: false },
+      recordParams: ((fn.hs && fn.hs.recordParams) || []).map((r) => ({ name: r.name, type: r.type, fields: [...(r.fields || [])] })),
+    });
+    for (const s of (fn.hs && fn.hs.lineageNotInlined) || []) out.notInlined.push({ function: fn.qid, file: fn.file, line: fn.line, callee: s.callee, reason: s.reason });
+    for (const n of Object.values(fn.cfg.nodes)) {
+      const call = n.kind === 'call' ? n : (n.kind === 'assign' && n.source && n.source.kind === 'call' ? n.source : null);
+      if (!call || !call.hs) continue;
+      const via = call.hs.via;
+      if (!via || !HIGHER_ORDER_VIA.test(via)) continue;
+      if (call.hs.status === 'resolved' && call.hs.target) continue;
+      out.unresolvedHigherOrder.push({
+        function: fn.qid, file: fn.file, line: n.line ?? call.line ?? fn.line, via, status: call.hs.status || 'unknown',
+        callee: typeof call.callee === 'string' ? call.callee : null,
+        reason: call.hs.status === 'param' ? 'the function argument is a parameter of the enclosing function' : 'the function argument was not resolved to a project function',
+      });
+    }
+  }
+  const key = (a) => `${a.file}:${String(a.line).padStart(8, '0')}:${a.via}`;
+  out.unresolvedHigherOrder.sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+  return out;
+}
+
+/**
+ * The original and lineage-view locations of a bound Haskell consumer. `adapted` is the result of adaptCallGraphForLineage.
+ * Both refer to the same source file and line: the view clones the function but never moves or renames it.
+ */
+export function haskellConsumerLocations(adapted, binding) {
+  if (!binding || !adapted || typeof adapted.functions?.get !== 'function') return null;
+  const clone = adapted.functions.get(binding.qid);
+  if (!clone) return null;
+  const orig = binding.originalLocation || { file: binding.file, line: binding.line };
+  return {
+    original: { file: orig.file, line: orig.line },
+    view: { file: clone.file, line: clone.line, view: 'haskell-lineage', adapted: !!(clone.hs && clone.hs.lineageView), inlinedCalls: (clone.hs && clone.hs.lineageInlinedCalls) || 0 },
+    notInlined: (clone.hs && clone.hs.lineageNotInlined) || [],
+  };
+}

package/src/lineage/index.js

@@ -277,6 +277,9 @@ export function buildLineageGraph(callGraph, opts = {}) {
       observationWindowStart: opts.observationWindowStart,
       observationWindowEnd: opts.observationWindowEnd,
       onProgress: opts.onProgress,
+      // DAG-07 R07.7: cooperative stop, forwarded only when supplied.
+      ...(opts.signal ? { signal: opts.signal } : {}),
+      ...(opts.deadline === undefined ? {} : { deadline: opts.deadline }),
     });
     const nixFiles = opts.fileContents && Object.keys(opts.fileContents).some((f) => /\.nix$/i.test(f));
     if (nixFiles) contributeNixConfigLineage(built.graph, opts.fileContents, { repository: opts.repository });