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

package/src/lineage/path-query.js

@@ -23,6 +23,11 @@
 
 import { pathId } from './ids.js';
 
+// Bound on the call-context stack a version 2 walk tracks. Kept here, not
+// imported from correlation.js, because this module's only import is ids.js
+// (§15.1); correlation.test.js pins the two values equal.
+export const DEFAULT_MAX_CALL_DEPTH = 8;
+
 /**
  * All `opts`-overridable. Two-plus orders of magnitude above what every
  * fixture measured in the design task's PoC needs (§15.11's largest row
@@ -35,10 +40,38 @@ export const DEFAULTS = {
   maxPaths: 32,
   maxPathsPerTerminal: 8,
   maxCandidatePaths: 256,
+  // R07.5: total hops copied into candidate paths. Each candidate costs its
+  // length, so this bounds output memory independently of the candidate count.
+  maxMaterializedHops: 1000000,
   maxExpansions: 10000,
   maxDepth: 64,
 };
 
+// DAG-07 R07.4: documented upper bounds. A budget must be a finite,
+// nonnegative integer no larger than its bound; anything else (NaN,
+// Infinity, negative, fractional, a string) makes the query `invalid`
+// rather than silently running unbounded or being coerced.
+export const BUDGET_UPPER_BOUNDS = {
+  maxPaths: 1e7,
+  maxPathsPerTerminal: 1e7,
+  maxCandidatePaths: 1e9,
+  maxMaterializedHops: 1e9,
+  maxExpansions: 1e9,
+  maxDepth: 1e6,
+};
+
+export function validateBudget(opts) {
+  const errors = [];
+  for (const [k, v] of Object.entries(opts ?? {})) {
+    if (!(k in BUDGET_UPPER_BOUNDS)) continue;
+    if (v === undefined) continue;
+    if (!Number.isInteger(v) || v < 0 || v > BUDGET_UPPER_BOUNDS[k]) {
+      errors.push(`${k} must be an integer in [0, ${BUDGET_UPPER_BOUNDS[k]}], got ${typeof v === 'number' ? String(v) : typeof v}`);
+    }
+  }
+  return errors;
+}
+
 // §15.4's terminal-reason vocabulary. Only 'origin' means "this really is
 // where the recorded flow starts" (`complete: true`). 'expansion-budget'
 // and 'candidate-cap' are deliberately NOT terminal reasons — see the loop
@@ -48,6 +81,9 @@ const TERMINAL_ORIGIN = 'origin';
 const TERMINAL_INCOMPLETE = 'incomplete-record';
 const TERMINAL_CYCLE = 'cycle';
 const TERMINAL_DEPTH = 'depth-limit';
+// Version 2 only: every incoming edge of the node would have returned to a
+// call site other than the one this walk entered through.
+const TERMINAL_UNBALANCED = 'unbalanced-call';
 
 /**
  * §15.9's stand-in for Sub-project D's source/sink registry, which does not
@@ -89,6 +125,13 @@ function hopOf(edge) {
     annotations: edge.annotations,
     originated: edge.originated,
     truncated: edge.truncated,
+    // Version 2 edges only; a version 1 hop has exactly the fields it had.
+    ...(edge.correlationVersion ? {
+      correlationVersion: edge.correlationVersion,
+      correlation: edge.correlation,
+      callBoundary: edge.callBoundary,
+      invocationId: edge.invocationId,
+    } : null),
   };
 }
 
@@ -98,7 +141,7 @@ function hopOf(edge) {
  * a flow source -> sink, so the arrays are reversed here, once, at the
  * point a candidate is emitted.
  */
