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

package/src/lineage/source-seeding.js

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

package/src/lineage/summaries.js

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

package/src/lineage/value-versions.js

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

package/src/lineage/witness-selection.js

@@ -0,0 +1,95 @@
+// witness-selection.js: which paths to DISPLAY, and what may be claimed from
+// them (DAG-07 R07.8).
+//
+// Two jobs that must never be confused:
+//   1. rankWitnesses: choose a small, diverse sample of the enumerated paths
+//      to show. Diversity is over source, sink, data class, trust boundary,
+//      control state and ambiguity. This is presentation only.
+//   2. assessAllPathsProtected: decide whether "every path is protected" may
+//      be said. It looks at EVERY enumerated path, displayed or not, and it
+//      refuses outright when the enumeration itself was truncated, so a
+//      sample that happens to contain only protected paths can never produce
+//      the claim. A hidden unprotected path refutes the claim.
+//
+// Pure: no store access, no engine imports.
+
+export const DIVERSITY_DIMENSIONS = Object.freeze(['source', 'sink', 'dataClass', 'trustBoundary', 'controlState', 'ambiguity']);
+
+/**
+ * Attribute values for one path. `attrsOf(path)` may supply `dataClass` and
+ * `controlState` ('protected' | 'unprotected' | 'unknown'); source, sink,
+ * boundary and ambiguity come from the path itself.
+ */
+export function witnessAttributes(path, attrsOf) {
+  const extra = typeof attrsOf === 'function' ? (attrsOf(path) ?? {}) : {};
+  return {
+    source: path.sourceNodeId ?? null,
+    sink: path.sinkNodeId ?? null,
+    dataClass: extra.dataClass ?? path.dataElementId ?? 'unknown',
+    trustBoundary: (path.crossScopeCount ?? 0) > 0 ? 'crosses' : 'local',
+    controlState: extra.controlState ?? 'unknown',
+    ambiguity: (path.ambiguousHopCount ?? 0) > 0 ? 'ambiguous' : 'correlated',
+  };
+}
+
+/**
+ * Greedy diversity ranking. Each step picks the path adding the most
+ * not-yet-shown values across the six dimensions; ties go to the path id so
+ * the order is deterministic. Never drops or alters a path: `ranked` is a
+ * permutation of the input and `displayed` is its prefix.
+ */
+export function rankWitnesses(paths, { limit = 10, attrsOf } = {}) {
+  const list = Array.isArray(paths) ? paths : [];
+  const cap = Number.isInteger(limit) && limit >= 0 ? limit : 10;
+  const seen = Object.fromEntries(DIVERSITY_DIMENSIONS.map((d) => [d, new Set()]));
+  const pool = list.map((p) => ({ p, a: witnessAttributes(p, attrsOf) }));
+  const ranked = [];
+  while (pool.length) {
+    let best = -1;
+    let bestGain = -1;
+    for (let i = 0; i < pool.length; i++) {
+      let gain = 0;
+      for (const d of DIVERSITY_DIMENSIONS) if (!seen[d].has(pool[i].a[d])) gain += 1;
+      if (gain > bestGain || (gain === bestGain && String(pool[i].p.id) < String(pool[best].p.id))) { best = i; bestGain = gain; }
+    }
+    const [chosen] = pool.splice(best, 1);
+    for (const d of DIVERSITY_DIMENSIONS) seen[d].add(chosen.a[d]);
+    ranked.push(chosen.p);
+  }
+  const displayed = ranked.slice(0, cap);
+  const coverage = Object.fromEntries(DIVERSITY_DIMENSIONS.map((d) => [d, new Set(displayed.map((p) => witnessAttributes(p, attrsOf)[d])).size]));
+  return { ranked, displayed, hiddenCount: ranked.length - displayed.length, coverage };
+}
+
+/**
+ * May "all paths are protected" be asserted?
+ *
+ * `enumerated` is every path the query produced (before any display cap);
+ * `result` is the reconstructPaths result they came from. The claim is
+ * allowed only when the query was exhaustive (status complete, nothing
+ * dropped or truncated, at least one path) and every path is protected.
+ * `holds` is false when ANY enumerated path, hidden or not, is unprotected
+ * (a refutation needs no exhaustiveness), and null when it is merely not
+ * established.
+ */
+export function assessAllPathsProtected({ result, enumerated, attrsOf }) {
+  const paths = Array.isArray(enumerated) ? enumerated : [];
+  const stateOf = (p) => (typeof attrsOf === 'function' ? (attrsOf(p)?.controlState ?? 'unknown') : 'unknown');
+  const unprotected = paths.filter((p) => stateOf(p) === 'unprotected');
+  const unknown = paths.filter((p) => stateOf(p) !== 'protected' && stateOf(p) !== 'unprotected');
+  const reasons = [];
+  if (!result || result.status !== 'complete') reasons.push('query-not-complete');
+  if (result && (result.truncated || result.droppedPathCount > 0 || result.analysisTruncated)) reasons.push('truncated-sample');
+  if (result && result.resumed) reasons.push('resumed-page');
+  if (paths.length === 0) reasons.push('no-paths');
+  if (unknown.length) reasons.push('control-state-unknown');
+  if (unprotected.length) {
+    return {
+      claim: 'all-paths-protected', allowed: false, holds: false,
+      reasons: ['refuted-by-unprotected-path'],
+      refutingPathId: unprotected[0].id ?? null, unprotectedCount: unprotected.length,
+    };
+  }
+  const allowed = reasons.length === 0;
+  return { claim: 'all-paths-protected', allowed, holds: allowed ? true : null, reasons, unprotectedCount: 0 };
+}

