@clear-capabilities/agentic-security-scanner 0.172.1 → 0.173.0

package/src/ir/semantic-graph.js

@@ -0,0 +1,245 @@
+// SemanticGraph v1: a typed, versioned, additive view over the Layer-1 IR (E2-01).
+//
+// WHY. The IR (`buildProjectIR`) is a bag of per-function records consumed by the taint engine. It has no stable identifiers, no shared
+// entity types and no serialization contract, so every analysis that needs "the call at this place" or "where did this value come from"
+// re-derives it with its own conventions, and nothing can be compared across runs. This module names the entities once, gives each a
+// STABLE id, and fixes a versioned wire format.
+//
+// ADDITIVE. Building the graph reads the IR and never modifies it; it is not wired into findings, `chain[]` or last-scan.json. Existing
+// output is unchanged by construction (a test pins that). A consumer opts in by calling `buildSemanticGraph`.
+//
+// HONEST. An entity type the IR cannot yet supply (Sanitizer, Guard, ServiceBoundary, StorageEdge) is declared in the schema, emitted as an
+// empty list, and reported `schema-only` in `coverage` with the reason. A location the IR does not carry (column) is `null` and the entity
+// says `locationPrecision: 'line'`. Nothing is guessed to fill a field.
+//
+// STABLE IDS. An id is the first 16 hex of SHA-256 over the entity's kind and its identity fields, which never include a line number: adding
+// a blank line above a function does not change any id in it. Ties between otherwise identical entities (two `exec(x)` in one function) are
+// broken by their order of appearance in that function.
+import { createHash } from 'node:crypto';
+import { analysisLimits } from '../dataflow/analysis-limits.js';
+
+export const SEMANTIC_GRAPH_SCHEMA = 'agentic-security/semantic-graph';
+export const SEMANTIC_GRAPH_VERSION = '1.0.0';
+export const SUPPORTED_MAJOR = 1;
+
+export const ENTITY_LISTS = Object.freeze(['symbols', 'callSites', 'allocations', 'fieldAccesses', 'valueOrigins', 'serviceBoundaries', 'storageEdges', 'sanitizers', 'guards']);
+export const CONFIDENCE_TIERS = Object.freeze(['observed', 'inferred', 'unresolved']);
+const SYMBOL_KINDS = Object.freeze(['module', 'function', 'class', 'variable', 'parameter']);
+const ORIGIN_KINDS = Object.freeze(['parameter', 'call-result', 'literal', 'member', 'concat', 'object', 'array', 'function', 'identifier', 'unknown']);
+
+const ID_PREFIX = Object.freeze({ symbols: 'sym', callSites: 'call', allocations: 'alloc', fieldAccesses: 'field', valueOrigins: 'orig', serviceBoundaries: 'svc', storageEdges: 'store', sanitizers: 'san', guards: 'guard' });
+
+const h16 = (parts) => createHash('sha256').update(JSON.stringify(parts)).digest('hex').slice(0, 16);
+const stripLine = (qid) => String(qid).replace(/@\d+$/, '');
+
+// ---- canonical serialization ------------------------------------------------------------------------------------------------
+
+function canon(v) {
+  if (Array.isArray(v)) return v.map(canon);
+  if (v && typeof v === 'object') return Object.fromEntries(Object.keys(v).sort().map((k) => [k, canon(v[k])]));
+  return v;
+}
+export function serializeGraph(graph) {
+  const g = { ...graph };
+  for (const k of ENTITY_LISTS) g[k] = [...(graph[k] || [])].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return JSON.stringify(canon(g));
+}
+
+// ---- validation -------------------------------------------------------------------------------------------------------------
+
+/** @returns {{ok:boolean, errors:{code:string,path:string,message:string}[]}} Never throws on hostile input. */
+export function validateGraph(g) {
+  const errors = [];
+  const err = (code, path, message) => errors.push({ code, path, message });
+  if (!g || typeof g !== 'object' || Array.isArray(g)) return { ok: false, errors: [{ code: 'NOT_AN_OBJECT', path: '', message: 'a graph is an object' }] };
+  if (g.schema !== SEMANTIC_GRAPH_SCHEMA) { err('SCHEMA_MISMATCH', 'schema', `expected ${SEMANTIC_GRAPH_SCHEMA}`); return { ok: false, errors }; }
+  const m = typeof g.schemaVersion === 'string' ? /^(\d+)\.(\d+)\.(\d+)$/.exec(g.schemaVersion) : null;
+  if (!m) { err('BAD_VERSION', 'schemaVersion', 'must be a semantic version'); return { ok: false, errors }; }
+  if (Number(m[1]) !== SUPPORTED_MAJOR) { err('UNSUPPORTED_MAJOR', 'schemaVersion', `major ${m[1]} is not supported (supported: ${SUPPORTED_MAJOR}); migrate it first`); return { ok: false, errors }; }
+  const ids = new Map();
+  for (const list of ENTITY_LISTS) {
+    if (!Array.isArray(g[list])) { err('MISSING_FIELD', list, 'must be a list (empty when none)'); continue; }
+    g[list].forEach((e, i) => {
+      const p = `${list}[${i}]`;
+      if (!e || typeof e !== 'object' || Array.isArray(e)) { err('BAD_TYPE', p, 'must be an object'); return; }
+      if (typeof e.id !== 'string' || !new RegExp(`^${ID_PREFIX[list]}:[0-9a-f]{16}$`).test(e.id)) err('BAD_ID', `${p}.id`, `must look like ${ID_PREFIX[list]}:<16 hex>`);
+      else if (ids.has(e.id)) err('DUPLICATE_ID', `${p}.id`, `duplicate id ${e.id}`); else ids.set(e.id, list);
+      if (typeof e.file !== 'string' || !e.file || e.file.startsWith('/') || e.file.split('/').includes('..')) err('BAD_TYPE', `${p}.file`, 'must be a repository-relative path');
+      if (!(Number.isInteger(e.line) && e.line >= 0)) err('BAD_TYPE', `${p}.line`, 'line must be a non-negative integer');
+      if (!(e.column === null || (Number.isInteger(e.column) && e.column >= 0))) err('BAD_TYPE', `${p}.column`, 'column must be null or a non-negative integer');
+      if (e.column === null && e.locationPrecision !== 'line') err('RULE_VIOLATION', `${p}.locationPrecision`, "a null column requires locationPrecision 'line'");
+      const c = e.confidence;
+      if (!c || typeof c !== 'object' || !CONFIDENCE_TIERS.includes(c.tier) || typeof c.basis !== 'string' || !c.basis) err('BAD_TYPE', `${p}.confidence`, 'needs { tier, basis }');
+    });
+  }
+  if (errors.length) return { ok: false, errors };
+  const need = (e, p, field, list) => { if (e[field] !== null && e[field] !== undefined && ids.get(e[field]) !== list) err('DANGLING_REF', `${p}.${field}`, `${e[field]} is not a ${list} id`); };
+  g.symbols.forEach((e, i) => { if (!SYMBOL_KINDS.includes(e.kind)) err('UNKNOWN_ENUM', `symbols[${i}].kind`, `unknown symbol kind ${e.kind}`); need(e, `symbols[${i}]`, 'parent', 'symbols'); });
+  g.callSites.forEach((e, i) => { need(e, `callSites[${i}]`, 'caller', 'symbols'); need(e, `callSites[${i}]`, 'callee', 'symbols'); if (e.callee && e.resolution !== 'resolved') err('RULE_VIOLATION', `callSites[${i}].resolution`, 'a call with a callee must be resolved'); if (!e.callee && e.resolution === 'resolved') err('RULE_VIOLATION', `callSites[${i}].resolution`, 'a resolved call needs a callee'); (e.args || []).forEach((a, j) => need(a, `callSites[${i}].args[${j}]`, 'origin', 'valueOrigins')); });
+  g.valueOrigins.forEach((e, i) => { if (!ORIGIN_KINDS.includes(e.kind)) err('UNKNOWN_ENUM', `valueOrigins[${i}].kind`, `unknown origin kind ${e.kind}`); need(e, `valueOrigins[${i}]`, 'symbol', 'symbols'); });
+  g.fieldAccesses.forEach((e, i) => { need(e, `fieldAccesses[${i}]`, 'symbol', 'symbols'); if (!['read', 'write'].includes(e.mode)) err('UNKNOWN_ENUM', `fieldAccesses[${i}].mode`, 'mode must be read or write'); });
+  g.allocations.forEach((e, i) => need(e, `allocations[${i}]`, 'symbol', 'symbols'));
+  if (!g.coverage || typeof g.coverage !== 'object') err('MISSING_FIELD', 'coverage', 'coverage is required');
+  else for (const list of ENTITY_LISTS) { const c = g.coverage[list]; if (!c || !['populated', 'schema-only'].includes(c.state) || !c.reason) err('BAD_TYPE', `coverage.${list}`, 'needs { state, reason }'); else if (c.state === 'schema-only' && g[list].length) err('RULE_VIOLATION', `coverage.${list}`, 'schema-only but not empty'); else if (c.state === 'populated' && !g[list].length) err('RULE_VIOLATION', `coverage.${list}`, 'populated but empty'); }
+  return { ok: errors.length === 0, errors };
+}
+
+/** Parse and validate a serialized graph. Returns { ok, graph?, errors }. */
+export function parseGraph(text) {
+  let g; try { g = JSON.parse(text); } catch (e) { return { ok: false, errors: [{ code: 'BAD_JSON', path: '', message: e.message }] }; }
+  const v = validateGraph(g);
+  return v.ok ? { ok: true, graph: g, errors: [] } : { ok: false, errors: v.errors };
+}
+
+/** Bring an older-minor graph to this version. A different major is refused: there is no silent best-effort. */
+export function migrateGraph(g) {
+  const m = typeof g?.schemaVersion === 'string' ? /^(\d+)\.(\d+)\.(\d+)$/.exec(g.schemaVersion) : null;
+  if (!m || g.schema !== SEMANTIC_GRAPH_SCHEMA) return { ok: false, reason: 'not a semantic graph' };
+  if (Number(m[1]) !== SUPPORTED_MAJOR) return { ok: false, reason: `major ${m[1]} has no migration path to ${SEMANTIC_GRAPH_VERSION}` };
+  return { ok: true, graph: { ...g, schemaVersion: SEMANTIC_GRAPH_VERSION }, migrated: g.schemaVersion !== SEMANTIC_GRAPH_VERSION };
+}
+
+// ---- builder ----------------------------------------------------------------------------------------------------------------
+
+const exprText = (e) => {
+  if (!e || typeof e !== 'object') return '';
+  switch (e.kind) {
+    case 'ident': return e.name;
+    case 'member': return `${exprText(e.object)}.${e.prop ?? '[]'}`;
+    case 'call': return `${exprText(e.callee)}(...)`;
+    case 'literal': return JSON.stringify(e.value);
+    default: return `<${e.kind || 'unknown'}>`;
+  }
+};
+const originKindOf = (e, params) => {
+  if (!e) return 'unknown';
+  if (e.kind === 'ident') return params.includes(e.name) ? 'parameter' : 'identifier';
+  if (e.kind === 'call') return 'call-result';
+  if (e.kind === 'literal') return 'literal';
+  if (e.kind === 'member') return 'member';
+  if (e.kind === 'binary' || e.kind === 'tpl') return 'concat';
+  if (e.kind === 'object') return 'object';
+  if (e.kind === 'array') return 'array';
+  if (e.kind === 'function-value') return 'function';
+  return 'unknown';
+};
+const loc = (file, line) => ({ file, line: Number.isInteger(line) ? line : 0, column: null, locationPrecision: 'line' });
+const OBSERVED = { tier: 'observed', basis: 'read directly from the Layer-1 IR' };
+const UNRESOLVED = { tier: 'unresolved', basis: 'the IR holds no resolved target for this call' };
+
+function memberChain(e) {
+  const path = [];
+  let cur = e;
+  while (cur && cur.kind === 'member') { path.unshift(cur.prop ?? '[]'); cur = cur.object; }
+  return cur && cur.kind === 'ident' ? { base: cur.name, path } : null;
+}
+function walkExprs(e, visit) {
+  if (!e || typeof e !== 'object') return;
+  visit(e);
+  for (const k of ['object', 'callee', 'left', 'right', 'test', 'cons', 'alt']) if (e[k]) walkExprs(e[k], visit);
+  for (const k of ['args', 'parts', 'elements', 'values']) if (Array.isArray(e[k])) e[k].forEach((x) => walkExprs(x, visit));
+  if (Array.isArray(e.props)) e.props.forEach((p) => walkExprs(p?.value ?? p, visit));
+}
+
+/**
+ * @param {{perFile:object, callGraph?:object}} projectIR the object `buildProjectIR` returns
+ * @param {{engineVersion?:string}} [meta]
+ */
+export function buildSemanticGraph(projectIR, meta = {}) {
+  const g = Object.fromEntries(ENTITY_LISTS.map((k) => [k, []]));
+  const ordinal = new Map();
+  const next = (key) => { const n = ordinal.get(key) ?? 0; ordinal.set(key, n + 1); return n; };
+  const symByQid = new Map();
+  const files = Object.keys(projectIR?.perFile || {}).sort();
+
+  // pass 1: symbols
+  for (const file of files) {
+    const pf = projectIR.perFile[file];
+    for (const fn of pf.functions || []) {
+      const isModule = fn.name === '<module>';
+      const key = `${file}|${stripLine(fn.qid)}`;
+      const id = `sym:${h16(['symbol', file, stripLine(fn.qid), next(`sym|${key}`)])}`;
+      symByQid.set(fn.qid, id);
+      g.symbols.push({ id, kind: isModule ? 'module' : 'function', name: fn.name, qid: stripLine(fn.qid), parent: null, params: [...(fn.params || [])], ...loc(file, fn.line), confidence: OBSERVED });
+    }
+  }
+  // function-by-name index for DIRECT same-file resolution only; anything else stays unresolved (cross-file resolution is E2-02)
+  const byFileName = new Map();
+  for (const file of files) for (const fn of projectIR.perFile[file].functions || []) if (fn.name !== '<module>') { const k = `${file}|${fn.name}`; byFileName.set(k, byFileName.has(k) ? null : symByQid.get(fn.qid)); }
+
+  // pass 2: call sites, origins, field accesses, allocations
+  for (const file of files) {
+    for (const fn of projectIR.perFile[file].functions || []) {
+      const symId = symByQid.get(fn.qid);
+      const params = fn.params || [];
+      const originFor = (expr, variable, line) => {
+        const kind = originKindOf(expr, params);
+        const o = { id: `orig:${h16(['origin', symId, variable, kind, exprText(expr), next(`orig|${symId}|${variable}|${kind}|${exprText(expr)}`)])}`, symbol: symId, variable, kind, text: exprText(expr), ...loc(file, line), confidence: kind === 'unknown' ? { tier: 'unresolved', basis: 'the IR could not model this expression' } : OBSERVED };
+        g.valueOrigins.push(o);
+        return o.id;
+      };
+      const field = (expr, mode, line) => {
+        const mc = memberChain(expr);
+        if (!mc || !mc.path.length) return;
+        g.fieldAccesses.push({ id: `field:${h16(['field', symId, mc.base, mc.path, mode, next(`field|${symId}|${mc.base}|${mc.path.join('.')}|${mode}`)])}`, symbol: symId, base: mc.base, path: mc.path, mode, ...loc(file, line), confidence: OBSERVED });
+      };
+      const alloc = (expr, line) => {
+        const kind = expr.kind === 'object' ? 'object' : expr.kind === 'array' ? 'array' : expr.kind === 'function-value' ? 'function' : null;
+        if (!kind) return;
+        g.allocations.push({ id: `alloc:${h16(['alloc', symId, kind, next(`alloc|${symId}|${kind}`)])}`, symbol: symId, kind, ...loc(file, line), confidence: OBSERVED });
+      };
+      for (const c of fn.calls || []) {
+        const calleeText = c.callee;
+        const direct = byFileName.get(`${file}|${calleeText}`) || null;
+        const args = (c.args || []).map((a, index) => { walkExprs(a, (x) => { if (x.kind === 'member') field(x, 'read', c.line); alloc(x, c.line); }); return { index, origin: originFor(a, `arg:${calleeText}:${index}`, c.line) }; });
+        g.callSites.push({ id: `call:${h16(['call', symId, calleeText, next(`call|${symId}|${calleeText}`)])}`, caller: symId, calleeText, callee: direct, resolution: direct ? 'resolved' : 'unresolved', args, ...loc(file, c.line), confidence: direct ? { tier: 'inferred', basis: 'a function of this name exists in the same file' } : UNRESOLVED });
+      }
+      const callFromExpr = (x, line) => {
+        const calleeText = exprText(x.callee).replace(/\(\.\.\.\)$/, '');
+        const direct = x.callee?.kind === 'ident' ? (byFileName.get(`${file}|${calleeText}`) || null) : null;
+        const args = (x.args || []).map((a, index) => ({ index, origin: originFor(a, `arg:${calleeText}:${index}`, line) }));
+        g.callSites.push({ id: `call:${h16(['call', symId, calleeText, next(`call|${symId}|${calleeText}`)])}`, caller: symId, calleeText, callee: direct, resolution: direct ? 'resolved' : 'unresolved', args, ...loc(file, line), confidence: direct ? { tier: 'inferred', basis: 'a function of this name exists in the same file' } : UNRESOLVED });
+      };
+      // The CFG is the one structure every language's IR shares (`writes` exists for JavaScript only): assignment nodes carry { target, source, line }.
+      const assigns = Object.values(fn.cfg?.nodes || {}).filter((n) => n.kind === 'assign' && n.target).sort((x, y) => (x.line ?? 0) - (y.line ?? 0) || String(x.id ?? '').localeCompare(String(y.id ?? '')));
+      for (const d of assigns) {
+        const variable = String(d.target);
+        const line = d.line ?? fn.line;
+        originFor(d.source, variable, line);
+        // calls that appear INSIDE an assignment source (`const cmd = h.build(x)`) are not in fn.calls; they are call sites all the same
+        walkExprs(d.source, (x) => { if (x.kind === 'member') field(x, 'read', line); alloc(x, line); if (x.kind === 'call' && x.callee) callFromExpr(x, line); });
+        const mc = variable.includes('.') ? variable.split('.') : null;
+        if (mc) g.fieldAccesses.push({ id: `field:${h16(['field', symId, mc[0], mc.slice(1), 'write', next(`field|${symId}|${mc[0]}|${mc.slice(1).join('.')}|write`)])}`, symbol: symId, base: mc[0], path: mc.slice(1), mode: 'write', ...loc(file, line), confidence: OBSERVED });
+      }
+    }
+  }
+
+  // E2-07: service relationships are opt-in. A caller that ran dataflow/service-edges.js passes the result as `meta.serviceEdges`; HTTP and
+  // messaging relationships become `serviceBoundaries`, persistence relationships become `storageEdges`, and relationships with no counterpart
+  // are kept as boundaries with `to: null` and unresolved confidence. Without it both lists stay schema-only, as before.
+  const se = meta.serviceEdges && meta.serviceEdges.optedIn ? meta.serviceEdges : null;
+  if (se) {
+    const tier = (e) => (e === 'observed' ? 'observed' : e === 'inferred' ? 'inferred' : 'unresolved');
+    for (const e of se.edges) {
+      const list = e.kind === 'persistence' ? g.storageEdges : g.serviceBoundaries;
+      list.push({ id: `${e.kind === 'persistence' ? 'store' : 'svc'}:${e.id.slice('svcedge:'.length)}`, kind: e.kind, from: e.from, to: e.to, via: e.via, ...loc(e.from.file, e.from.line), evidence: e.evidence, confidence: { tier: tier(e.evidence), basis: e.basis } });
+    }
+    for (const u of se.unknown) g.serviceBoundaries.push({ id: `svc:${h16(['unknown', u.service, u.file, u.kind, u.reason])}`, kind: u.kind, from: { service: u.service, file: u.file, line: u.line }, to: null, via: null, ...loc(u.file, u.line), evidence: 'unknown', confidence: { tier: 'unresolved', basis: u.reason } });
+  }
+  const SCHEMA_ONLY = {
+    ...(se ? {} : { serviceBoundaries: 'opt-in: pass meta.serviceEdges (dataflow/service-edges.js) with two or more declared services; the IR itself carries no service-boundary facts', storageEdges: 'opt-in: pass meta.serviceEdges (dataflow/service-edges.js); the IR itself carries no persistence facts' }),
+    sanitizers: 'sanitizer decisions are made by the dataflow layer (sanitizer-gate.js), not recorded in the IR; they are folded in by E2-08',
+    guards: 'guard dominance is computed by dataflow/guard-dominance.js, not recorded in the IR; it is folded in by E2-08',
+  };
+  const REASON_POP = { serviceBoundaries: 'HTTP and messaging relationships between declared services, and the ones with no counterpart', storageEdges: 'tables one declared service writes and another reads', symbols: 'one per IR function and per file top level', callSites: 'every call recorded in an IR function, plus calls nested inside assignment sources', allocations: 'object, array and function-valued expressions in call arguments and assignments', fieldAccesses: 'member reads in arguments and assignments, and dotted writes', valueOrigins: 'every call argument and every assignment node in the CFG of a function' };
+  const coverage = {};
+  for (const k of ENTITY_LISTS) coverage[k] = SCHEMA_ONLY[k] ? { state: 'schema-only', reason: SCHEMA_ONLY[k] } : g[k].length ? { state: 'populated', reason: REASON_POP[k] } : { state: 'schema-only', reason: `no ${k} in this input` };
+  const limits = [
+    'columns are null: the IR carries line numbers only',
+    'a call resolves only to a same-file function of the same name; imports, re-exports and methods are unresolved until E2-02',
+    'heap, alias and closure facts are not in the IR, so field accesses are syntactic, not points-to results',
+  ];
+  // Dynamic constructs the analysis cannot resolve, per function (E2-03): the graph says where precision was given up, instead of leaving it implicit.
+  const dynamicFeatures = analysisLimits(projectIR).map((l) => ({ symbol: symByQid.get(`${l.qid}@${(projectIR.perFile[l.file].functions.find((f) => stripLine(f.qid) === l.qid) || {}).line}`) ?? null, file: l.file, line: l.line, kind: l.kind, detail: l.detail, effect: l.effect }));
+  return { schema: SEMANTIC_GRAPH_SCHEMA, schemaVersion: SEMANTIC_GRAPH_VERSION, producer: { layer: 'ir-v1', engineVersion: meta.engineVersion ?? null }, ...g, coverage, limits, dynamicFeatures };
+}

