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

package/src/lineage/control-credit.js

@@ -0,0 +1,313 @@
+//
+// control-credit.js: which controls protect which witness, and which do not (DAG-04, R04.5 / R04.6).
+//
+// A control earns credit on a witness only when ALL of these hold, each recorded as evidence:
+//   * the sanitizer's catalog family matches the SINK family (an HTML encoder does not protect SQL);
+//   * the value that reaches the sink is the value the control produced: the control's call sits ON the
+//     witness (an edge at its node), its result is what the witness carries, and every later read of the
+//     controlled variable sees exactly that definition (reassignment or a merge with another definition
+//     voids the credit: stale credit is refused);
+//   * nothing later on the same witness reverses it (decoders keyed by family, from sanitizer-gate.js).
+//
+// What this does NOT establish: that the sanitizer is correct. The family comes from the sanitizer
+// catalog, and dominance (a control on every path) is evidence about coverage, never proof of sanitizer
+// semantics. Every credit says so (`semanticsProof: false`). An unrecognized call that widened the value
+// (an opaque call) makes the witness `unknown`, not `unprotected` and never `protected`.
+//
+// Control state per witness: 'protected' | 'unprotected' | 'unknown'. `assessAllPathsProtectedWithControls`
+// feeds the real states into witness-selection.js `assessAllPathsProtected`, whose rules are unchanged:
+// it looks at every enumerated path, refuses on a truncated or resumed query, and one unprotected path
+// refutes the claim. An optional independent abstract proof (`abstractControlProof`) can license the claim
+// when enumeration was truncated, because it does not depend on which paths were enumerated.
+
+import { CATALOG } from '../dataflow/catalog.js';
+import { accessPathOf } from '../dataflow/access-paths.js';
+import { familyOfFinding, _reversedOnPath } from '../dataflow/sanitizer-gate.js';
+import { computeDominators } from '../ir/ssa.js';
+import { computeReachingDefinitions } from './value-versions.js';
+import { exprRoots, walkExpr } from './source-seeding.js';
+import { assessAllPathsProtected } from './witness-selection.js';
+import { recognizeTransformation } from './transform-catalog.js';
+
+export const CONTROL_CREDIT_VERSION = 'control-credit/1';
+
+const CREDIT_LIMITATIONS = Object.freeze([
+  'Sanitizer semantics come from the catalog family; correctness of the sanitizer itself is not proven.',
+  'Dominance or presence on the path is coverage evidence, not proof that the control neutralizes the sink.',
+  'Controls are matched by callee name; a project-local wrapper is an opaque call.',
+]);
+
+let _index = null;
+/** callee -> list of family sets, one per catalog entry (kept apart so name ambiguity is detectable). */
+function sanitizerIndex() {
+  if (_index) return _index;
+  _index = new Map();
+  for (const e of CATALOG) {
+    if (!e || e.kind !== 'sanitizer' || e.match?.type !== 'call' || !e.match.callee) continue;
+    const fams = Array.isArray(e.appliesTo) ? e.appliesTo : [];
+    if (!_index.has(e.match.callee)) _index.set(e.match.callee, []);
+    _index.get(e.match.callee).push(new Set(fams));
+  }
+  return _index;
+}
+
+function dotted(callee) {
+  if (typeof callee === 'string') return callee;
+  if (!callee) return null;
+  if (callee.kind === 'ident') return callee.name;
+  if (callee.kind === 'member') { const o = dotted(callee.object); return o ? `${o}.${callee.prop}` : callee.prop; }
+  return null;
+}
+
+/** Names a call may be known by, most specific first. */
+export function calleeNames(callee) {
+  const full = dotted(callee);
+  if (!full) return [];
+  const bare = full.split('.').pop();
+  return bare === full ? [full] : [full, bare];
+}
+
+/**
+ * The families a callee neutralizes: { known, families:Set, ambiguous }. `ambiguous` means the callee name
+ * is shared by catalog entries that disagree on families (a bare `escape`), so it cannot be credited.
+ */
+export function controlFamiliesOf(callee) {
+  const idx = sanitizerIndex();
+  for (const nm of calleeNames(callee)) {
+    const sets = idx.get(nm);
+    if (!sets) continue;
+    const key = (s) => [...s].sort().join(',');
+    const distinct = new Set(sets.map(key));
+    if (distinct.size > 1) return { known: true, name: nm, families: new Set(sets.flatMap((s) => [...s])), ambiguous: true };
+    return { known: true, name: nm, families: new Set(sets[0]), ambiguous: false };
+  }
+  return { known: false, name: null, families: new Set(), ambiguous: false };
+}
+
+/** The sink family for a catalog sink entry (`{ vuln: { cwe, name } }`) or a finding-shaped object. */
+export function sinkFamilyOf(x) {
+  if (!x) return null;
+  const v = x.vuln && typeof x.vuln === 'object' ? x.vuln : x;
+  return familyOfFinding({ cwe: v.cwe ?? x.cwe, vuln: typeof v.name === 'string' ? v.name : (typeof x.vuln === 'string' ? x.vuln : ''), family: x.family });
+}
+
+function callsAt(node) {
+  const calls = [];
+  if (!node) return calls;
+  for (const root of exprRoots(node)) walkExpr(root, (e) => { if (e.kind === 'call') calls.push(e); });
+  if (node.kind === 'call' && node.callee) calls.unshift({ kind: 'call', callee: node.callee, args: node.args ?? [] });
+  return calls;
+}
+
+const covers = (a, b) => typeof a === 'string' && typeof b === 'string' && (a === b || a.startsWith(`${b}.`) || b.startsWith(`${a}.`));
+
+function argReadsPath(call, fromPath) {
+  if (!fromPath) return false;
+  let hit = false;
+  for (const a of call.args ?? []) {
+    walkExpr(a, (e) => { if (!hit && (e.kind === 'ident' || e.kind === 'member')) { const p = e.kind === 'ident' ? e.name : accessPathOf(e); if (covers(p, fromPath)) hit = true; } });
+  }
+  return hit;
+}
+
+const _rdCache = new WeakMap();
+function rdOf(fn) {
+  const cfg = fn?.cfg;
+  if (!cfg) return null;
+  let rd = _rdCache.get(cfg);
+  if (!rd) { rd = computeReachingDefinitions({ cfg: { entry: cfg.entry, nodes: cfg.nodes }, params: fn.params ?? [] }); _rdCache.set(cfg, rd); }
+  return rd;
+}
+
+function isWidened(h) {
+  return (h.widenReasons ?? []).includes('unresolved-call') || (h.annotations ?? []).some((a) => a.widenReason === 'unresolved-call');
+}
+
+/**
+ * Judge one witness.
+ *
+ * @param {object} o
+ * @param {object[]} o.hops           `path.hops`, source first
+ * @param {(id:string)=>object|null} o.nodeOf  store.getNode (to read each hop's from/to access paths)
+ * @param {(qid:string)=>object|null} o.fnOf   IR function lookup
+ * @param {string|null} o.sinkFamily  the family of the sink (see sinkFamilyOf), null when unknown
+ * @param {boolean} [o.truncated]     the path is incomplete or analysis was cut short
+ */
+export function creditPath({ hops, nodeOf, fnOf, sinkFamily = null, truncated = false } = {}) {
+  const list = Array.isArray(hops) ? hops : [];
+  const credits = []; const rejected = []; const opaque = [];
+  const pathOf = (id) => nodeOf?.(id)?.path ?? null;
+
+  for (let i = 0; i < list.length; i++) {
+    const h = list[i];
+    const fn = fnOf?.(h.scope);
+    const node = fn?.cfg?.nodes?.[h.siteNodeId];
+    if (!node) continue;
+    const fromPath = pathOf(h.fromNodeId);
+    const calls = callsAt(node);
+    let recognizedHere = false;
+
+    for (const c of calls) {
+      const fam = controlFamiliesOf(c.callee);
+      if (!fam.known) continue;
+      recognizedHere = true;
+      const where = { edgeId: h.edgeId ?? null, scope: h.scope, nodeId: h.siteNodeId, callee: fam.name, families: [...fam.families].sort() };
+      if (!argReadsPath(c, fromPath)) { rejected.push({ ...where, reason: 'value-not-through-control' }); continue; }
+      // The control's result must be what the witness carries.
+      const viaAssign = node.kind === 'assign' && node.source === c && typeof node.target === 'string';
+      const viaSinkArg = node.kind === 'call' && (node.args ?? []).includes(c);
+      if (!viaAssign && !viaSinkArg) { rejected.push({ ...where, reason: 'result-not-carried' }); continue; }
+      if (fam.ambiguous) { rejected.push({ ...where, reason: 'ambiguous-callee-family' }); opaque.push({ ...where, reason: 'ambiguous-callee-family' }); continue; }
+      if (!sinkFamily) { rejected.push({ ...where, reason: 'sink-family-unknown' }); opaque.push({ ...where, reason: 'sink-family-unknown' }); continue; }
+      if (!fam.families.has(sinkFamily) && !fam.families.has('*')) { rejected.push({ ...where, reason: 'wrong-family', sinkFamily }); continue; }
+
+      // Value version: later reads of the controlled variable must see exactly this definition.
+      let versionOk = true; let versionReason = null;
+      if (viaAssign) {
+        const T = node.target;
+        for (let j = i + 1; j < list.length; j++) {
+          const hj = list[j];
+          if (hj.scope !== h.scope) continue;
+          const fj = pathOf(hj.fromNodeId);
+          if (!covers(fj, T)) continue;
+          const rd = rdOf(fnOf(hj.scope));
+          const vers = rd ? rd.versionsAt(hj.siteNodeId, T) : [];
+          if (!vers.includes(h.siteNodeId)) { versionOk = false; versionReason = 'stale-control-version'; break; }
+          if (vers.length > 1) { versionOk = false; versionReason = 'merged-with-other-definition'; break; }
+        }
+      }
+      if (!versionOk) { rejected.push({ ...where, reason: versionReason }); if (versionReason === 'merged-with-other-definition') opaque.push({ ...where, reason: versionReason }); continue; }
+
+      // Reversal later on the same witness voids the credit.
+      let reversedBy = null;
+      for (let j = i + 1; j < list.length && !reversedBy; j++) {
+        const nj = fnOf?.(list[j].scope)?.cfg?.nodes?.[list[j].siteNodeId];
+        for (const cj of callsAt(nj)) {
+          const hit = _reversedOnPath(calleeNames(cj.callee), sinkFamily);
+          if (hit) { reversedBy = hit; break; }
+        }
+      }
+      if (reversedBy) { rejected.push({ ...where, reason: `reversed:${reversedBy}` }); continue; }
+
+      credits.push({
+        ...where, sinkFamily, valueVersion: viaAssign ? h.siteNodeId : 'at-sink-argument',
+        basis: ['catalog-family', 'on-witness', 'value-version'], semanticsProof: false,
+      });
+    }
+
+    // A parameterized query is the SQL-specific control that is not a call to a sanitizer: the value enters as a
+    // bound parameter and never as query text. Credited only for the sql sink family.
+    if (sinkFamily === 'sql' && isParameterizedSqlCall(node, fromPath)) {
+      credits.push({
+        edgeId: h.edgeId ?? null, scope: h.scope, nodeId: h.siteNodeId, callee: 'parameterized-query', families: ['sql'], sinkFamily,
+        valueVersion: 'bound-parameter', basis: ['placeholder-binding', 'on-witness'], semanticsProof: false,
+      });
+    }
+
+    // An unrecognized call that widened the value could be a control; the witness cannot be called unprotected.
+    if (!recognizedHere && isWidened(h)) {
+      const names = calls.map((c) => dotted(c.callee)).filter(Boolean);
+      // A known decoder is not opaque: it is a recognized reversal (and is judged as such above).
+      const known = calls.length > 0 && calls.every((c) => controlFamiliesOf(c.callee).known
+        || recognizeTransformation(callDescriptor(c.callee))
+        || (sinkFamily && _reversedOnPath(calleeNames(c.callee), sinkFamily)));
+      if (!known) opaque.push({ edgeId: h.edgeId ?? null, scope: h.scope, nodeId: h.siteNodeId, callees: names, reason: 'opaque-call' });
+    }
+  }
+
+  let controlState;
+  const reasons = [];
+  if (credits.length) { controlState = 'protected'; reasons.push('matching-control-on-witness'); }
+  else if (opaque.length) { controlState = 'unknown'; reasons.push(...new Set(opaque.map((o) => o.reason))); }
+  else if (truncated) { controlState = 'unknown'; reasons.push('witness-incomplete'); }
+  else { controlState = 'unprotected'; reasons.push(rejected.length ? [...new Set(rejected.map((r) => r.reason))].sort().join(',') : 'no-control-on-witness'); }
+  return {
+    version: CONTROL_CREDIT_VERSION, controlState, reasons,
+    credits, rejected, opaque, sinkFamily, limitations: [...CREDIT_LIMITATIONS],
+  };
+}
+
+const PLACEHOLDER_RE = /(\?|\$\d+|:[A-Za-z_]\w*|%s|@[A-Za-z_]\w*)/;
+
+/** `db.query('... WHERE id = ?', [value])`: a literal query text with placeholders, the witness value only in later arguments. */
+export function isParameterizedSqlCall(node, fromPath) {
+  if (!node || node.kind !== 'call') return false;
+  const args = node.args ?? [];
+  const text = args[0];
+  if (args.length < 2 || !text || text.kind !== 'literal' || typeof text.value !== 'string' || !PLACEHOLDER_RE.test(text.value)) return false;
+  return argReadsPath({ args: args.slice(1) }, fromPath);
+}
+
+function callDescriptor(callee) {
+  if (typeof callee === 'string') return { type: 'call', callee };
+  if (!callee) return null;
+  if (callee.kind === 'ident') return { type: 'call', callee: callee.name };
+  if (callee.kind === 'member' && callee.object?.kind === 'ident') return { type: 'member-call', object: callee.object.name, method: callee.prop };
+  if (callee.kind === 'member') return { type: 'call', callee: callee.prop };
+  return null;
+}
+
+/**
+ * An independent, intraprocedural abstract proof that a matching control covers EVERY path to a sink
+ * argument: a control assignment dominates the sink node and is the only definition of the variable that
+ * reaches it. It does not depend on which witnesses were enumerated. It is still evidence about coverage:
+ * the control's correctness comes from the catalog family.
+ */
+export function abstractControlProof(fn, { sinkNodeId, variable, sinkFamily }) {
+  const cfg = fn?.cfg;
+  if (!cfg || !sinkFamily || !variable) return { proved: false, reason: 'insufficient-input', semanticsProof: false };
+  const nodes = cfg.nodes instanceof Map ? Object.fromEntries(cfg.nodes) : cfg.nodes;
+  if (!nodes[sinkNodeId]) return { proved: false, reason: 'unknown-sink-node', semanticsProof: false };
+  const dom = computeDominators({ entry: cfg.entry, nodes });
+  const rd = rdOf(fn);
+  const vers = rd.versionsAt(sinkNodeId, variable);
+  if (vers.length !== 1) return { proved: false, reason: 'multiple-reaching-definitions', semanticsProof: false };
+  const defId = vers[0];
+  const def = nodes[defId];
+  if (!def || def.kind !== 'assign' || !dom.get(sinkNodeId)?.has(defId)) return { proved: false, reason: 'definition-does-not-dominate-sink', semanticsProof: false };
+  const call = def.source?.kind === 'call' ? def.source : null;
+  const fam = call ? controlFamiliesOf(call.callee) : null;
+  if (!fam?.known || fam.ambiguous) return { proved: false, reason: 'definition-is-not-a-recognized-control', semanticsProof: false };
+  if (!fam.families.has(sinkFamily) && !fam.families.has('*')) return { proved: false, reason: 'wrong-family', semanticsProof: false };
+  return {
+    proved: true, controlNodeId: defId, callee: fam.name, sinkFamily, basis: ['dominance', 'single-reaching-definition', 'catalog-family'],
+    semanticsProof: false, limitations: [...CREDIT_LIMITATIONS, 'Intraprocedural: other functions that reach the same sink are not covered by this proof.'],
+  };
+}
+
+/**
+ * "Every path is protected", answered from real control states (R04.6).
+ *
+ * @param {object} o
+ * @param {object} o.result       the reconstructPaths result
+ * @param {object[]} o.enumerated every enumerated path (not just the displayed ones), with `.hops`
+ * @param {Map<string,object>|((p:object)=>object)} o.evidenceOf per-path { controlState, feasibility? }
+ * @param {object} [o.proof]      abstractControlProof result, an independent licence for the claim
+ *
+ * Paths whose feasibility is `infeasible-under-model` are excluded from the relevant set and LISTED, so the
+ * claim is explicitly scoped to the modeled feasible paths. unknown, unsupported and timeout paths stay
+ * relevant: they cannot be dismissed. The claim never rests on the displayed sample.
+ */
+export function assessAllPathsProtectedWithControls({ result, enumerated, evidenceOf, proof = null }) {
+  const get = (p) => (typeof evidenceOf === 'function' ? evidenceOf(p) : evidenceOf?.get?.(p.id)) ?? null;
+  const all = Array.isArray(enumerated) ? enumerated : [];
+  const excludedInfeasible = []; const relevant = [];
+  for (const p of all) {
+    const ev = get(p);
+    if (ev?.feasibility?.status === 'infeasible-under-model') excludedInfeasible.push({ pathId: p.id, contradiction: ev.feasibility.contradiction ?? null });
+    else relevant.push(p);
+  }
+  const attrsOf = (p) => ({ controlState: get(p)?.controlState ?? 'unknown' });
+  const base = assessAllPathsProtected({ result, enumerated: relevant, attrsOf });
+  const out = {
+    ...base, semanticsVersion: CONTROL_CREDIT_VERSION, claimScope: 'modeled-feasible-paths',
+    relevantPathCount: relevant.length, excludedInfeasible, basis: 'enumeration', abstractProof: proof ?? null,
+  };
+  if (base.holds === false) return out;
+  // Enumeration could not establish the claim (truncated, resumed, or unknown states). An independent abstract
+  // proof can, because it does not depend on which paths were enumerated. A refutation above always wins.
+  if (!base.allowed && proof?.proved) {
+    return { ...out, allowed: true, holds: true, basis: 'abstract-proof', reasons: base.reasons.filter((r) => r !== 'refuted-by-unprotected-path'), proofCovers: 'every path to the sink argument within the function' };
+  }
+  return out;
+}