package/src/pipeline/scan-health.js

@@ -84,6 +84,19 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
   if (lineageStatus?.failure) {
     conditions.push(`lineage graph build threw and was skipped: ${lineageStatus.failure}`);
   }
+  if (Array.isArray(lineageStatus?.incomplete) && lineageStatus.incomplete.length) {
+    conditions.push(`lineage field analysis stopped early in ${lineageStatus.incomplete.length} function(s) (iteration budget); a missing flow from those functions is not evidence of safety`);
+  }
+  if (lineageStatus?.completion && lineageStatus.completion.status !== 'complete') {
+    // DAG-07 R07.2: construction limits, cancellation, seeding limits and a
+    // zero-flow result from incomplete analysis all land here, in terms of
+    // the shared envelope, so none of them can be silent.
+    const c = lineageStatus.completion;
+    conditions.push(`lineage analysis is ${c.status} (${(c.reasons || []).join(', ') || 'no reason recorded'}); absence of a flow is not evidence that none exists`);
+  }
+  if (Array.isArray(lineageStatus?.degraded) && lineageStatus.degraded.length) {
+    conditions.push(`lineage analysis used a coarser summary for ${lineageStatus.degraded.length} call context(s) (context cap or unconverged recursion)`);
+  }
   // FR-203: a detector that threw on at least one file (captured via
   // FR-201's runDetector isolation) is a real analysis gap distinct from
   // an ANNOTATOR error above — annotators run post-detection over the
@@ -136,6 +149,8 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
           reason: deepStatus.reason ?? null,
           failure: deepStatus.failure ?? null,
           ...(Array.isArray(deepStatus.incomplete) && deepStatus.incomplete.length ? { incomplete: deepStatus.incomplete } : {}),
+          // DAG-05 R05.7: present only when the cross-scan cache was requested; says what was reused, what was recomputed, and why a run was cold.
+          ...(deepStatus.incremental ? { incremental: deepStatus.incremental } : {}),
         }
       : null,
     lineageAnalysis: lineageStatus
@@ -144,6 +159,9 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
           enabled: !!lineageStatus.enabled,
           reason: lineageStatus.reason ?? null,
           failure: lineageStatus.failure ?? null,
+          ...(lineageStatus.completion ? { completion: lineageStatus.completion } : {}),
+          ...(Array.isArray(lineageStatus.incomplete) && lineageStatus.incomplete.length ? { incomplete: lineageStatus.incomplete } : {}),
+          ...(Array.isArray(lineageStatus.degraded) && lineageStatus.degraded.length ? { degraded: lineageStatus.degraded } : {}),
         }
       : null,
     annotatorErrorCount: safeAnnotatorErrors.length,