package/src/lineage/build-attested-correlation.js

@@ -0,0 +1,63 @@
+// Runtime correlation that knows which build it is talking about (E5-02).
+//
+// `correlateObservations` (observation-correlation.js) is pinned, byte for byte, by its own tests: it answers "was this flow seen in the window" and
+// nothing about WHICH build was seen. This wrapper adds that, without changing it. A caller that names the static snapshot's identity gets back the
+// same correlation, computed over only the observations that could be about that code, plus a statement per flow of whether the evidence is tied to
+// the snapshot's build:
+//
+//   corroborated   every contributing observation matched the snapshot's identity (deployment-identity.js: matched)
+//   unattested     at least one contributing observation carried no comparable identity: seen at runtime, but not shown to be this code
+//   none           no contributing observation
+//
+// Observations from a DIFFERENT build are excluded and listed under `buildMismatchedObservationIds`: they are not evidence about this code at all.
+// A caller that names no snapshot identity gets the original result unchanged.
+import { execFileSync } from 'node:child_process';
+import { correlateObservations } from './observation-correlation.js';
+import { canCorroborate, linkObservationToSnapshot, normalizeIdentity, observationIdentity } from './deployment-identity.js';
+
+const LAYER_RUNTIME_OBSERVED = 'runtime_observed';
+
+/** The identity of the source snapshot at `root`: the git HEAD, whether the work tree is dirty, and anything the caller adds (image digest, build hash, environment). */
+export function snapshotIdentityOf(root, extra = {}) {
+  let commit = null; let dirty = false;
+  try {
+    commit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+    dirty = execFileSync('git', ['status', '--porcelain'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }).trim().length > 0;
+  } catch { commit = null; }
+  return { ...normalizeIdentity({ commit, dirty, ...extra }) };
+}
+
+/**
+ * @param {object} graph
+ * @param {object[]|null|undefined} observations as for correlateObservations
+ * @param {object} opts correlateObservations' options plus
+ *   snapshotIdentity     {commit, buildHash, imageDigest, sbomRef, environment, dirty} of the static snapshot. Without it the original result is returned unchanged.
+ *   observationBuilds    {[observationId]: {commit, buildHash, imageDigest, sbomRef}} identity the importer recorded for an observation
+ */
+export function correlateWithBuild(graph, observations, opts = {}) {
+  const snapshot = opts.snapshotIdentity && typeof opts.snapshotIdentity === 'object' ? normalizeIdentity(opts.snapshotIdentity) : null;
+  if (!snapshot || !Array.isArray(observations)) return correlateObservations(graph, observations, opts);
+  const builds = opts.observationBuilds && typeof opts.observationBuilds === 'object' ? opts.observationBuilds : {};
+  const links = new Map(); const kept = []; const mismatched = [];
+  for (const obs of observations) {
+    const id = obs && typeof obs.id === 'string' ? obs.id : null;
+    const claimed = id && builds[id] ? { ...observationIdentity(obs), ...normalizeIdentity({ ...builds[id], environment: obs.environment }) } : observationIdentity(obs);
+    const link = linkObservationToSnapshot(claimed, snapshot);
+    if (id) links.set(id, link);
+    if (link.state === 'mismatched') { if (id) mismatched.push(id); continue; }
+    kept.push(obs);
+  }
+  const base = correlateObservations(graph, kept, opts);
+  const byFlow = {};
+  for (const [fid, entry] of Object.entries(base.byFlow || {})) {
+    const ids = entry.observationIds || [];
+    const corroboration = entry.layer !== LAYER_RUNTIME_OBSERVED || !ids.length ? 'none' : ids.every((i) => canCorroborate(links.get(i))) ? 'corroborated' : 'unattested';
+    byFlow[fid] = { ...entry, corroboration };
+  }
+  return {
+    ...base, byFlow,
+    buildMismatchedObservationIds: [...new Set(mismatched)].sort(),
+    buildLink: { requested: true, snapshot: { commit: snapshot.commit, buildHash: snapshot.buildHash, imageDigest: snapshot.imageDigest, environment: snapshot.environment, dirty: snapshot.dirty } },
+    limitations: [...(base.limitations || []), 'Observations from a different build were excluded; observations with no comparable build identity are kept but marked unattested, never corroborated.'],
+  };
+}