package/src/lineage/correlation.js

@@ -0,0 +1,199 @@
+//
+// correlation.js: provenance correlation version 2 (DAG-03).
+//
+// Version 1 pairs the production and consumption halves of a hop at a join
+// key (scope, nodeId, dataElementId, context) and marks the pairings it
+// cannot tell apart as `ambiguousCorrelation`. Version 2 adds evidence the
+// engine had at the moment it emitted each half, so that halves pair only
+// when that evidence proves them compatible:
+//
+//   derivationId     where inside the CFG node's expression tree an in-half
+//                    was produced (a segment path such as `/src/p:left/a0`)
+//   derivationScope  the part of that tree an out-half consumes
+//   relPath          the field path of an in-half relative to the value it
+//                    is selected from, and of an out-half relative to the
+//                    value it writes
+//   fromVersions     the definitions of the read path that reach the read
+//   toVersion        the definition a write creates
+//   invocationId     one id per call expression instance
+//   callRole         'arg' | 'bind' | 'return'
+//   argPosition / formalPosition   actual and formal argument positions
+//
+// Version 2 is OFF by default. It is enabled per call site by the
+// `correlationVersion: 2` option or process-wide by
+// AGENTIC_SECURITY_LINEAGE_CORRELATION=2. With it off no module in this
+// package emits, reads or hashes any of the fields above, so version 1
+// output, ids and digests are byte-identical to the pre-DAG-03 behavior.
+//
+// A hop that lacks the evidence (a hand-built stream, an older recorder, an
+// expression kind that carries no derivation) is never pruned: it pairs the
+// way version 1 paired it and the edge says so (`correlation:
+// 'legacy-unknown'`). Evidence only ever removes pairings that are proven
+// incompatible; it never removes a marked edge to make a metric look better.
+//
+import * as crypto from 'node:crypto';
+import { provenanceNodeId, provenanceEdgeId } from './ids.js';
+
+export const CORRELATION_VERSION_1 = 1;
+export const CORRELATION_VERSION_2 = 2;
+
+/** Additive hop fields version 2 adds to the 14 version 1 fields. */
+export const V2_HOP_FIELDS = [
+  'derivationId', 'derivationScope', 'relPath', 'fromVersions', 'toVersion',
+  'invocationId', 'callRole', 'argPosition', 'formalPosition', 'allocKind', 'receiver',
+];
+
+/** Default bound on the call-context stack a balanced traversal tracks. */
+export const DEFAULT_MAX_CALL_DEPTH = 8;
+
+/**
+ * Resolves the effective correlation version. An explicit option wins over
+ * the environment; anything other than 2 (or '2') is version 1.
+ */
+export function resolveCorrelationVersion(option) {
+  if (option !== undefined && option !== null) {
+    return Number(option) === CORRELATION_VERSION_2 ? CORRELATION_VERSION_2 : CORRELATION_VERSION_1;
+  }
+  return process.env.AGENTIC_SECURITY_LINEAGE_CORRELATION === '2' ? CORRELATION_VERSION_2 : CORRELATION_VERSION_1;
+}
+
+// --- derivation ids ---------------------------------------------------
+
+/** Appends one segment to a derivation path. */
+export function deriveChild(parent, seg) {
+  return `${parent ?? ''}/${seg}`;
+}
+
+/**
+ * Is `scope` a segment-aligned prefix of (or equal to) `id`? An out-half
+ * whose scope is `/src/p:left` consumes `/src/p:left` and everything under
+ * it, but not `/src/p:leftover`.
+ */
+export function derivationCovers(scope, id) {
+  if (scope === '' || scope === null || scope === undefined) return true;
+  return id === scope || id.startsWith(`${scope}/`);
+}
+
+/**
+ * For an out-half that writes the byPath entry `subPath` of a value built by
+ * `expr`, returns the derivation scope that entry was produced under and the
+ * part of `subPath` left over below that scope. Only an object literal names
+ * its properties; every other expression kind keeps the root scope, which
+ * is the version 1 behavior (all in-halves of the node are candidates).
+ */
+export function scopeForSubPath(expr, subPath, rootDerivation) {
+  let scope = rootDerivation ?? '';
+  let rest = subPath ?? '';
+  let cur = expr;
+  while (cur && cur.kind === 'object' && rest !== '') {
+    const dot = rest.indexOf('.');
+    const head = dot === -1 ? rest : rest.slice(0, dot);
+    const tail = dot === -1 ? '' : rest.slice(dot + 1);
+    const props = (cur.props ?? []).filter((p) => !p.spread && p.key === head);
+    if (props.length !== 1) break; // absent, duplicated or computed: keep the wider scope
+    scope = deriveChild(scope, `p:${head}`);
+    rest = tail;
+    cur = props[0].value;
+  }
+  return { scope, rest };
+}
+
+/** The field path of `key` relative to the queried path (empty when the key is the path or an ancestor). */
+export function relPathOf(key, path) {
+  if (typeof key !== 'string' || typeof path !== 'string') return null;
+  return key.length > path.length && key.startsWith(`${path}.`) ? key.slice(path.length + 1) : '';
+}
+
+/** One id per call expression instance in a function context. */
+export function invocationIdOf({ scope, nodeId, context, derivation }) {
+  const h = crypto.createHash('sha256')
+    .update([scope, nodeId, context, derivation].map((p) => (p === null || p === undefined ? '' : String(p))).join('|'))
+    .digest('hex').slice(0, 12);
+  return `inv:${h}`;
+}
+
+// Two relative field paths disagree only when BOTH name a field and the names
+// differ. An empty path is a container-level fact, which applies to every
+// field of the container, so it never disagrees: pruning on it would drop a
+// real edge.
+function fieldsDisagree(a, b) {
+  return typeof a === 'string' && typeof b === 'string' && a !== '' && b !== '' && a !== b;
+}
+
+// --- pairing -----------------------------------------------------------
+
+/**
+ * Are an in-half `s` and an out-half `o` of one group compatible under
+ * version 2? Both arguments are `{hop}` wrappers. `true` means "pair them";
+ * `evidence` says whether the pairing is proven by ids on both sides.
+ */
+export function pairCompatibility(sHop, oHop) {
+  // A call argument feeds exactly the parameter binding of the same
+  // invocation and position. It never reaches the assignment that receives
+  // the call's result, because the value goes through the callee.
+  if (sHop.callRole === 'arg') {
+    const ok = oHop.callRole === 'bind'
+      && oHop.invocationId === sHop.invocationId
+      && oHop.formalPosition === sHop.argPosition
+      && !fieldsDisagree(sHop.relPath, oHop.relPath);
+    return { compatible: ok, proven: true };
+  }
+  if (oHop.callRole === 'bind') return { compatible: false, proven: true };
+  if (sHop.derivationId != null && oHop.derivationScope != null) {
+    if (!derivationCovers(oHop.derivationScope, sHop.derivationId)) return { compatible: false, proven: true };
+    if (fieldsDisagree(sHop.relPath, oHop.relPath)) return { compatible: false, proven: true };
+    return { compatible: true, proven: true };
+  }
+  return { compatible: true, proven: false };
+}
+
+// --- crosswalk ---------------------------------------------------------
+
+/**
+ * Version 1 to version 2 crosswalk for a built version 2 store. A version 1
+ * id names a (scope, context, path, data element) location; the version 2
+ * ids under it are the value versions of that location. An edge crosswalks
+ * the same way through its endpoints.
+ *
+ *   { version: 2, nodes: [{ v1, v2: [ids] }], edges: [{ v1, v2: [ids] }],
+ *     unmapped: { nodes: [...], edges: [...] } }
+ *
+ * Every version 2 id appears under exactly one version 1 id, so the
+ * crosswalk is total over the store; `unmapped` is always empty for a
+ * correct store and exists so a test can assert that.
+ */
+export function buildCrosswalk(store) {
+  const nodes = store.nodes();
+  const edges = store.edges();
+  const v1OfNode = new Map();
+  const nodeGroups = new Map();
+  for (const n of nodes) {
+    const v1 = provenanceNodeId({
+      kind: n.kind, scope: n.scope, context: n.context, path: n.path,
+      siteNodeId: n.siteNodeId, dataElementId: n.dataElementId,
+    });
+    v1OfNode.set(n.id, v1);
+    if (!nodeGroups.has(v1)) nodeGroups.set(v1, []);
+    nodeGroups.get(v1).push(n.id);
+  }
+  const edgeGroups = new Map();
+  for (const e of edges) {
+    const v1 = provenanceEdgeId({
+      fromNodeId: v1OfNode.get(e.fromNodeId), toNodeId: v1OfNode.get(e.toNodeId),
+      dataElementId: e.dataElementId, scope: e.scope, context: e.context, siteNodeId: e.siteNodeId,
+      inKind: e.inKind, inSubKind: e.inSubKind, outKind: e.outKind, outSubKind: e.outSubKind,
+      widenReasons: e.widenReasons, lossReasons: e.lossReasons,
+    });
+    if (!edgeGroups.has(v1)) edgeGroups.set(v1, []);
+    edgeGroups.get(v1).push(e.id);
+  }
+  const toRows = (m) => [...m.entries()]
+    .map(([v1, v2]) => ({ v1, v2: [...new Set(v2)].sort() }))
+    .sort((a, b) => (a.v1 < b.v1 ? -1 : a.v1 > b.v1 ? 1 : 0));
+  return {
+    version: CORRELATION_VERSION_2,
+    nodes: toRows(nodeGroups),
+    edges: toRows(edgeGroups),
+    unmapped: { nodes: [], edges: [] },
+  };
+}