package/src/posture/CLAUDE.md

@@ -1019,6 +1019,23 @@ Measures a deterministic baseline and model arms, and routes tasks from the meas
 * **The router is the policy layer, `routing/decide.js` is the calibrated one.** `policy-router.js` selects from measured scoreboard entries (quality, median cost, median latency, run count) under four policies; `decide.js` keeps quality LOWER bounds on held-out outcomes per stratum. They do not call each other. The router refuses to guess: too few runs, unknown cost under a cost policy, an egress denial or a dataset mismatch excludes a model with the reason, and `threat-model` is blocked because it has no evaluation task.
 * **Digest-checked state.** Runs and the scoreboard live under `.agentic-security/eval-lab/` (registered in `artifact-registry.js`); a record that no longer matches its digest is reported and never used for routing.
 
+## Replayable path witnesses and scoped runtime support: `witness-bundle.js`, `witness-runtime.js` (DAG-10)
+
+A sibling of `evidence-bundle.js` for one source-to-sink PATH rather than one finding. Same Ed25519 key, same self-issued trust basis (`buildLocalIssuance`, newly exported, is the only edit to `evidence-bundle.js`). Pure of the scan path: nothing here is wired into `engine.js`; the one production caller is `verify-attestation` in `bin/agentic-security.js`. Suite: `test/witness-bundle.test.js` (in `test:posture`).
+
+- **Artifacts, not trust.** `exportProvenanceArtifact({hops, incomplete})` is the provenance store export: the normalized 14-field hop stream plus the truncation marks that never travel as hops (`analysisCompletion.incomplete`). `buildWitnessBundle` records graph digest (`computeGraphDigest`), provenance digest, source blob sha256s, the analysis configuration digest, transfer-model fingerprints, ordered edges (full derivation fields plus call/return binding), sink/source/field/context references and completion records. `replayWitness(bundle, {graph, provenance, sources, config})` is offline and bounded (`WITNESS_BOUNDS`): it rebuilds a `PathStore` from the hop stream and requires every recorded edge to be the edge the store derives, the edges to chain, each call/return binding to match both the store and a carrying hop, the terminal reason and truncation state to re-derive, and every digest to match.
+- **A valid signature proves integrity only.** The bundle carries `proves`/`doesNotProve` inside the signed bytes and the verifier rejects a bundle that drops or edits them. Transfer-model fingerprints are computed by RUNNING the half-edge classifiers on fixed probe hops (a minified bundle and the source tree agree); replay under a different fingerprint fails rather than pretending the old model still holds. Replay does not validate the model.
+- **Four statuses, never merged** (`witness-runtime.js`): `modeledPath`, `feasibility` (the nullable DAG-04 `controlEvidence` slot; `not_assessed` until it exists), `runtimeSupport`, `exploitProof`. `evidence` holds exactly these four keys, each `{status}`; any other key (a score, a confidence) fails replay.
+- **Runtime support rules.** `path_supported` needs ONE causal group covering every path edge with compatible environment, deployment, time window, identity scope, order and unambiguous mappings; edges seen in unrelated traces are `edge_partial`. Low-confidence mappings stay `candidate_only`; `no_observation_in_window` and `not_consulted` are different and neither is evidence of safety; a denied observation is `blocked_attempt` and proves only that attempt. The closed-world `RuntimeObservation` contract has no trace or session field, so causal groups are caller-supplied: from the observation store alone the strongest answer is `edge_partial`.
+- **Proof binding.** An external proof reference must name this bundle's sink node, data element, graph digest and configuration digest; a stale or mismatched one is listed under `exploit.rejected` with reasons and is never re-attached.
+- **Partial stays partial.** Completion fields are required (a missing one is invalid, never "complete"), the bundle is JSON-normalized at build so serialization cannot change it, and replay re-derives the path terminal, the truncation marks and `overall`.
+- **Redaction.** Identities become `idt_` tokens (`lineage/identity-token.js`), trace/session ids become `sref_` references, free text goes through `mcp/redact.js`, unknown input fields are dropped and only counted.
+- **Limits.** Building needs the hop stream, which a scan does not persist; `witness build` (`dag-commands.js`) therefore re-runs the field analysis rather than reading a stored stream. Source files are bound only when the caller supplies their text (the rest are listed `unboundSourceFiles` and replay warns). The graph-edge to provenance-edge relation is the flow binding (`graphBinding.flowId`), checked for existence, not re-derived. Cross-service replay depends on DAG-08.
+
+## Opt-in DAG commands: `dag-commands.js` (DAG-01, 02, 06, 08, 09, 10)
+
+CLI entry points for capabilities that were library-only: `dataflow view` (typed graph view plus SCC condensation), `dataflow contracts` (boundary contracts via `runBoundaryTaint`), `dataflow sink-query` (demand reverse taint), the completion contract of `dataflow plan-cuts` (`planContract`; the command body is still in `bin/agentic-security.js`), and `witness build|verify`. Dispatched lazily from `bin/agentic-security.js`, so a default scan never imports it and its output is unchanged. Every report carries a `completion` record in the shared vocabulary and `negativeClaimAllowed` is false unless the engine's own envelope earned it. Exit codes: 0 report produced, 1 nothing usable or verification failed, 2 usage. Suite: `test/cli/dag-commands.test.js` (in `test:lineage`). User docs: `docs/security-graph/graph-precision.md` (Commands section).
+
 ## Gotchas
 
 - The seed `calibration-seed.json` is small (n < 30 for several families). Don't treat it as a held-out set — that's `holdout-eval.js`'s job, against an externally-supplied JSONL.