package/src/lineage/deployment-identity.js

@@ -0,0 +1,76 @@
+// Tying runtime observations to the code that was deployed (E5-02).
+//
+// A runtime observation is evidence about ONE running build. A static finding is evidence about ONE source snapshot. The two are the same subject only
+// when the build is known to have been made from that snapshot. Without that tie, "this route received traffic" says nothing about whether the code
+// that received it contained the finding, and calling it corroboration would be a false claim.
+//
+// WHAT TIES THEM. Four identity fields, compared when both sides have them:
+//   commit       the git commit (a full sha, or a prefix of at least 12 hex characters)
+//   buildHash    a build or reproducibility hash
+//   imageDigest  the container image digest (sha256:...)
+//   sbomRef      an SBOM or artifact reference
+// plus the environment the observation came from, which must equal the environment the snapshot's deployment record names when both are present.
+//
+// THE RULES (each is a test)
+//   mismatched   a field both sides carry DIFFERS, or the environments differ. One disagreement is enough, however many fields agree.
+//   matched      at least one STRONG field (commit, buildHash or imageDigest) is present on both sides and equal, and nothing disagrees
+//   unknown      no strong field is present on both sides: the observation carries no identity, the snapshot carries none, or they carry different kinds
+//   A snapshot with uncommitted changes cannot be tied to a commit: a commit match is downgraded to `unknown` with that reason, because the code that was
+//   scanned is not the code the commit names.
+// Only `matched` may be labelled corroborating. `unknown` is unattested evidence; `mismatched` is excluded and counted.
+export const STRONG_FIELDS = Object.freeze(['commit', 'buildHash', 'imageDigest']);
+export const IDENTITY_FIELDS = Object.freeze(['commit', 'buildHash', 'imageDigest', 'sbomRef']);
+const ATTR = Object.freeze({ commit: 'deployment.commit', buildHash: 'deployment.build', imageDigest: 'deployment.image.digest', sbomRef: 'deployment.sbom.ref' });
+export const IDENTITY_ATTRIBUTE_KEYS = Object.freeze(Object.values(ATTR));
+
+const hex = (s) => (typeof s === 'string' && /^[0-9a-f]{12,64}$/i.test(s) ? s.toLowerCase() : null);
+const digest = (s) => { const m = typeof s === 'string' ? /^(?:sha256:)?([0-9a-f]{64})$/i.exec(s) : null; return m ? `sha256:${m[1].toLowerCase()}` : null; };
+const token = (s) => (typeof s === 'string' && /^[A-Za-z0-9._:-]{1,128}$/.test(s) ? s : null);
+
+/** Normalise an identity-bearing object ({commit, buildHash, imageDigest, sbomRef, environment, dirty}) to comparable values; an unusable value becomes null. */
+export function normalizeIdentity(raw) {
+  const r = raw && typeof raw === 'object' ? raw : {};
+  return { commit: hex(r.commit), buildHash: token(r.buildHash), imageDigest: digest(r.imageDigest), sbomRef: token(r.sbomRef), environment: token(r.environment), dirty: r.dirty === true };
+}
+
+/** The identity an observation carries, from its approved attributes and its environment. */
+export function observationIdentity(obs) {
+  const a = (obs && obs.attributes) || {};
+  return normalizeIdentity({ commit: a[ATTR.commit], buildHash: a[ATTR.buildHash], imageDigest: a[ATTR.imageDigest], sbomRef: a[ATTR.sbomRef], environment: obs && obs.environment });
+}
+
+const sameCommit = (a, b) => { const n = Math.min(a.length, b.length); return n >= 12 && a.slice(0, n) === b.slice(0, n); };
+
+/**
+ * @param {object} observation a runtime observation (or an identity object)
+ * @param {object} snapshot    the static snapshot's identity: {commit, buildHash, imageDigest, sbomRef, environment, dirty}
+ * @returns {{state:'matched'|'mismatched'|'unknown', compared:string[], agreed:string[], disagreed:string[], reasons:string[]}}
+ */
+export function linkObservationToSnapshot(observation, snapshot) {
+  const o = observation && observation.attributes !== undefined ? observationIdentity(observation) : normalizeIdentity(observation);
+  const s = normalizeIdentity(snapshot);
+  const compared = []; const agreed = []; const disagreed = []; const reasons = [];
+  for (const f of IDENTITY_FIELDS) {
+    if (o[f] == null || s[f] == null) continue;
+    compared.push(f);
+    const eq = f === 'commit' ? sameCommit(o[f], s[f]) : o[f] === s[f];
+    (eq ? agreed : disagreed).push(f);
+  }
+  if (o.environment != null && s.environment != null) {
+    compared.push('environment');
+    if (o.environment === s.environment) agreed.push('environment'); else disagreed.push('environment');
+  }
+  if (disagreed.length) return { state: 'mismatched', compared, agreed, disagreed, reasons: disagreed.map((f) => `${f} differs between the observation and the snapshot`) };
+  const strong = agreed.filter((f) => STRONG_FIELDS.includes(f));
+  if (!strong.length) {
+    if (o.commit == null && o.buildHash == null && o.imageDigest == null) reasons.push('the observation carries no commit, build hash or image digest');
+    else if (s.commit == null && s.buildHash == null && s.imageDigest == null) reasons.push('the snapshot carries no commit, build hash or image digest');
+    else reasons.push('the observation and the snapshot carry different kinds of identity, so none can be compared');
+    return { state: 'unknown', compared, agreed, disagreed, reasons };
+  }
+  if (s.dirty && strong.length === 1 && strong[0] === 'commit') return { state: 'unknown', compared, agreed, disagreed, reasons: ['the snapshot has uncommitted changes: the code that was analysed is not the code the commit names'] };
+  return { state: 'matched', compared, agreed, disagreed, reasons: [`${strong.join(', ')} agree and nothing disagrees`] };
+}
+
+/** True only for a link that may be called corroboration. */
+export const canCorroborate = (link) => !!link && link.state === 'matched';

