@clear-capabilities/agentic-security-scanner 0.161.0 → 0.163.0

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

@@ -0,0 +1,253 @@
+// cross-repo.js: resolve deployment boundaries across repositories (X-304).
+//
+// Extends the idea behind cross-repo-link.js (an operator declares that a node
+// in one repository depends on a node in another) from the data-flow graph to
+// the deployment boundary graph, and adds the two things that file's
+// declared-link flavour did not need: an exact revision on both ends, and an
+// access scope.
+//
+// Inputs are all local and all explicit: boundary graph exports the operator
+// supplies (one per repository), a list of declared dependencies, and the set
+// of repositories the operator is authorized to read. This module has no
+// network access and no way to fetch a missing repository: an unavailable one
+// is a gap, not a lookup. The source file contains no import of any network or
+// process module, and a test pins that.
+//
+// A link resolves only when every one of these holds, each tested in both
+// directions:
+//   - both repositories are in the access scope and a graph was supplied for
+//     each (otherwise: access-denied / repository-unavailable);
+//   - each supplied graph passes validation and says it is the repository it
+//     was supplied as (otherwise: graph-integrity / identity-collision);
+//   - the graph's revision equals the revision the declaration binds, exactly
+//     (otherwise: version-mismatch, or revision-unknown when the graph has none);
+//   - the declared service exists, resolved, in the graph of the repository it
+//     is declared in (otherwise: unresolved-identity), and no second supplied
+//     repository also resolves that identity (otherwise: identity-collision);
+//   - a declared entry route exists in the callee graph and reaches the callee
+//     service (otherwise the link stays unresolved; no route is guessed).
+//
+// An unresolved link is not dropped. It is kept in `links` with every gap code
+// that blocked it, and, when both revisions are bound by the declaration, as
+// an unresolved edge to an unresolved callee node in the federated graph, so
+// the dependency stays visible to path queries as a path nobody could verify.
+
+import { semanticId, digestOf } from '../../posture/assurance/identity.js';
+import {
+  buildBoundaryGraph, importBoundaryGraph, validateBoundaryGraph, nodeIdOf, indexGraph, findPath, boundaryCrossings,
+} from './boundary-graph.js';
+
+export const CROSS_REPO_PARSER = 'cross-repo-declaration';
+export const CROSS_REPO_PARSER_VERSION = '1';
+export const DEFAULT_DECLARATION_FILE = 'cross-repo-declarations.json';
+
+const REV = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SVC = /^[^\u0000-\u001f\u007f]{1,256}$/;
+
+function isObj(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+
+/** Check one declaration's shape. Returns an error message or null. Pure. */
+export function checkDeclaration(d) {
+  if (!isObj(d)) return 'declaration must be an object';
+  for (const side of ['caller', 'callee']) {
+    const s = d[side];
+    if (!isObj(s)) return `${side} is required`;
+    if (typeof s.repository !== 'string' || !NAME.test(s.repository)) return `${side}.repository must be a repository name`;
+    if (typeof s.revision !== 'string' || !REV.test(s.revision)) return `${side}.revision must be an exact 40 or 64 hex commit`;
+    if (typeof s.service !== 'string' || !SVC.test(s.service)) return `${side}.service must be a service name`;
+    if (typeof s.environment !== 'string' || !NAME.test(s.environment)) return `${side}.environment must be an environment name`;
+    if (s.tenant !== undefined && s.tenant !== null && (typeof s.tenant !== 'string' || !NAME.test(s.tenant))) return `${side}.tenant must be null or a name`;
+  }
+  if (d.caller.environment !== d.callee.environment) return 'a cross-repository link cannot join two environments';
+  if ((d.caller.tenant ?? null) !== (d.callee.tenant ?? null)) return 'a cross-repository link declares one tenant; a tenant transition needs its own declaration of both sides';
+  if (d.callee.route !== undefined && d.callee.route !== null) {
+    const r = d.callee.route;
+    if (!isObj(r) || (r.host !== undefined && typeof r.host !== 'string') || (r.path !== undefined && typeof r.path !== 'string')) return 'callee.route must be {host?, path?}';
+    if (r.host === undefined && r.path === undefined) return 'callee.route needs a host or a path';
+  }
+  return null;
+}
+
+export function declarationId(d) {
+  return semanticId('blink', {
+    callerRepository: d?.caller?.repository, callerRevision: d?.caller?.revision, callerService: d?.caller?.service,
+    calleeRepository: d?.callee?.repository, calleeRevision: d?.callee?.revision, calleeService: d?.callee?.service,
+    environment: d?.caller?.environment, tenant: d?.caller?.tenant ?? null, route: d?.callee?.route ?? null,
+  }, ['callerRepository', 'callerRevision', 'callerService', 'calleeRepository', 'calleeRevision', 'calleeService', 'environment', 'tenant', 'route']);
+}
+
+function pathUnder(prefix, p) {
+  if (typeof prefix !== 'string' || typeof p !== 'string') return false;
+  if (prefix === '/') return true;
+  return p === prefix || p.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`);
+}
+
+/**
+ * @param {object} p
+ * @param {Array<{repository: string, text?: string, graph?: object}>} p.graphs  supplied exports, one per repository
+ * @param {object[]} p.declarations
+ * @param {{authorizedRepositories: string[]}} p.accessScope
+ * @param {{file?: string}} [p.declarationSource]
+ */
+export function resolveCrossRepoBoundaries({ graphs = [], declarations = [], accessScope, declarationSource = {} } = {}) {
+  const gaps = [];
+  const gap = (code, subject, message) => gaps.push({ code, subject, file: null, message });
+  if (!isObj(accessScope) || !Array.isArray(accessScope.authorizedRepositories)) {
+    return { status: 'invalid-input', reason: 'accessScope.authorizedRepositories is required; with no scope nothing is authorized', graph: null, links: [], gaps: [] };
+  }
+  const authorized = new Set(accessScope.authorizedRepositories.filter(r => typeof r === 'string'));
+  const declFile = declarationSource.file ?? DEFAULT_DECLARATION_FILE;
+
+  // ---- load the supplied graphs
+  const supplied = new Map(); // repository -> { graph, index } for usable ones
+  const claimed = new Map();  // repository -> count of supplied entries claiming it
+  for (const g of graphs) if (isObj(g) && typeof g.repository === 'string') claimed.set(g.repository, (claimed.get(g.repository) ?? 0) + 1);
+  const usable = [];
+  for (const entry of graphs) {
+    if (!isObj(entry) || typeof entry.repository !== 'string') { gap('malformed-input', 'graphs', 'a supplied graph without a repository name is ignored'); continue; }
+    const repo = entry.repository;
+    if (!authorized.has(repo)) { gap('access-denied', repo, `repository '${repo}' is not in the access scope; its graph was supplied but is not read`); continue; }
+    if (claimed.get(repo) > 1) { gap('identity-collision', repo, `${claimed.get(repo)} supplied graphs claim to be repository '${repo}'; none is used`); continue; }
+    let graph;
+    if (typeof entry.text === 'string') {
+      const imp = importBoundaryGraph(entry.text);
+      if (imp.status !== 'ok') { gap('graph-integrity', repo, `the graph supplied for '${repo}' is ${imp.status}: ${imp.reason ?? imp.errors.map(e => e.message).slice(0, 3).join('; ')}`); continue; }
+      graph = imp.graph;
+    } else if (isObj(entry.graph)) {
+      const v = validateBoundaryGraph(entry.graph);
+      if (!v.ok) { gap('graph-integrity', repo, `the graph supplied for '${repo}' failed validation: ${v.errors.slice(0, 3).map(e => e.message).join('; ')}`); continue; }
+      graph = entry.graph;
+    } else { gap('malformed-input', repo, 'a supplied graph needs text or graph'); continue; }
+    if (graph.repository !== repo) { gap('identity-collision', repo, `the graph supplied as '${repo}' says it is repository '${graph.repository}'; it is not used`); continue; }
+    supplied.set(repo, { graph, index: indexGraph(graph) });
+    usable.push(graph);
+  }
+
+  // ---- resolve declarations
+  const links = [];
+  const crossEdges = [];
+  const extraNodes = [];
+  const sortedDecls = declarations.map((d, i) => ({ d, i })).sort((a, b) => (declarationId(a.d) < declarationId(b.d) ? -1 : declarationId(a.d) > declarationId(b.d) ? 1 : a.i - b.i));
+  const declDigest = digestOf(sortedDecls.map(x => x.d)); // order independent: the same declarations give the same evidence digest
+  for (const { d } of sortedDecls) {
+    const bad = checkDeclaration(d);
+    if (bad) { gap('malformed-input', 'declaration', bad); links.push({ declarationId: null, status: 'invalid', gapCodes: ['malformed-input'], evidence: null, transitions: null, edgeId: null }); continue; }
+    const id = declarationId(d);
+    const blocked = [];
+    const block = (code, message) => { blocked.push(code); gap(code, id, message); };
+    const env = d.caller.environment, tenant = d.caller.tenant ?? null;
+
+    const callerOk = authorized.has(d.caller.repository), calleeOk = authorized.has(d.callee.repository);
+    if (!callerOk) block('access-denied', `caller repository '${d.caller.repository}' is not in the access scope`);
+    if (!calleeOk) block('access-denied', `callee repository '${d.callee.repository}' is not in the access scope`);
+    const callerG = callerOk ? supplied.get(d.caller.repository) : null;
+    const calleeG = calleeOk ? supplied.get(d.callee.repository) : null;
+    if (callerOk && !callerG) block('repository-unavailable', `no usable graph was supplied for caller repository '${d.caller.repository}'`);
+    if (calleeOk && !calleeG) block('repository-unavailable', `no usable graph was supplied for callee repository '${d.callee.repository}'`);
+
+    for (const [side, g, decl] of [['caller', callerG, d.caller], ['callee', calleeG, d.callee]]) {
+      if (!g) continue;
+      if (g.graph.revision === null) block('revision-unknown', `the ${side} graph for '${decl.repository}' records no revision, so the declared revision cannot be verified`);
+      else if (g.graph.revision !== decl.revision) block('version-mismatch', `the ${side} graph for '${decl.repository}' is at ${g.graph.revision.slice(0, 12)}, the declaration binds ${decl.revision.slice(0, 12)}`);
+    }
+
+    const callerNodeId = nodeIdOf({ kind: 'service', name: d.caller.service, environment: env, tenant });
+    const calleeNodeId = nodeIdOf({ kind: 'service', name: d.callee.service, environment: env, tenant });
+    let callerNode = null, calleeNode = null;
+    if (callerG && !blocked.length) {
+      callerNode = callerG.index.nodesById.get(callerNodeId);
+      if (!callerNode || !callerNode.resolved) block('unresolved-identity', `service '${d.caller.service}' (${env}) is not a resolved service in '${d.caller.repository}' at the bound revision`);
+      else if (callerNode.repository !== null && callerNode.repository !== d.caller.repository) block('identity-collision', `service '${d.caller.service}' is owned by '${callerNode.repository}', not '${d.caller.repository}'`);
+    }
+    if (calleeG && !blocked.length) {
+      calleeNode = calleeG.index.nodesById.get(calleeNodeId);
+      if (!calleeNode || !calleeNode.resolved) block('unresolved-identity', `service '${d.callee.service}' (${env}) is not a resolved service in '${d.callee.repository}' at the bound revision`);
+      else if (calleeNode.repository !== null && calleeNode.repository !== d.callee.repository) block('identity-collision', `service '${d.callee.service}' is owned by '${calleeNode.repository}', not '${d.callee.repository}'`);
+      else {
+        const others = [...supplied.entries()].filter(([repo, s]) => repo !== d.callee.repository && s.index.nodesById.get(calleeNodeId)?.resolved);
+        if (others.length) block('identity-collision', `service '${d.callee.service}' (${env}) is also defined by ${others.map(([r]) => `'${r}'`).sort().join(', ')}; the callee identity is ambiguous`);
+      }
+    }
+
+    // route and privilege transitions
+    let routeNode = null, routeChain = null;
+    if (!blocked.length && d.callee.route) {
+      const want = d.callee.route;
+      const candidates = calleeG.graph.nodes.filter(n => n.kind === 'route' && n.environment === env && (n.tenant ?? null) === tenant
+        && (want.host === undefined || n.attrs.host === want.host || n.attrs.host === '*') && (want.path === undefined || pathUnder(n.attrs.path, want.path)));
+      for (const r of candidates.sort((a, b) => (a.id < b.id ? -1 : 1))) {
+        const chain = findPath(calleeG.index.out, r.id, calleeNodeId, { accept: (e) => e.relation === 'routes-to' && e.pathState !== 'blocked', maxHops: 4 });
+        if (chain) { routeNode = r; routeChain = chain; break; }
+      }
+      if (!routeNode) block('unresolved-identity', `no route matching ${JSON.stringify(want)} reaches '${d.callee.service}' in '${d.callee.repository}'`);
+    }
+
+    const crossRepo = { callerRepository: d.caller.repository, callerRevision: d.caller.revision, calleeRepository: d.callee.repository, calleeRevision: d.callee.revision };
+    const source = { file: declFile, digest: declDigest, parser: CROSS_REPO_PARSER, parserVersion: CROSS_REPO_PARSER_VERSION };
+    const baseEdge = { relation: 'calls', from: callerNodeId, environment: env, tenant, effect: 'none', provenance: 'static-config', confidence: 'high', observationInterval: null, completeness: null, sourceRevision: d.caller.revision, source, discriminator: `xrepo:${d.callee.repository}`, crossRepo, attrs: {} };
+
+    if (blocked.length) {
+      links.push({ declarationId: id, status: 'unresolved', caller: { ...d.caller }, callee: { ...d.callee }, gapCodes: [...new Set(blocked)].sort(), evidence: null, transitions: null, edgeId: null });
+      // Keep the dependency visible as an unresolved path, bound to the revisions the operator declared.
+      extraNodes.push(
+        { kind: 'service', name: d.caller.service, environment: env, tenant, repository: null, trustZone: 'unknown', resolved: false, unresolvedReason: 'cross-repository caller could not be verified', attrs: {}, declaredBy: [] },
+        { kind: 'service', name: d.callee.service, environment: env, tenant, repository: null, trustZone: 'unknown', resolved: false, unresolvedReason: `cross-repository callee could not be resolved (${[...new Set(blocked)].sort().join(', ')})`, attrs: {}, declaredBy: [] },
+      );
+      crossEdges.push({ ...baseEdge, to: calleeNodeId, pathState: 'unresolved', confidence: 'low' });
+      continue;
+    }
+
+    const targetId = routeNode ? routeNode.id : calleeNodeId;
+    const edge = { ...baseEdge, to: targetId, pathState: 'possible' };
+    crossEdges.push(edge);
+
+    const calleeAssumes = calleeG.graph.edges.filter(e => e.relation === 'assumes' && e.from === calleeNodeId);
+    const callerAssumes = callerG.graph.edges.filter(e => e.relation === 'assumes' && e.from === callerNodeId);
+    const privileges = calleeAssumes.map(a => ({
+      identityNodeId: a.to,
+      identity: calleeG.index.nodesById.get(a.to)?.name ?? null,
+      identityResolved: calleeG.index.nodesById.get(a.to)?.resolved ?? false,
+      assumesEdgeId: a.id,
+      grants: calleeG.graph.edges.filter(e => e.relation === 'grants' && e.from === a.to)
+        .map(e => ({ edgeId: e.id, resource: calleeG.index.nodesById.get(e.to)?.name ?? null, effect: e.effect, pathState: e.pathState, discriminator: e.discriminator }))
+        .sort((x, y) => (x.edgeId < y.edgeId ? -1 : 1)),
+    })).sort((x, y) => (x.identityNodeId < y.identityNodeId ? -1 : 1));
+    const nodeRefs = (g, nodeId) => (g.index.nodesById.get(nodeId)?.declaredBy ?? []).map(r => ({ ...r }));
+    links.push({
+      declarationId: id,
+      status: 'resolved',
+      caller: { ...d.caller }, callee: { ...d.callee },
+      gapCodes: [],
+      edgeId: null, // filled once the federated graph assigns ids
+      evidence: {
+        declaration: { file: declFile, digest: declDigest },
+        caller: { repository: d.caller.repository, revision: d.caller.revision, graphDigest: callerG.graph.digest, nodeId: callerNodeId, declaredBy: nodeRefs(callerG, callerNodeId) },
+        callee: { repository: d.callee.repository, revision: d.callee.revision, graphDigest: calleeG.graph.digest, nodeId: calleeNodeId, declaredBy: nodeRefs(calleeG, calleeNodeId) },
+        route: routeNode ? { nodeId: routeNode.id, name: routeNode.name, declaredBy: nodeRefs(calleeG, routeNode.id), chainEdgeIds: routeChain.map(e => e.id) } : null,
+      },
+      transitions: {
+        entry: routeNode ? { routeNodeId: routeNode.id, trustZone: routeNode.trustZone } : null,
+        callerIdentities: callerAssumes.map(a => ({ identityNodeId: a.to, identity: callerG.index.nodesById.get(a.to)?.name ?? null })).sort((x, y) => (x.identityNodeId < y.identityNodeId ? -1 : 1)),
+        calleePrivileges: privileges,
+      },
+      _edge: edge,
+    });
+  }
+
+  // ---- federated graph
+  const nodes = [...usable.flatMap(g => g.nodes), ...extraNodes];
+  const edges = [...usable.flatMap(g => g.edges), ...crossEdges];
+  const sources = [...usable.flatMap(g => g.sources), { file: declFile, digest: declDigest, parser: CROSS_REPO_PARSER, parserVersion: CROSS_REPO_PARSER_VERSION, bytes: JSON.stringify(declarations).length }];
+  const built = buildBoundaryGraph({ repository: null, revision: null, nodes, edges, gaps: [...usable.flatMap(g => g.gaps), ...gaps], sources });
+  if (!built.ok) return { status: 'invalid-graph', reason: 'the federated graph failed validation', graph: null, links: links.map(({ _edge, ...l }) => l), gaps, errors: built.errors };
+
+  // attach edge ids and boundary crossings to resolved links
+  const fIndex = indexGraph(built.graph);
+  const finalLinks = links.map(({ _edge, ...l }) => {
+    if (l.status !== 'resolved') return l;
+    const match = built.graph.edges.find(e => e.crossRepo && e.relation === 'calls' && e.from === _edge.from && e.to === _edge.to && e.crossRepo.calleeRepository === _edge.crossRepo.calleeRepository && e.crossRepo.calleeRevision === _edge.crossRepo.calleeRevision && e.crossRepo.callerRevision === _edge.crossRepo.callerRevision);
+    return { ...l, edgeId: match?.id ?? null, transitions: { ...l.transitions, crossings: match ? boundaryCrossings(match, fIndex.nodesById) : [] } };
+  });
+  return { status: 'ok', reason: null, graph: built.graph, links: finalLinks, gaps: built.graph.gaps };
+}

package/src/lineage/deployment/drift.js

@@ -0,0 +1,383 @@
+// drift.js: boundary drift between two revisions, with dependency-aware invalidation and impact-driven rescans (X-306).
+//
+// Four jobs, all pure (graphs in, records out; no clock, no file or network access):
+//
+//  1. `diffBoundaryGraphs` compares two validated graphs at stable node and edge ids and names what changed in terms a
+//     reviewer cares about: new exposure, changed privilege, tenant-boundary weakening, removed controls. Those four are
+//     `material`. Every other change to a non-structural relation is reported too (it still changes how a finding is
+//     conditioned) but is not material. It also diffs the SOURCES the two graphs were built from and names the edges each
+//     changed file supported, so a drift can be explained from the file that moved.
+//  2. `planRescan` maps each change to the hypotheses (findings) it can affect and lists the focused rescans. A hypothesis is
+//     affected only when its bound service is the service a change touches, or can reach it, or is reachable from it, in
+//     either revision. Unchanged components are not rescanned. A hypothesis that cannot be tied to a service cannot be proven
+//     independent of a change, so it makes the plan INCOMPLETE; so does a graph gap that stands for a missing dependency.
+//  3. `incrementalAnnotate` recomputes only the affected hypotheses and carries the rest forward. `compareScoped` then lets a
+//     test (or a caller) check the incremental result against a complete recomputation. Equivalence is the property that
+//     justifies not rescanning; an incomplete plan never claims it.
+//  4. `invalidatePathsForSources` drops exactly the paths a changed source file supported (through the edges and node
+//     declarations that cite it), reusing `invalidateChangedSources` for the graph itself.
+
+import { indexGraph, validateBoundaryGraph } from './boundary-graph.js';
+import { invalidateChangedSources } from './ingest.js';
+import { bindFindingToService, exposureReach, TRAVERSED_RELATIONS } from './attack-paths.js';
+import { semanticId, digestOf, hypothesisIdFromFinding } from '../../posture/assurance/identity.js';
+
+export const DRIFT_SCHEMA = 'agentic-security/boundary-drift';
+export const DRIFT_VERSION = '1.0.0';
+
+export const DRIFT_CATEGORIES = Object.freeze([
+  'new-exposure', 'changed-privilege', 'tenant-weakening', 'removed-control',
+  'control-added', 'privilege-reduced', 'exposure-reduced', 'connectivity-added', 'connectivity-removed', 'edge-changed',
+  'zone-changed', 'node-resolution-changed', 'service-added', 'service-removed',
+]);
+export const MATERIAL_CATEGORIES = Object.freeze(['new-exposure', 'changed-privilege', 'tenant-weakening', 'removed-control']);
+const MATERIAL = new Set(MATERIAL_CATEGORIES);
+
+// A gap of these kinds means a dependency of the graph is missing, so a conclusion drawn from it is incomplete.
+export const DEPENDENCY_GAP_CODES = Object.freeze([
+  'source-missing', 'source-changed', 'repository-unavailable', 'access-denied', 'version-mismatch', 'revision-unknown',
+  'graph-integrity', 'limit-exceeded', 'unresolved-identity',
+]);
+const DEPENDENCY_GAPS = new Set(DEPENDENCY_GAP_CODES);
+
+const TRAVERSED = new Set(TRAVERSED_RELATIONS);
+const STRUCTURAL = new Set(['defined-in', 'deployed-in', 'scoped-to']);
+const MAX_CLOSURE_HOPS = 8;
+
+const sortedUnique = (a) => [...new Set(a)].sort();
+const keyOf = (n) => `${n.kind}|${n.name}|${n.environment ?? ''}`;
+const isDeny = (e) => e.effect === 'deny' || e.relation === 'network-denies';
+
+// ------------------------------------------------------------ diff
+
+function stable(v) { return JSON.stringify(v, Object.keys(v ?? {}).sort()); }
+
+function sameEdgeBody(a, b) {
+  return a.pathState === b.pathState && a.confidence === b.confidence && stable(a.attrs ?? {}) === stable(b.attrs ?? {});
+}
+
+/**
+ * Compare two boundary graphs.
+ *
+ * @returns {{ ok: boolean, diff: object|null, errors: object[] }} never throws
+ */
+export function diffBoundaryGraphs(before, after) {
+  const vb = validateBoundaryGraph(before), va = validateBoundaryGraph(after);
+  if (!vb.ok || !va.ok) return { ok: false, diff: null, errors: [...vb.errors.map((e) => ({ ...e, side: 'before' })), ...va.errors.map((e) => ({ ...e, side: 'after' }))] };
+  if (before.repository !== null && after.repository !== null && before.repository !== after.repository) {
+    return { ok: false, diff: null, errors: [{ code: 'RULE_VIOLATION', path: 'repository', message: `graphs are for different repositories ('${before.repository}' and '${after.repository}'); a diff across repositories would hide every id as added or removed` }] };
+  }
+  const bi = indexGraph(before), ai = indexGraph(after);
+  const bEdges = new Map(before.edges.map((e) => [e.id, e]));
+  const aEdges = new Map(after.edges.map((e) => [e.id, e]));
+  const nodeOf = (id) => ai.nodesById.get(id) ?? bi.nodesById.get(id);
+  const changes = [];
+  const push = (category, o) => {
+    const nodeIds = sortedUnique(o.nodeIds ?? []);
+    const edgeIds = sortedUnique(o.edgeIds ?? []);
+    const env = o.environment ?? null;
+    changes.push({
+      id: semanticId('bdrift', { category, nodeIds, edgeIds, detail: o.detail ?? null }, ['category', 'nodeIds', 'edgeIds', 'detail']),
+      category, material: MATERIAL.has(category), nodeIds, edgeIds, environment: env, tenant: o.tenant ?? null,
+      description: o.description, before: o.before ?? null, after: o.after ?? null,
+    });
+  };
+  const endpointsOf = (e) => [e.from, e.to];
+
+  // 1. exposure
+  const rb = exposureReach(before), ra = exposureReach(after);
+  const rank = { definite: 2, unresolved: 1 };
+  for (const [id, a] of [...ra].sort((x, y) => (x[0] < y[0] ? -1 : 1))) {
+    const n = ai.nodesById.get(id);
+    if (!n || !['service', 'resource', 'route'].includes(n.kind)) continue;
+    const b = rb.get(id);
+    if (!b || rank[a.state] > rank[b.state]) {
+      push('new-exposure', {
+        nodeIds: [id], edgeIds: a.via, environment: n.environment, tenant: n.tenant, detail: a.state,
+        description: `${n.kind} '${n.name}' is ${a.state === 'definite' ? 'reachable' : 'possibly reachable'} from an exposed entry point${b ? ' (it was only possibly reachable before)' : ' and was not before'}`,
+        before: b ? b.state : null, after: a.state,
+      });
+    }
+  }
+  for (const [id, b] of [...rb].sort((x, y) => (x[0] < y[0] ? -1 : 1))) {
+    const n = bi.nodesById.get(id);
+    if (!n || !['service', 'resource', 'route'].includes(n.kind)) continue;
+    const a = ra.get(id);
+    if (!a || rank[a.state] < rank[b.state]) {
+      push('exposure-reduced', { nodeIds: [id], edgeIds: b.via, environment: n.environment, tenant: n.tenant, detail: a ? a.state : 'gone', description: `${n.kind} '${n.name}' is ${a ? 'less certainly' : 'no longer'} reachable from an exposed entry point`, before: b.state, after: a ? a.state : null });
+    }
+  }
+
+  // 2. edges added
+  for (const e of after.edges) {
+    if (bEdges.has(e.id) || STRUCTURAL.has(e.relation)) continue;
+    const f = nodeOf(e.from), t = nodeOf(e.to);
+    const label = `${e.relation} ${f?.name} -> ${t?.name}`;
+    const base = { nodeIds: endpointsOf(e), edgeIds: [e.id], environment: e.environment, tenant: e.tenant };
+    if (f?.tenant != null && t?.tenant != null && f.tenant !== t.tenant) {
+      push('tenant-weakening', { ...base, detail: 'cross-tenant-edge', description: `new ${label} crosses from tenant ${f.tenant} to tenant ${t.tenant}`, after: e.relation });
+    }
+    if (isDeny(e)) push('control-added', { ...base, description: `new explicit deny: ${label}`, after: e.relation });
+    else if (e.relation === 'grants' && e.effect === 'allow') push('changed-privilege', { ...base, detail: 'grant-added', description: `new grant: ${label}`, after: e.attrs ?? {} });
+    else if (e.relation === 'assumes') push('changed-privilege', { ...base, detail: 'identity-assumed', description: `workload ${f?.name} now assumes identity ${t?.name}`, after: e.relation });
+    else if (TRAVERSED.has(e.relation)) push('connectivity-added', { ...base, description: `new ${label}`, after: e.relation });
+  }
+
+  // 3. edges removed
+  for (const e of before.edges) {
+    if (aEdges.has(e.id) || STRUCTURAL.has(e.relation)) continue;
+    const f = nodeOf(e.from), t = nodeOf(e.to);
+    const label = `${e.relation} ${f?.name} -> ${t?.name}`;
+    const base = { nodeIds: endpointsOf(e), edgeIds: [e.id], environment: e.environment, tenant: e.tenant };
+    if (isDeny(e)) push('removed-control', { ...base, description: `explicit deny removed: ${label}`, before: e.relation });
+    else if (e.relation === 'grants' && e.effect === 'allow') push('privilege-reduced', { ...base, description: `grant removed: ${label}`, before: e.attrs ?? {} });
+    else if (TRAVERSED.has(e.relation)) push('connectivity-removed', { ...base, description: `removed ${label}`, before: e.relation });
+  }
+
+  // 4. edges present in both whose body changed
+  for (const e of after.edges) {
+    const old = bEdges.get(e.id);
+    if (!old || STRUCTURAL.has(e.relation) || sameEdgeBody(old, e)) continue;
+    const f = nodeOf(e.from), t = nodeOf(e.to);
+    const label = `${e.relation} ${f?.name} -> ${t?.name}`;
+    const base = { nodeIds: endpointsOf(e), edgeIds: [e.id], environment: e.environment, tenant: e.tenant };
+    if (e.relation === 'grants' && stable(old.attrs ?? {}) !== stable(e.attrs ?? {})) {
+      push('changed-privilege', { ...base, detail: 'grant-changed', description: `grant changed: ${label}`, before: old.attrs ?? {}, after: e.attrs ?? {} });
+    } else {
+      push('edge-changed', { ...base, detail: `${old.pathState}>${e.pathState}`, description: `${label} changed (state ${old.pathState} -> ${e.pathState}, confidence ${old.confidence} -> ${e.confidence})`, before: { pathState: old.pathState, confidence: old.confidence }, after: { pathState: e.pathState, confidence: e.confidence } });
+    }
+  }
+
+  // 5. nodes
+  const afterByKey = new Map();
+  for (const n of after.nodes) { if (!afterByKey.has(keyOf(n))) afterByKey.set(keyOf(n), []); afterByKey.get(keyOf(n)).push(n); }
+  for (const n of before.nodes) {
+    const same = ai.nodesById.get(n.id);
+    if (same) {
+      if (same.trustZone !== n.trustZone) push('zone-changed', { nodeIds: [n.id], environment: n.environment, tenant: n.tenant, detail: `${n.trustZone}>${same.trustZone}`, description: `${n.kind} '${n.name}' moved from trust zone ${n.trustZone} to ${same.trustZone}`, before: n.trustZone, after: same.trustZone });
+      if (same.resolved !== n.resolved) push('node-resolution-changed', { nodeIds: [n.id], environment: n.environment, tenant: n.tenant, detail: `${n.resolved}>${same.resolved}`, description: `${n.kind} '${n.name}' is now ${same.resolved ? 'resolved' : 'unresolved'}`, before: n.resolved, after: same.resolved });
+      continue;
+    }
+    // The id is gone. A tenant binding that was dropped keeps (kind, name, environment) but loses its tenant.
+    const twin = (afterByKey.get(keyOf(n)) ?? []).find((m) => m.tenant === null);
+    if (n.tenant !== null && twin) {
+      push('tenant-weakening', { nodeIds: [n.id, twin.id], environment: n.environment, tenant: n.tenant, detail: 'tenant-binding-lost', description: `${n.kind} '${n.name}' is no longer bound to tenant ${n.tenant}`, before: n.tenant, after: null });
+    } else if (n.kind === 'service' && !(afterByKey.get(keyOf(n)) ?? []).length) {
+      push('service-removed', { nodeIds: [n.id], environment: n.environment, tenant: n.tenant, description: `service '${n.name}' is no longer in the graph`, before: n.name });
+    }
+  }
+  for (const n of after.nodes) {
+    if (!bi.nodesById.has(n.id) && n.kind === 'service' && !before.nodes.some((m) => keyOf(m) === keyOf(n))) {
+      push('service-added', { nodeIds: [n.id], environment: n.environment, tenant: n.tenant, description: `service '${n.name}' is new`, after: n.name });
+    }
+  }
+
+  // Deterministic order, and one record per id.
+  const byId = new Map(changes.map((c) => [c.id, c]));
+  const list = [...byId.values()].sort((a, b) => (Number(b.material) - Number(a.material)) || (a.category < b.category ? -1 : a.category > b.category ? 1 : a.id < b.id ? -1 : 1));
+
+  // Sources: what moved on disk, and which edges each moved file supported.
+  const bSrc = new Map(before.sources.map((s) => [s.file, s]));
+  const aSrc = new Map(after.sources.map((s) => [s.file, s]));
+  const supportedBy = (graph, file) => graph.edges.filter((e) => e.source?.file === file).map((e) => e.id).sort();
+  const sources = { added: [], removed: [], changed: [] };
+  for (const [file, s] of [...aSrc].sort()) {
+    const o = bSrc.get(file);
+    if (!o) sources.added.push({ file, digest: s.digest, edgeIds: supportedBy(after, file) });
+    else if (o.digest !== s.digest) sources.changed.push({ file, beforeDigest: o.digest, afterDigest: s.digest, edgeIdsBefore: supportedBy(before, file), edgeIdsAfter: supportedBy(after, file) });
+  }
+  for (const [file, s] of [...bSrc].sort()) if (!aSrc.has(file)) sources.removed.push({ file, digest: s.digest, edgeIds: supportedBy(before, file) });
+
+  const incomplete = after.gaps.filter((g) => DEPENDENCY_GAPS.has(g.code)).map((g) => ({ code: g.code, subject: g.subject, message: g.message }));
+  const byCategory = {};
+  for (const c of list) byCategory[c.category] = (byCategory[c.category] ?? 0) + 1;
+  const diff = {
+    schema: DRIFT_SCHEMA, schemaVersion: DRIFT_VERSION,
+    repository: after.repository ?? before.repository, beforeDigest: before.digest, afterDigest: after.digest,
+    beforeRevision: before.revision, afterRevision: after.revision,
+    changes: list, sources, incomplete,
+    summary: { total: list.length, material: list.filter((c) => c.material).length, byCategory },
+  };
+  return { ok: true, diff, errors: [] };
+}
+
+/** Human-readable lines for a diff. States what changed and what it does not show; never says a change is safe. */
+export function explainDrift(diff) {
+  const lines = [];
+  if (!diff || !Array.isArray(diff.changes)) return ['no drift record'];
+  lines.push(`Boundary drift: ${diff.summary.total} change(s), ${diff.summary.material} material`);
+  for (const c of diff.changes) lines.push(`  ${c.material ? '[material] ' : ''}${c.category}: ${c.description}`);
+  if (!diff.changes.length) lines.push('  no change to a non-structural relation was found between these two graphs');
+  for (const s of diff.sources.changed) lines.push(`  source changed: ${s.file} (supported ${s.edgeIdsBefore.length} edge(s) before, ${s.edgeIdsAfter.length} now)`);
+  for (const s of diff.sources.removed) lines.push(`  source removed: ${s.file} (supported ${s.edgeIds.length} edge(s))`);
+  for (const s of diff.sources.added) lines.push(`  source added: ${s.file}`);
+  if (diff.incomplete.length) lines.push(`  incomplete inputs: ${sortedUnique(diff.incomplete.map((g) => g.code)).join(', ')}; a change behind them may be missing from this diff`);
+  lines.push('  This compares two configured graphs; it does not show how the deployed system behaves.');
+  return lines;
+}
+
+// ------------------------------------------------------------ impact: which hypotheses a change can affect
+
+function adjacency(graphs) {
+  const fwd = new Map(), rev = new Map();
+  for (const g of graphs) {
+    for (const e of g.edges) {
+      if (!TRAVERSED.has(e.relation) && !isDeny(e)) continue;
+      if (!fwd.has(e.from)) fwd.set(e.from, new Set());
+      fwd.get(e.from).add(e.to);
+      if (!rev.has(e.to)) rev.set(e.to, new Set());
+      rev.get(e.to).add(e.from);
+    }
+  }
+  return { fwd, rev };
+}
+
+function closure(start, map) {
+  const seen = new Set(start);
+  let frontier = [...start];
+  for (let hop = 0; hop < MAX_CLOSURE_HOPS && frontier.length; hop++) {
+    const next = [];
+    for (const id of frontier) for (const m of map.get(id) ?? []) if (!seen.has(m)) { seen.add(m); next.push(m); }
+    frontier = next;
+  }
+  return seen;
+}
+
+/** The (kind|name|environment) keys of every service a change can affect: its own, those that reach it, those it reaches. */
+function affectedServiceKeys(change, before, after) {
+  const nodes = new Map();
+  for (const g of [before, after]) for (const n of g.nodes) nodes.set(n.id, n);
+  const { fwd, rev } = adjacency([before, after]);
+  const seeds = change.nodeIds.filter((id) => nodes.has(id));
+  const reach = new Set([...closure(seeds, fwd), ...closure(seeds, rev)]);
+  const keys = new Set();
+  for (const id of reach) { const n = nodes.get(id); if (n && n.kind === 'service') keys.add(keyOf(n)); }
+  return keys;
+}
+
+function serviceKeyOfBinding(finding, bindings, before, after) {
+  for (const g of [after, before]) {
+    const b = bindFindingToService(finding, bindings, g);
+    if (b.status === 'bound') return { status: 'bound', key: keyOf(b.service), reason: b.reason };
+    if (b.status === 'unbound' || b.status === 'ambiguous') return { status: b.status, key: null, reason: b.reason };
+  }
+  // The service exists in neither graph (renamed or removed). Use the binding's own name so a removal still maps.
+  const b = bindFindingToService(finding, bindings, after);
+  if (b.binding && b.binding.environment) return { status: 'bound', key: `service|${b.binding.service}|${b.binding.environment}`, reason: 'service is absent from both graphs; matched by the binding name' };
+  return { status: b.status, key: null, reason: b.reason };
+}
+
+/**
+ * The focused rescan plan for a diff.
+ *
+ * @param {object} args
+ * @param {object} args.diff        from `diffBoundaryGraphs`
+ * @param {object} args.before
+ * @param {object} args.after
+ * @param {Array<{hypothesisId?:string, finding:object}>} args.hypotheses
+ * @param {Array} args.bindings     see `bindFindingToService`
+ */
+export function planRescan({ diff, before, after, hypotheses = [], bindings = [] } = {}) {
+  const affecting = diff.changes;
+  const incomplete = diff.incomplete.map((g) => ({ hypothesisId: null, code: g.code, reason: `${g.subject}: ${g.message}` }));
+  const serviceKeysByChange = new Map(affecting.map((c) => [c.id, affectedServiceKeys(c, before, after)]));
+  const rescan = [], skipped = [];
+  for (const h of hypotheses) {
+    const finding = h.finding ?? h;
+    const hypothesisId = h.hypothesisId ?? hypothesisIdFromFinding(finding);
+    const file = finding?.file ?? null;
+    const bound = serviceKeyOfBinding(finding, bindings, before, after);
+    if (bound.status !== 'bound') {
+      if (affecting.length) incomplete.push({ hypothesisId, code: 'unbound-hypothesis', reason: `${bound.reason}; it cannot be shown independent of the ${affecting.length} change(s), so it is neither rescanned nor cleared` });
+      else skipped.push({ hypothesisId, file, reason: 'no change between the two graphs' });
+      continue;
+    }
+    const reasons = affecting.filter((c) => serviceKeysByChange.get(c.id).has(bound.key)).map((c) => c.id);
+    if (reasons.length) rescan.push({ hypothesisId, file, serviceKey: bound.key, reasons });
+    else skipped.push({ hypothesisId, file, reason: `no changed relation touches, reaches or is reached by ${bound.key.split('|')[1]}` });
+  }
+  const sortById = (a, b) => (String(a.hypothesisId) < String(b.hypothesisId) ? -1 : 1);
+  rescan.sort(sortById); skipped.sort(sortById);
+  incomplete.sort((a, b) => `${a.code}|${a.hypothesisId}`.localeCompare(`${b.code}|${b.hypothesisId}`));
+  return {
+    status: incomplete.length ? 'incomplete' : 'complete',
+    changeIds: affecting.map((c) => c.id),
+    rescan, skipped, incomplete,
+    rescanFiles: sortedUnique(rescan.map((r) => r.file).filter(Boolean)),
+    statement: incomplete.length
+      ? `incomplete: ${incomplete.length} dependency problem(s) mean the plan cannot show that every unaffected hypothesis is independent of the change`
+      : `${rescan.length} hypothesis(es) to rescan, ${skipped.length} unaffected and not rescanned`,
+  };
+}
+
+// ------------------------------------------------------------ incremental vs complete
+
+/** The deployment-conditioned result for one hypothesis, without graph-wide metadata that moves between revisions. */
+export function scopedSignature(context) {
+  if (!context) return null;
+  return digestOf({
+    hypothesisId: context.hypothesisId, binding: context.binding.status, service: context.binding.service?.id ?? null,
+    exposure: context.exposure.state,
+    paths: context.paths.map((p) => ({ id: p.id, kind: p.kind, state: p.state, conditions: p.conditions.map((c) => c.kind), blockers: p.blockers.map((b) => b.edgeId), exploitability: p.exploitability.label })),
+    verification: context.verification.map((v) => [v.recordId, v.applicable]),
+  });
+}
+
+/**
+ * Recompute only the hypotheses the plan names and carry the rest forward.
+ *
+ * @param {object} args
+ * @param {object} args.plan
+ * @param {Array<{hypothesisId?:string, finding:object}>} args.hypotheses
+ * @param {Object<string, object>} args.previous  hypothesisId -> context from the earlier revision
+ * @param {(h: object) => object} args.annotate   recompute one hypothesis against the new revision
+ */
+export function incrementalAnnotate({ plan, hypotheses, previous = {}, annotate }) {
+  const idOf = (h) => h.hypothesisId ?? hypothesisIdFromFinding(h.finding ?? h);
+  const redo = new Set(plan.rescan.map((r) => r.hypothesisId));
+  const unproven = new Set(plan.incomplete.map((i) => i.hypothesisId).filter(Boolean));
+  const results = {}, recomputed = [], carried = [], stale = [];
+  for (const h of hypotheses) {
+    const id = idOf(h);
+    if (redo.has(id) || !(id in previous)) { results[id] = annotate(h); recomputed.push(id); }
+    else { results[id] = previous[id]; (unproven.has(id) ? stale : carried).push(id); }
+  }
+  return {
+    status: plan.status, results, recomputed: recomputed.sort(), carried: carried.sort(), stale: stale.sort(),
+    incomplete: plan.incomplete,
+  };
+}
+
+/** Compare an incremental result with a complete one on the scoped signature. An incomplete incremental result never matches. */
+export function compareScoped(incremental, complete) {
+  const ids = sortedUnique([...Object.keys(incremental.results), ...Object.keys(complete)]);
+  const differing = ids.filter((id) => scopedSignature(incremental.results[id]) !== scopedSignature(complete[id]));
+  const equivalent = incremental.status === 'complete' && differing.length === 0;
+  return { equivalent, differing, status: incremental.status };
+}
+
+// ------------------------------------------------------------ invalidation of paths by changed sources
+
+/**
+ * Which paths a set of changed or removed source files invalidates, and the graph with those relations dropped.
+ * A path is invalidated exactly when one of its supporting edges, or the declaration of one of its nodes, cites a changed file.
+ *
+ * @param {object[]} paths          path records (`computeAttackPaths`)
+ * @param {object} graph
+ * @param {Object<string,string>|Map} currentDigests  file -> sha256 now (absent means removed)
+ */
+export function invalidatePathsForSources(paths, graph, currentDigests) {
+  const inv = invalidateChangedSources(graph, currentDigests);
+  if (!inv.ok) return { ok: false, valid: [], invalidated: [], graph: null, staleFiles: inv.staleFiles, errors: inv.errors };
+  const staleEdges = new Set(inv.invalidatedEdgeIds);
+  const stale = new Set(inv.staleFiles);
+  const declaredOnlyByStale = new Set(graph.nodes.filter((n) => n.declaredBy.length && n.declaredBy.every((d) => stale.has(d.file))).map((n) => n.id));
+  const valid = [], invalidated = [];
+  for (const p of paths) {
+    const edgeIds = p.supportingEdgeIds.filter((id) => staleEdges.has(id));
+    const nodeIds = sortedUnique(p.hops.flatMap((h) => [h.from.id, h.to.id]).filter((id) => declaredOnlyByStale.has(id)));
+    if (edgeIds.length || nodeIds.length) invalidated.push({ pathId: p.id, edgeIds: sortedUnique(edgeIds), nodeIds });
+    else valid.push(p);
+  }
+  return { ok: true, valid, invalidated, graph: inv.graph, staleFiles: inv.staleFiles, errors: [] };
+}