package/src/posture/business-logic.js

@@ -154,19 +154,28 @@ function collectStateSets(fileContents) {
 }
 
 function extractStateMachine(fileContents) {
-  // Then look for direct writes like `.status = "<not in set>"` and flag.
+  // Then look for direct writes like `.status = "<not in set>"` and flag. A write is
+  // compared only against the status sets declared in the SAME file: a set in one
+  // module says nothing about what another module's `.status` may hold, and matching
+  // every `.status =` in the repository against the first set found anywhere flags
+  // unrelated objects. Test files are skipped (they assign arbitrary states on purpose).
   const stateSets = collectStateSets(fileContents);
   if (!stateSets.length) return [];
+  const byFile = new Map();
+  for (const s of stateSets) {
+    if (!byFile.has(s.file)) byFile.set(s.file, []);
+    byFile.get(s.file).push(s);
+  }
   const findings = [];
-  for (const [fp, c] of Object.entries(fileContents || {})) {
-    if (typeof c !== 'string' || !JS_TS_RE.test(fp)) continue;
+  for (const [fp, sets] of byFile) {
+    const c = fileContents[fp];
+    if (typeof c !== 'string' || /(^|\/)(test|tests|__tests__|fixtures?)\//i.test(fp) || /\.(test|spec)\.[cm]?[jt]sx?$/i.test(fp)) continue;
     const writeRe = /\.\s*(?:status|state|phase)\s*=\s*['"]([^'"]+)['"]/g;
     let m;
     while ((m = writeRe.exec(c))) {
       const value = m[1];
-      const validSet = stateSets.find(s => s.values.size > 0);
-      if (!validSet) continue;
-      if (validSet.values.has(value)) continue;
+      if (sets.some(s => s.values.has(value))) continue;
+      const validSet = sets[0];
       const line = _lineOf(c, m.index);
       findings.push({
         id: `state-machine:${fp}:${line}:${value}`,
@@ -179,7 +188,7 @@ function extractStateMachine(fileContents) {
         parser: 'STATE-MACHINE',
         confidence: 0.5,
         snippet: m[0].slice(0, 200),
-        remediation: `The statuses recognized by your system appear to be {${[...validSet.values].join(', ')}}. This write sets a different value ('${value}'). If the new value is legitimate, add it to the set; otherwise treat the write as a state-machine bypass and reject it.`,
+        remediation: `The statuses recognized by this file appear to be {${[...validSet.values].join(', ')}}. This write sets a different value ('${value}'). If the new value is legitimate, add it to the set; otherwise treat the write as a state-machine bypass and reject it.`,
       });
     }
   }