package/src/mcp/tools.js

@@ -28,6 +28,7 @@ import { redactString, redactFinding } from './redact.js';
 import { _remediationOf, normalizeFindings } from '../report/index.js';
 // X-206: the one projection of the verification record, shared with the JSON report, the text report and the autopilot response.
 import { verificationFields } from '../posture/verification/projection.js';
+import { verifyPatch, additiveFields } from '../fix/verify-patch.js';
 import { boundaryFields } from '../lineage/deployment/projection.js';
 // Git-origin provenance (Finding Provenance M0/M1). Distinct from
 // `finding.provenance` (AI-authorship) and from an SCA entry's `provenance`
@@ -879,25 +880,14 @@ export const apply_fix = {
       }
       // Inline re-verify — the load-bearing gate. Must pass to write.
       let verdict;
+      let fixVerification = null;
       try {
         const _files = Object.fromEntries(Object.entries(confinedAbs).map(([rel, v]) => [rel, v.content]));
-        if (process.env.AGENTIC_SECURITY_FIX_RUN_TESTS === '1') {
-          // Addition #7 — connect the closed-loop verifier: add the project test
-          // suite as a fourth verification leg (scan + lint + tests). Opt-in
-          // because many repos have no runner and we must not fail-closed by
-          // default. Normalized to the scan+lint verdict shape used below.
-          const { verifyFixWithTests } = await import('../posture/fix-verify-loop.js');
-          const t = await verifyFixWithTests({ scanRoot: ctx.sessionRoot, originalFindingStableId: f.stableId, files: _files });
-          verdict = { ok: t.ok, summary: t.summary, rescan: t.legs?.scan?.detail, lint: t.legs?.lint?.detail, tests: t.legs?.tests, testVerdict: t.verdict, verificationRecord: t.verificationRecord ?? null };
-        } else {
-          const verifyFixCore = await getVerifyFixCore();
-          verdict = await verifyFixCore({
-            scanRoot: ctx.sessionRoot,
-            originalFindingStableId: f.stableId,
-            files: _files,
-            fixMeta,
-          });
-        }
+        // One verifier for every route (E3-03). AGENTIC_SECURITY_FIX_RUN_TESTS used to swap in a second test runner here; verifyFix
+        // already carries the test leg, so the flag is now inert.
+        const central = await verifyPatch({ scanRoot: ctx.sessionRoot, finding: { id: f.id, stableId: f.stableId }, files: _files, fixMeta, route: 'mcp-apply-fix', mode: dry_run ? 'preview' : 'apply', verify: await getVerifyFixCore() });
+        verdict = central.verdict;
+        fixVerification = central.fixVerification;
       } catch (e) {
         return { _meta: META, applied: false, reason: `patch verification failed: ${e.message}` };
       }