package/src/lineage/coverage.js

@@ -442,7 +442,14 @@ export function buildCoverageLedger(built, opts = {}) {
     paths: { enumerated: built.stats.pathsEnumerated, projected: built.stats.pathsProjected, truncatedQueries: built.stats.truncatedQueries },
     budgets: { ...PATH_QUERY_DEFAULTS, ...(opts.budget ?? {}) },
 
-    provenance: { hops: built.hops.length, pnodes: storeStats.nodes, pedges: storeStats.edges },
+    provenance: {
+      hops: built.hops.length, pnodes: storeStats.nodes, pedges: storeStats.edges,
+      ...(storeStats.correlationVersion ? { correlationVersion: storeStats.correlationVersion } : null),
+    },
+    // DAG-07: present only when some function stopped early, so a complete
+    // run's ledger (and its digest) is unchanged.
+    ...(built.analysisCompletion && built.analysisCompletion.status !== 'complete'
+      ? { analysisCompletion: built.analysisCompletion } : {}),
   };
 }
 

package/src/lineage/cross-repo-link.js

@@ -127,3 +127,25 @@ export function validateCrossRepoLink(record) {
 
   return { valid: errors.length === 0, errors };
 }
+
+// DAG-08: attributable link evidence. A CrossRepoLink is an operator assertion, so as evidence it is a `manual-assertion`: it is
+// not foreign-graph validation, a digest check, a code mapping or an observed connection, and nothing here can turn it into one.
+// The Haskell/Nix analysis scope declared on either endpoint is carried through unchanged, so a link to static Nix evidence stays
+// static-configuration evidence.
+export function linkEvidence(link) {
+  const scope = {};
+  for (const s of ['local', 'remote']) {
+    const sc = link && link.scope && link.scope[s];
+    if (sc) scope[s] = { target: sc.target ?? null, config: sc.config ?? null, analysis: sc.analysis ?? null, limitations: sc.limitations || [] };
+  }
+  return {
+    kind: 'manual-assertion', declared: true, observed: false, linkId: link && link.id, declaredBy: link && link.declaredBy,
+    declaredAt: link && link.declaredAt, provenance: link && link.provenance, scope,
+    staticConfigurationOnly: Object.values(scope).some((sc) => sc.analysis && sc.analysis.runtime === false),
+  };
+}
+
+/** True only for a structurally valid declared link that does not claim to be observed. */
+export function isDeclaredNotObserved(link) {
+  return !!link && validateCrossRepoLink(link).valid && !(link.evidence && link.evidence.observed === true);
+}