-function materialize(store, nodesRev, edgesRev, terminalReason) {
+function materialize(store, nodesRev, edgesRev, terminalReason, callContext = null) {
   const nodeIds = [...nodesRev].reverse();
   const edges = [...edgesRev].reverse();
   const hops = edges.map((e) => hopOf(e));
@@ -138,6 +181,9 @@ function materialize(store, nodesRev, edgesRev, terminalReason) {
     lossHopCount,
     ambiguousHopCount,
     analysisTruncated,
+    // Correlation version 2 only (absent, not null, in version 1): whether the
+    // walk had to abstract the call context to stay within its bound.
+    ...(callContext ? { callContext } : null),
     // §15.7's diversity signature. `transformation` and `protection` are
     // DELIBERATELY absent — Sub-project D / Milestone 2 own them; using
     // today's widen/loss reasons as a stand-in for either would be
@@ -187,6 +233,7 @@ export function comparePaths(a, b) {
  * (§18.4's single most load-bearing constraint).
  */
 export function reconstructPaths(store, startNodeId, opts = {}) {
+  const budgetErrors = validateBudget(opts);
   const budget = { ...DEFAULTS, ...opts };
   const startNode = store.getNode(startNodeId);
   const truncationReasons = new Set();
@@ -206,36 +253,125 @@ export function reconstructPaths(store, startNodeId, opts = {}) {
     cyclesClipped: 0,
     terminals: [],
     analysisTruncated: false,
+    status: 'complete',
+    negativeClaimAllowed: false,
     budget: { ...budget, expansionsUsed: 0 },
   };
+  if (budgetErrors.length) {
+    // Invalid input is neither "no path" nor a partial answer.
+    result.status = 'invalid';
+    result.budgetErrors = budgetErrors;
+    result.budget = { ...DEFAULTS, expansionsUsed: 0 };
+    return result;
+  }
   // An id that names no node is NOT "no path exists" — it is "you asked
   // about something that is not in this store". §15.4 keeps the two apart,
   // because collapsing them is §18.4's failure mode wearing a different hat.
-  if (!startNode) return result;
+  if (!startNode) {
+    result.status = 'partial';
+    // A store that refused input may simply not contain the node asked for.
+    if (typeof store.limitStatus === 'function' && store.limitStatus().hit) {
+      result.truncated = true;
+      result.truncationReasons = ['store-limit'];
+    }
+    return result;
+  }
 
   const orphaned = new Set(store.diagnostics().orphanedPeerSources.map((o) => o.nodeId));
 
+  // Correlation version 2 (DAG-03, R03.5): a precise witness is a REALIZABLE
+  // path, so a return edge may only be followed back to the call it returned
+  // to. `path.calls` is the stack of invocations the backward walk has
+  // entered (a return edge pushes its invocation, the matching call edge
+  // pops it). Past `maxCallDepth` the stack is abstracted: further entries
+  // are only counted (`overflow`), a call edge met while any are pending is
+  // accepted without a match, and the path says so in `callContext`.
+  const v2 = typeof store.correlationVersion === 'function' && store.correlationVersion() === 2;
+  const maxCallDepth = Number.isInteger(opts.maxCallDepth) && opts.maxCallDepth >= 1 ? opts.maxCallDepth : DEFAULT_MAX_CALL_DEPTH;
+  const balancing = { enabled: v2, maxCallDepth, unbalancedPruned: 0, prunedEdgeIds: [], contextWidenedPaths: 0 };
+  if (v2) {
+    result.correlationVersion = 2;
+    result.budget.maxCallDepth = maxCallDepth;
+  }
+
   const candidates = [];
   let expansions = 0;
-  const stack = [{
-    nodeId: startNodeId,
-    nodesRev: [startNodeId],
-    edgesRev: [],
-    onPath: new Set([startNodeId]),
-  }];
+  let materializedHops = 0;
+  const materializeCounted = (n, e, reason) => { materializedHops += e.length; return materialize(store, n, e, reason, ctxOf()); };
+  // DAG-07 R07.6: ONE shared path (arrays + visited set) that is unwound on
+  // backtrack, instead of copying both for every frame (which made a chain
+  // of depth d cost O(d^2)). A frame is only {nodeId, edge, hops}; visit
+  // order and expansion accounting are identical to the copying version.
+  const path = {
+    nodesRev: [startNodeId], edgesRev: [], onPath: new Set([startNodeId]),
+    calls: [], overflow: 0, effects: [], widened: 0,
+  };
+  const ctxOf = () => (v2 ? { balanced: path.widened === 0, widened: path.widened > 0, maxCallDepth } : null);
+  const stack = [{ nodeId: startNodeId, edge: null, hops: 0 }];
+  // R07.9: a continuation (continuation.js) hands back the frontier a
+  // previous call stopped at. Shape is checked, never trusted blindly; a
+  // malformed one makes the query invalid rather than silently restarting.
+  if (opts.resumeState !== undefined) {
+    const rs = opts.resumeState;
+    const ok = rs && rs.startNodeId === startNodeId && Array.isArray(rs.nodesRev) && Array.isArray(rs.edgesRev)
+      && Array.isArray(rs.stack) && rs.nodesRev.length === rs.edgesRev.length + 1;
+    if (!ok) {
+      result.status = 'invalid';
+      result.budgetErrors = ['resumeState is malformed or belongs to a different start node'];
+      return result;
+    }
+    path.nodesRev = rs.nodesRev.slice();
+    path.edgesRev = rs.edgesRev.slice();
+    path.onPath = new Set(rs.nodesRev);
+    stack.length = 0;
+    for (const f of rs.stack) stack.push({ ...f });
+    result.resumed = true;
+  }
 
   while (stack.length > 0) {
     if (candidates.length >= budget.maxCandidatePaths) { truncationReasons.add('candidate-cap'); break; }
+    if (materializedHops >= budget.maxMaterializedHops) { truncationReasons.add('materialization-budget'); break; }
     if (expansions >= budget.maxExpansions) { truncationReasons.add('expansion-budget'); break; }
     const frame = stack.pop();
-    const hops = frame.edgesRev.length;
+    const hops = frame.hops;
+    // Unwind to this frame's parent, then step onto the frame.
+    const parentLen = hops === 0 ? 0 : hops - 1;
+    while (path.edgesRev.length > parentLen) {
+      path.edgesRev.pop();
+      path.onPath.delete(path.nodesRev.pop());
+      if (v2) {
+        const eff = path.effects.pop();
+        if (eff?.push) path.calls.pop();
+        if (eff?.pop) path.calls.push(eff.pop);
+        if (eff?.overflowInc) path.overflow -= 1;
+        if (eff?.overflowDec) path.overflow += 1;
+        if (eff?.widened) path.widened -= 1;
+      }
+    }
+    if (frame.edge) {
+      if (v2) {
+        const eff = {};
+        const b = frame.edge.callBoundary;
+        if (b === 'return') {
+          if (path.calls.length < maxCallDepth) { path.calls.push(frame.edge.invocationId); eff.push = true; }
+          else { path.overflow += 1; eff.overflowInc = true; eff.widened = true; path.widened += 1; }
+        } else if (b === 'call') {
+          if (path.overflow > 0) { path.overflow -= 1; eff.overflowDec = true; eff.widened = true; path.widened += 1; }
+          else if (path.calls.length > 0) eff.pop = path.calls.pop();
+        }
+        path.effects.push(eff);
+      }
+      path.edgesRev.push(frame.edge);
+      path.nodesRev.push(frame.nodeId);
+      path.onPath.add(frame.nodeId);
+    }
     // `edgesTo` is the traversal primitive; sorted for determinism, since
     // it is backed by a Set and carries no inherent order.
     const incoming = [...store.edgesTo(frame.nodeId)].sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0));
 
     if (incoming.length === 0) {
       if (hops > 0) {
-        candidates.push(materialize(store, frame.nodesRev, frame.edgesRev,
+        candidates.push(materializeCounted(path.nodesRev, path.edgesRev,
           orphaned.has(frame.nodeId) ? TERMINAL_INCOMPLETE : TERMINAL_ORIGIN));
       }
       continue;
@@ -265,33 +401,56 @@ export function reconstructPaths(store, startNodeId, opts = {}) {
     // literal zero-hop budget will not get one.
     if (hops >= budget.maxDepth && hops > 0) {
       truncationReasons.add('depth-limit');
-      candidates.push(materialize(store, frame.nodesRev, frame.edgesRev, TERMINAL_DEPTH));
+      candidates.push(materializeCounted(path.nodesRev, path.edgesRev, TERMINAL_DEPTH));
       continue;
     }
 
     let extended = 0;
     let clipped = 0;
+    let unbalanced = 0;
     for (const e of incoming) {
       expansions += 1;
-      if (frame.onPath.has(e.fromNodeId)) { clipped += 1; continue; }
+      if (v2 && e.callBoundary === 'call' && path.overflow === 0 && path.calls.length > 0
+          && path.calls[path.calls.length - 1] !== e.invocationId) {
+        // The walk entered the callee through another call site, so this
+        // edge belongs to a call/return pair no execution can produce.
+        unbalanced += 1;
+        balancing.unbalancedPruned += 1;
+        if (balancing.prunedEdgeIds.length < 10) balancing.prunedEdgeIds.push(e.id);
+        continue;
+      }
+      if (path.onPath.has(e.fromNodeId)) { clipped += 1; continue; }
       extended += 1;
-      stack.push({
-        nodeId: e.fromNodeId,
-        nodesRev: [...frame.nodesRev, e.fromNodeId],
-        edgesRev: [...frame.edgesRev, e],
-        onPath: new Set([...frame.onPath, e.fromNodeId]),
-      });
+      stack.push({ nodeId: e.fromNodeId, edge: e, hops: hops + 1 });
     }
     result.cyclesClipped += clipped;
+    if (extended === 0 && clipped === 0 && unbalanced > 0 && hops > 0) {
+      // Everything that led here is a mismatched call/return pair. Say so,
+      // as a partial path, instead of letting an empty answer read as
+      // "nothing flows".
+      candidates.push(materialize(store, path.nodesRev, path.edgesRev, TERMINAL_UNBALANCED, ctxOf()));
+      continue;
+    }
     if (extended === 0 && hops > 0) {
       // Every continuation would revisit a node already on this path. The
       // branch ends HERE, and it ends because of a cycle — never silently
       // as if this node were the flow's origin.
-      candidates.push(materialize(store, frame.nodesRev, frame.edgesRev, TERMINAL_CYCLE));
+      candidates.push(materializeCounted(path.nodesRev, path.edgesRev, TERMINAL_CYCLE));
     }
   }
 
   result.budget.expansionsUsed = expansions;
+  // R07.1: work still queued when a budget stopped the walk (0 when exhausted).
+  result.unexploredFrontierCount = stack.length;
+  if (stack.length > 0) {
+    result.resumeState = { startNodeId, nodesRev: path.nodesRev.slice(), edgesRev: path.edgesRev.slice(), stack: stack.map((f) => ({ ...f })) };
+  }
+  result.budget.materializedHops = materializedHops;
+  if (v2) {
+    balancing.contextWidenedPaths = candidates.filter((p) => p.callContext?.widened).length;
+    balancing.prunedEdgeIds.sort();
+    result.balancing = balancing;
+  }
   result.enumeratedPathCount = candidates.length;
   // Task 2 review finding 1: this is scoped to EVERY complete path found
   // during enumeration, not just the ones the caps below end up returning
@@ -384,6 +543,9 @@ export function reconstructPaths(store, startNodeId, opts = {}) {
   }
   result.terminals = terminals;
 
+  // R07.5: a store that refused hops/edges or skipped a group is missing
+  // pairings this query cannot see, so it can never prove "no path".
+  if (typeof store.limitStatus === 'function' && store.limitStatus().hit) truncationReasons.add('store-limit');
   result.truncated = truncationReasons.size > 0 || result.droppedPathCount > 0;
   result.truncationReasons = [...truncationReasons].sort();
 
@@ -395,6 +557,13 @@ export function reconstructPaths(store, startNodeId, opts = {}) {
     // `noPathReason` — never a stylistic choice.
     result.noPathReason = orphaned.has(startNodeId) ? TERMINAL_INCOMPLETE : 'no-incoming-edges';
   }
+  result.status = isIncompleteAnswer(result) ? 'partial' : 'complete';
+  // "No modeled path" is allowed only for an exhausted query; it is a
+  // statement about the modeled graph, never about the software.
+  // A resumed page only describes the work done since the continuation, so it
+  // can never license a negative claim about the whole query.
+  result.negativeClaimAllowed = result.status === 'complete' && result.paths.length === 0 && !result.resumed
+    && result.noPathReason === 'no-incoming-edges';
   return result;
 }
 
@@ -404,7 +573,7 @@ export function reconstructPaths(store, startNodeId, opts = {}) {
  * term).
  */
 export function isIncompleteAnswer(result) {
-  return result.truncated || result.unknownStartNode || result.analysisTruncated
+  return result.status === 'invalid' || result.truncated || result.unknownStartNode || result.analysisTruncated
     || result.noPathReason === TERMINAL_INCOMPLETE
     || result.paths.some((p) => !p.complete);
 }

package/src/lineage/path-store.js

@@ -21,7 +21,11 @@
 // C5's job and C5's alone.
 //
 
+import { createHash } from 'node:crypto';
 import { provenanceNodeId, provenanceEdgeId } from './ids.js';
+import {
+  CORRELATION_VERSION_2, V2_HOP_FIELDS, resolveCorrelationVersion, pairCompatibility, buildCrosswalk,
+} from './correlation.js';
 
 // §3 + §13.0's exact 14-field hop shape, in a FIXED order. Never derive a
 // dedupe/discriminator key via `Object.keys(h)` — that is order-dependent,
@@ -40,8 +44,11 @@ export const HOP_FIELDS = [
 
 const IN_KINDS = new Set(['production', 'selection']);
 
-function hopDedupeKey(h) {
-  return HOP_FIELDS.map((f) => JSON.stringify(h[f] ?? null)).join('|');
+function hopDedupeKey(h, v2 = false) {
+  const base = HOP_FIELDS.map((f) => JSON.stringify(h[f] ?? null)).join('|');
+  // Version 2 hops carry additive evidence fields; two hops that differ only
+  // in that evidence are different hops. Version 1 never reads them.
+  return v2 ? `${base}|${V2_HOP_FIELDS.map((f) => JSON.stringify(h[f] ?? null)).join('|')}` : base;
 }
 
 function joinKeyOf(h) {
@@ -149,8 +156,31 @@ export function classifyOut(h) {
   return { role: 'unclassified', crossScope: false, node: null };
 }
 
+// DAG-07 R07.5: construction bounds. Hitting one never throws and never
+// silently drops: it is recorded in diagnostics().limits and makes every
+// reconstruction over this store report `store-limit` truncation.
+export const STORE_LIMIT_DEFAULTS = {
+  maxHops: 2000000,
+  maxPairingsPerGroup: 10000,
+  maxEdges: 5000000,
+};
+
 export class PathStore {
-  constructor() {
+  /**
+   * `options.correlationVersion` (or AGENTIC_SECURITY_LINEAGE_CORRELATION=2)
+   * selects provenance correlation version 2 (DAG-03): value-versioned path
+   * nodes, evidence-gated pairing of the two hop halves and call-boundary
+   * edges that carry their invocation. The default is version 1, whose nodes,
+   * edges, ids and diagnostics are byte-identical to the pre-DAG-03 store.
+   */
+  constructor(limits = {}, options = {}) {
+    this._v2 = resolveCorrelationVersion(options?.correlationVersion) === CORRELATION_VERSION_2;
+    this._limits = { ...STORE_LIMIT_DEFAULTS };
+    for (const k of Object.keys(STORE_LIMIT_DEFAULTS)) {
+      const v = limits?.[k];
+      if (Number.isInteger(v) && v >= 0) this._limits[k] = v;
+    }
+    this._limitHits = { hopsRefused: 0, groupsSkipped: [], edgesRefused: 0, summarizedGroups: 0 };
     this._groups = new Map();
     this._seen = new Set();
     this._truncations = new Map();
@@ -178,8 +208,12 @@ export class PathStore {
     if (missing.length > 0) {
       this._malformed.push({ hop, missing });
     }
-    const k = hopDedupeKey(hop);
+    const k = hopDedupeKey(hop, this._v2);
     if (this._seen.has(k)) return false;
+    if (this._stats.hopsAccepted >= this._limits.maxHops) {
+      this._limitHits.hopsRefused += 1;
+      return false;
+    }
     this._seen.add(k);
     this._stats.hopsAccepted += 1;
 
@@ -196,14 +230,24 @@ export class PathStore {
     if (IN_KINDS.has(hop.kind)) {
       const c = classifyIn(hop);
       if (c.role === 'source') {
-        g.in.push({ hop, ...c });
+        if (this._v2 && !c.crossScope && c.node.kind === 'path') {
+          // One in-half node per reaching definition: a merge keeps every
+          // alternative, a killed definition is simply absent.
+          const vs = Array.isArray(hop.fromVersions) && hop.fromVersions.length > 0 ? hop.fromVersions : [null];
+          for (const v of vs) g.in.push({ hop, ...c, node: { ...c.node, version: v } });
+        } else {
+          g.in.push({ hop, ...c });
+        }
         if (c.crossScope) this._peerSourced.push({ hop, node: c.node });
       } else {
         g.annotations.push(hop);
       }
     } else if (hop.kind === 'write-out') {
       const c = classifyOut(hop);
-      if (c.role === 'target') g.out.push({ hop, ...c });
+      if (c.role === 'target') {
+        const node = this._v2 && c.node.kind === 'path' ? { ...c.node, version: hop.toVersion ?? null } : c.node;
+        g.out.push({ hop, ...c, node });
+      }
       else this._unclassified.push(hop);
     } else {
       this._unclassified.push(hop);
@@ -233,13 +277,15 @@ export class PathStore {
 
   _build() {
     if (this._built) return this._built;
+    this._limitHits = { hopsRefused: this._limitHits.hopsRefused, groupsSkipped: [], edgesRefused: 0, summarizedGroups: 0 };
     const nodes = new Map();
     const edges = new Map();
     const outIndex = new Map();
     const inIndex = new Map();
 
+    const nid = (desc) => this.nodeIdFor(desc);
     const intern = (desc) => {
-      const id = provenanceNodeId(desc);
+      const id = nid(desc);
       let n = nodes.get(id);
       if (!n) {
         n = {
@@ -251,8 +297,29 @@ export class PathStore {
       return n;
     };
 
+    // Version 2: a definition that never wrote this data element at this path
+    // cannot be where it came from, so a source node (path, version, id) with
+    // no producing out-half is a phantom alternative and is dropped. The entry
+    // version has no producer by nature (a seed, or a caller binding), so it
+    // is kept. Counted in diagnostics, never silent.
+    const produced = new Set();
+    if (this._v2) {
+      for (const g of this._groups.values()) {
+        for (const o of g.out) if (o.node.kind === 'path') produced.add(nid(o.node));
+      }
+    }
+    let versionPruned = 0;
     for (const g of this._groups.values()) {
       let sources = g.in;
+      if (this._v2) {
+        sources = g.in.filter((s) => {
+          const v = s.node.version;
+          if (s.node.kind !== 'path' || v == null || v === 'entry') return true;
+          if (produced.has(nid(s.node))) return true;
+          versionPruned += 1;
+          return false;
+        });
+      }
       let originated = false;
       // Populated only when `originated` below — the union of every
       // annotation's widen/loss reason at this key, so an edge originating
@@ -266,7 +333,7 @@ export class PathStore {
       // exact shape a Sub-project D source registry will produce first).
       let originWidenReasons = [];
       let originLossReasons = [];
-      if (sources.length === 0 && g.annotations.length > 0) {
+      if (g.in.length === 0 && g.annotations.length > 0) {
         // §2.2's annotation rule, in the ONE direction it is still right:
         // with no non-null in-half anywhere at this key, the annotation is
         // itself the origin of the value ("no prior aliasing source").
@@ -294,16 +361,65 @@ export class PathStore {
       // in-half and the return's in-half share one join key). Counting
       // only the pairings the store would ACTUALLY form (after the peer x
       // peer exclusion) recovers the distinction at zero cost.
-      const pairable = (s, o) => !(s.crossScope && o.crossScope);
-      const sourcesFor = (o) => new Set(sources.filter((s) => pairable(s, o)).map((s) => provenanceNodeId(s.node)));
-      const targetsFor = (s) => new Set(g.out.filter((o) => pairable(s, o)).map((o) => provenanceNodeId(o.node)));
+      const pairable = (s, o) => {
+        if (s.crossScope && o.crossScope) return false;
+        return !this._v2 || originated || pairCompatibility(s.hop, o.hop).compatible;
+      };
+      const sourcesFor = (o) => new Set(sources.filter((s) => pairable(s, o)).map((s) => nid(s.node)));
+      const targetsFor = (s) => new Set(g.out.filter((o) => pairable(s, o)).map((o) => nid(o.node)));
 
       const annotations = g.annotations.map((a) => ({
         kind: a.kind, subKind: a.subKind,
         widenReason: a.widenReason ?? null, lossReason: a.lossReason ?? null,
         peerScope: a.peerScope ?? null, peerContext: a.peerContext ?? null,
       }));
+      // Version 2: the graph content must not depend on hop delivery order,
+      // and an annotation list is built in delivery order. Sorted by content.
+      if (this._v2) annotations.sort((a, b) => { const x = JSON.stringify(a); const y = JSON.stringify(b); return x < y ? -1 : x > y ? 1 : 0; });
 
+      // R07.5: an explicit cross product above the cap is not materialized;
+      // the group is reported instead of being silently pruned.
+      if (sources.length * g.out.length > this._limits.maxPairingsPerGroup) {
+        this._limitHits.groupsSkipped.push({
+          scope: g.scope, nodeId: g.nodeId, dataElementId: g.dataElementId,
+          pairings: sources.length * g.out.length,
+        });
+        // R07.5: the explicit cross product (S x O edges) is replaced by a
+        // typed ambiguous-summary relation: every source reaches one summary
+        // node and that node reaches every target (S + O edges). Which
+        // source feeds which target is deliberately not claimed, so every
+        // such edge is marked ambiguous; reachability is kept, nothing is
+        // silently dropped, and the group stays reported above.
+        const hub = intern({ kind: 'summary', scope: g.scope, context: g.context, path: null, siteNodeId: g.nodeId, dataElementId: g.dataElementId });
+        this._limitHits.summarizedGroups += 1;
+        const addSummaryEdge = (fromN, toN, inHop, outHop, crossScope) => {
+          const widenReasons = [...new Set([inHop.widenReason, outHop.widenReason].filter((r) => r != null))].sort();
+          const lossReasons = [...new Set([inHop.lossReason, outHop.lossReason].filter((r) => r != null))].sort();
+          const desc = {
+            fromNodeId: fromN.id, toNodeId: toN.id, dataElementId: g.dataElementId,
+            scope: g.scope, context: g.context, siteNodeId: g.nodeId,
+            inKind: inHop.kind, inSubKind: inHop.subKind,
+            outKind: outHop.kind, outSubKind: outHop.subKind,
+            widenReasons, lossReasons,
+          };
+          const eid = provenanceEdgeId(desc);
+          if (edges.has(eid)) return;
+          if (edges.size >= this._limits.maxEdges) { this._limitHits.edgesRefused += 1; return; }
+          edges.set(eid, {
+            id: eid, ...desc, line: g.line, crossScope, originated,
+            ambiguousCorrelation: true, ambiguousSummary: true, annotations,
+            truncated: this._truncations.has(scopeKeyOf(g.scope, g.context)),
+          });
+          if (!outIndex.has(fromN.id)) outIndex.set(fromN.id, new Set());
+          if (!inIndex.has(toN.id)) inIndex.set(toN.id, new Set());
+          outIndex.get(fromN.id).add(eid);
+          inIndex.get(toN.id).add(eid);
+        };
+        const summaryHop = { kind: 'summary', subKind: 'ambiguous-summary', widenReason: null, lossReason: null };
+        for (const s of sources) addSummaryEdge(intern(s.node), hub, s.hop, summaryHop, s.crossScope);
+        for (const o of g.out) addSummaryEdge(hub, intern(o.node), summaryHop, o.hop, o.crossScope);
+        continue;
+      }
       for (const s of sources) {
         for (const o of g.out) {
           // §14.3: an edge with BOTH endpoints in the peer's namespace is
@@ -327,13 +443,34 @@ export class PathStore {
             outKind: o.hop.kind, outSubKind: o.hop.subKind,
             widenReasons, lossReasons,
           };
-          const id = provenanceEdgeId(desc);
-          if (!edges.has(id)) {
+          let v2Edge = null;
+          let idParts = [];
+          if (this._v2) {
+            const pc = originated ? { proven: false } : pairCompatibility(s.hop, o.hop);
+            const invocationId = s.hop.invocationId ?? o.hop.invocationId ?? null;
+            const callBoundary = o.hop.callRole === 'bind' ? 'call' : s.hop.callRole === 'return' ? 'return' : null;
+            v2Edge = {
+              correlationVersion: CORRELATION_VERSION_2,
+              correlation: pc.proven ? 'proven' : 'legacy-unknown',
+              invocationId, callBoundary,
+            };
+            idParts = ['cv2', invocationId, callBoundary];
+          }
+          const id = provenanceEdgeId(desc, idParts);
+          if (edges.has(id) && v2Edge && v2Edge.correlation !== 'proven') {
+            // Two pairings that dedupe to one edge: the edge is only as proven
+            // as its weakest pairing, whatever order they arrived in.
+            edges.get(id).correlation = 'legacy-unknown';
+          }
+          if (!edges.has(id) && edges.size >= this._limits.maxEdges) {
+            this._limitHits.edgesRefused += 1;
+          } else if (!edges.has(id)) {
             edges.set(id, {
               id, ...desc, line: g.line,
               crossScope: s.crossScope || o.crossScope,
               originated,
               ambiguousCorrelation: sourcesFor(o).size >= 2 && targetsFor(s).size >= 2,
+              ...v2Edge,
               annotations,
               truncated: this._truncations.has(scopeKeyOf(g.scope, g.context)),
             });
@@ -356,14 +493,14 @@ export class PathStore {
     // fabricated into an origin, never dropped.
     const orphanedPeerSources = [];
     for (const { hop, node } of this._peerSourced) {
-      const id = provenanceNodeId(node);
+      const id = nid(node);
       const inEdges = inIndex.get(id);
       if (!inEdges || inEdges.size === 0) {
         orphanedPeerSources.push({ hop, nodeId: id });
       }
     }
 
-    this._built = { nodes, edges, outIndex, inIndex, orphanedPeerSources };
+    this._built = { nodes, edges, outIndex, inIndex, orphanedPeerSources, versionPruned };
     return this._built;
   }
 
@@ -375,11 +512,46 @@ export class PathStore {
   edges() { return [...this._build().edges.values()]; }
   getNode(id) { return this._build().nodes.get(id) ?? null; }
   getEdge(id) { return this._build().edges.get(id) ?? null; }
-  nodeIdFor(desc) { return provenanceNodeId(desc); }
+  nodeIdFor(desc) {
+    return this._v2 ? provenanceNodeId(desc, ['cv2', desc.version ?? null]) : provenanceNodeId(desc);
+  }
+  /** 1 or 2: the correlation version this store was built with. */
+  correlationVersion() { return this._v2 ? 2 : 1; }
+  /** Version 1 to version 2 id crosswalk (version 2 stores only; `null` for version 1). */
+  crosswalk() { return this._v2 ? buildCrosswalk(this) : null; }
   edgesFrom(nodeId) { return [...(this._build().outIndex.get(nodeId) ?? [])].map((e) => this._build().edges.get(e)); }
   edgesTo(nodeId) { return [...(this._build().inIndex.get(nodeId) ?? [])].map((e) => this._build().edges.get(e)); }
   hasEdge(fromId, toId) { return this.edgesFrom(fromId).some((e) => e.toNodeId === toId); }
-  stats() { return { ...this._stats, groups: this._groups.size, nodes: this._build().nodes.size, edges: this._build().edges.size }; }
+  /**
+   * R07.9: content digest of the built graph (sorted node and edge ids plus
+   * the construction-limit outcome). Two stores with equal digests answer
+   * every query identically; a continuation is bound to it.
+   */
+  digest() {
+    const b = this._build();
+    const h = createHash('sha256');
+    h.update(JSON.stringify([[...b.nodes.keys()].sort(), [...b.edges.keys()].sort(), this.limitStatus().hit]));
+    return h.digest('hex');
+  }
+  /** R07.5: has any construction bound been hit? Forces the build so the join-time counters are current. */
+  limitStatus() {
+    this._build();
+    const h = this._limitHits;
+    return {
+      hit: h.hopsRefused > 0 || h.groupsSkipped.length > 0 || h.edgesRefused > 0,
+      hopsRefused: h.hopsRefused,
+      groupsSkipped: h.groupsSkipped.slice(),
+      edgesRefused: h.edgesRefused,
+      ambiguousSummaries: h.summarizedGroups,
+      limits: { ...this._limits },
+    };
+  }
+  stats() {
+    return {
+      ...this._stats, groups: this._groups.size, nodes: this._build().nodes.size, edges: this._build().edges.size,
+      ...(this._v2 ? { correlationVersion: 2 } : null),
+    };
+  }
 
   /**
    * Four buckets, all "recorded, never thrown, never silently dropped"
@@ -395,6 +567,8 @@ export class PathStore {
       unclassified: this._unclassified,
       truncations: [...this._truncations.entries()],
       orphanedPeerSources: this._build().orphanedPeerSources,
+      limits: this.limitStatus(),
+      ...(this._v2 ? { correlationVersion: 2, versionPruned: this._build().versionPruned } : null),
     };
   }
 }