@@ -909,6 +899,7 @@ export const apply_fix = {
           // X-201: the same version-1 verification record every surface emits (additive; null when none could be formed).
           verificationRecord: verdict.verificationRecord ?? null,
           ...verificationFields(verdict.verificationRecord),
+          ...(fixVerification ? additiveFields(fixVerification) : {}),
         };
       }
       // FR-307/FR-1002/D-0024: this caller-supplied-patch branch writes via
@@ -929,7 +920,7 @@ export const apply_fix = {
       }
       const materialClassification = classifyFixMaterialRisk(filesForMaterialClassification);
       if (dry_run) {
-        return { _meta: META, applied: false, dryRun: true, verified: true, files: Object.keys(confinedAbs), summary: verdict.summary, verificationRecord: verdict.verificationRecord ?? null, ...verificationFields(verdict.verificationRecord), materialClassification };
+        return { _meta: META, applied: false, dryRun: true, verified: true, files: Object.keys(confinedAbs), summary: verdict.summary, verificationRecord: verdict.verificationRecord ?? null, ...verificationFields(verdict.verificationRecord), materialClassification, ...(fixVerification ? additiveFields(fixVerification) : {}) };
       }
       const approvalRefusal = _highImpactApprovalRefusal(ctx, materialClassification, fixMeta);
       if (approvalRefusal) return approvalRefusal;
@@ -960,7 +951,7 @@ export const apply_fix = {
       }
       let acceptance = null;
       try { acceptance = fixAcceptanceRate(ctx.sessionRoot); } catch { /* best-effort */ }
-      return { _meta: META, applied: true, verified: true, patched: written, integrity: status, verify: { summary: verdict.summary, verificationRecord: verdict.verificationRecord ?? null, ...verificationFields(verdict.verificationRecord) }, acceptance, materialClassification };
+      return { _meta: META, applied: true, verified: true, patched: written, integrity: status, verify: { summary: verdict.summary, verificationRecord: verdict.verificationRecord ?? null, ...verificationFields(verdict.verificationRecord) }, acceptance, materialClassification, ...(fixVerification ? additiveFields(fixVerification) : {}) };
     }
 
     if (typeof f.fix?.replacement !== 'string') {
@@ -1118,21 +1109,8 @@ export const verify_fix = {
       // Best-effort: a missing/unsigned/tampered scan just means no PoC is
       // available to re-check, not a verify_fix failure — the rescan/lint/
       // tests legs below are independent of this and still apply.
-      let poc = null;
-      try {
-        const { scan: lastScan } = _readLastScanVerified(ctx.sessionRoot, { allowUnsigned: true });
-        const orig = lastScan && (lastScan.findings || []).find(f => f.stableId === stable_id);
-        if (orig && orig.poc && orig.poc.code) poc = { ...orig.poc, finding: orig };
-      } catch { /* best-effort lookup; poc stays null */ }
-
-      const verifyFixCore = await getVerifyFixCore();
-      const r = await verifyFixCore({
-        scanRoot: ctx.sessionRoot,
-        originalFindingStableId: stable_id,
-        files: confined,
-        poc,
-        fixMeta,
-      });
+      const central = await verifyPatch({ scanRoot: ctx.sessionRoot, finding: { stableId: stable_id }, files: confined, fixMeta, route: 'mcp-verify-fix', mode: 'verify', verify: await getVerifyFixCore() });
+      const r = central.verdict;
       return {
         _meta: META,
         ok: r.ok,
@@ -1154,6 +1132,7 @@ export const verify_fix = {
         // `not-run` when no exploit oracle executed against the patch, never a bare pass/fail.
         verificationRecord: r.verificationRecord ?? null,
         ...verificationFields(r.verificationRecord),
+        ...additiveFields(central.fixVerification),
       };
     } catch (e) {
       return { _meta: META, ok: false, reason: `verify_fix failed: ${e.message}` };

package/src/pipeline/canonical-output.js

@@ -0,0 +1,64 @@
+// Canonical scan output (E6-06).
+//
+// A scan result mixes two kinds of fact. Some are about the CODE: which findings exist, where, with what evidence. Those must be identical on every
+// run over the same input, whatever order the files were read in, however many scans ran at once, and whenever it happened. The rest are about the
+// RUN: when it started, how long each stage took, which stage finished first. Those differ every time and are not a defect.
+//
+// This module splits them:
+//   canonical   findings (and the other finding-bearing lists) with volatile fields removed, numbers rounded to a fixed precision, object keys sorted,
+//               lists in a total order (file, line, vuln, stableId, id, then the serialized record as the last tiebreak). Hashed into `digest`.
+//   run         timestamps, durations, telemetry, scan id; kept, separate, and never part of the digest
+//   provenance  what produced the canonical part: scanner version, rule-pack hash, and each source of NONDETERMINISM that was active (a network feed,
+//               a model), named so a reader knows which results could legitimately differ
+//
+// The digest therefore answers one question: did two runs find the same things? A difference in `run` never changes it.
+import { createHash } from 'node:crypto';
+import { computeRulePackHash } from '../posture/deterministic.js';
+
+const LISTS = Object.freeze(['findings', 'secrets', 'logicVulns', 'supplyChain']);
+// fields inside a finding that describe the run, not the code
+const VOLATILE_FINDING_KEYS = new Set(['detectedAt', 'scannedAt', 'ts', 'timestamp', 'elapsedMs', 'durationMs', 'scanId']);
+const PRECISION = 6;
+
+const round = (n) => (Number.isInteger(n) ? n : Math.round(n * 10 ** PRECISION) / 10 ** PRECISION);
+function clean(v) {
+  if (Array.isArray(v)) return v.map(clean);
+  if (v && typeof v === 'object') {
+    const o = {};
+    for (const k of Object.keys(v).sort()) { if (VOLATILE_FINDING_KEYS.has(k) || v[k] === undefined) continue; o[k] = clean(v[k]); }
+    return o;
+  }
+  return typeof v === 'number' && Number.isFinite(v) ? round(v) : v;
+}
+const s = (x) => (x === undefined || x === null ? '' : String(x));
+function order(a, b) {
+  return s(a.file).localeCompare(s(b.file), 'en') || (Number(a.line) || 0) - (Number(b.line) || 0) || s(a.vuln || a.title).localeCompare(s(b.vuln || b.title), 'en')
+    || s(a.stableId).localeCompare(s(b.stableId), 'en') || s(a.id).localeCompare(s(b.id), 'en') || JSON.stringify(a).localeCompare(JSON.stringify(b), 'en');
+}
+
+/** Sources of nondeterminism that are active for this process, named. */
+export function nondeterminismSources(env = process.env) {
+  const out = [];
+  if (env.AGENTIC_SECURITY_LLM_ENDPOINT && env.AGENTIC_SECURITY_LLM_VALIDATE !== '0') out.push({ source: 'llm-validator', reason: 'a model endpoint is configured and the validator is on: its verdicts can differ between runs', model: env.AGENTIC_SECURITY_LLM_MODEL || null });
+  if (env.AGENTIC_SECURITY_DETERMINISTIC !== '1' && env.AGENTIC_SECURITY_OFFLINE !== '1') out.push({ source: 'network-feeds', reason: 'vulnerability and registry feeds are fetched and cached; their content changes over time' });
+  return out;
+}
+
+/**
+ * @param {object} scan a scan result
+ * @param {{env?:object, scannerVersion?:string}} opts
+ * @returns {{canonical:object, digest:string, run:object, provenance:object}}
+ */
+export function canonicalizeScan(scan, opts = {}) {
+  const canonical = {};
+  for (const k of LISTS) if (Array.isArray(scan && scan[k])) canonical[k] = scan[k].map(clean).sort(order);
+  const digest = createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+  const meta = (scan && (scan._scanMeta || scan.meta)) || {};
+  const run = {
+    scanId: meta.scanId ?? null, startedAt: meta.startedAt ?? null, durationMs: meta.durationMs ?? null,
+    telemetry: scan && scan.telemetry ? scan.telemetry : null,
+    fileTimings: Array.isArray(meta.fileTimings) ? meta.fileTimings : null,
+  };
+  const provenance = { scannerVersion: opts.scannerVersion ?? null, rulePackHash: computeRulePackHash(), nondeterminism: nondeterminismSources(opts.env), canonicalPrecision: PRECISION };
+  return { canonical, digest, run, provenance };
+}

package/src/pipeline/detector-runner.js

@@ -41,11 +41,18 @@
  * @param {() => any} fn - the detector call itself, e.g. `() => scanXxx(file, cc)`
  * @returns {any} fn()'s return value, or undefined if it threw
  */
+// E6-01: an optional sink for per-detector timing. Unset (the default), runDetector does exactly what it did before; set by a scan for its duration.
+let _timingSink = null;
+export function setDetectorTimingSink(fn) { _timingSink = typeof fn === 'function' ? fn : null; }
+
 export function runDetector(detectorErrors, file, analyzer, fn) {
+  const t0 = _timingSink ? process.hrtime.bigint() : 0n;
   try {
     return fn();
   } catch (e) {
     detectorErrors.push({ file, analyzer, err: String((e && e.message) || e) });
     return undefined;
+  } finally {
+    if (_timingSink) _timingSink(analyzer, Number(process.hrtime.bigint() - t0) / 1e6);
   }
 }

package/src/pipeline/scan-health.js

@@ -55,12 +55,23 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
   if (filesTimedOut > 0) {
     conditions.push(`${filesTimedOut} file(s) exceeded the per-file analysis timeout`);
   }
+  // A file the engine does not read at all (over the size limit, or too dense to be source: minified or generated) is a file whose problems nobody looked for.
+  // It used to be counted in `files.skipped` and nowhere else, so a scan that read none of a repository's largest files still said `complete`. An empty file is
+  // also counted as skipped, but there is nothing in it to miss, so it is not a condition.
+  const unanalysed = (Number(scanMeta?.filesOversizeSkipped) || 0) + (Number(scanMeta?.filesDenseSkipped) || 0);
+  if (unanalysed > 0) {
+    conditions.push(`${unanalysed} file(s) were not analysed because they are over the size limit or too dense to be source (minified or generated)`);
+  }
   if (engineErrors?.cppDataflowParseErrors > 0) {
     conditions.push(`${engineErrors.cppDataflowParseErrors} C/C++ dataflow parse error(s)`);
   }
   if (deepStatus?.failure) {
     conditions.push(`deep analysis (IR-taint) threw and fell back to pattern-only results: ${deepStatus.failure}`);
   }
+  if (Array.isArray(deepStatus?.incomplete) && deepStatus.incomplete.length) {
+    // E2-05: the deep analysis ran but stopped short somewhere. The result is less complete than it looks, so it is a condition, not a footnote.
+    conditions.push(`deep analysis stopped short (analysis_incomplete): ${deepStatus.incomplete.map((x) => `${x.reason} x${x.count}`).join(', ')}`);
+  }
   if (deepStatus?.requested && !deepStatus.enabled) {
     conditions.push(`deep analysis was requested but did not run: ${deepStatus.reason || 'unknown reason'}`);
   }
@@ -111,6 +122,8 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
       expected: scanMeta?.checkpoint?.total ?? null,
       scanned: scanMeta?.filesScanned ?? null,
       skipped: (Number(scanMeta?.filesSkipped) || 0) + (Number(scanMeta?.filesDenseSkipped) || 0),
+      // skipped files that had something in them to miss: over the size limit, or too dense to be source. Empty files are in `skipped` and not here.
+      unanalysed,
       timedOut: filesTimedOut,
     },
     analyzers: analyzerCoverage || null,
@@ -122,6 +135,7 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
           ciOverrideAllowed: !!deepStatus.ciOverrideAllowed,
           reason: deepStatus.reason ?? null,
           failure: deepStatus.failure ?? null,
+          ...(Array.isArray(deepStatus.incomplete) && deepStatus.incomplete.length ? { incomplete: deepStatus.incomplete } : {}),
         }
       : null,
     lineageAnalysis: lineageStatus