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

package/src/fix/verification-record.js

@@ -0,0 +1,243 @@
+// The patch-level verification record (E3-02): one canonical statement of what was checked about ONE patch, by whichever route produced it.
+//
+// WHY A SECOND RECORD. posture/assurance/verification-record.js records a verdict on a HYPOTHESIS ("this finding is real"): confirmed,
+// refuted, inconclusive. This records what was done to a PATCH ("this change fixes it and breaks nothing"). They are separate axes and the
+// patch record points at the hypothesis it concerns; neither contains the other.
+//
+// HONESTY RULES (enforced by the validator, not by convention)
+//   1. Every check is a leg with one of five statuses: passed, failed, blocked, not_run, not_applicable. `not_run` and `blocked` are never
+//      `passed`, and `not_applicable` carries a reason, so "did not apply" cannot hide "was not checked".
+//   2. `verifiedFull` is DERIVED: true only when every required leg passed and none failed. A record that claims it without that is invalid.
+//      `degradedLegs` lists every required leg that did not pass, with the reason.
+//   3. A leg may only cite evidence that is in the record, and every evidence item is addressed by its digest.
+//   4. `confidence: proven` needs a named policy and evidence; confidence is never inferred from severity.
+//   5. A route that ran fewer checks produces a record with those legs `not_run`; it does not produce a shorter record.
+//
+// Pure: no fs, no clock, no network. The id is content-derived from an allowlist of semantic fields, so timestamps and tool paths cannot
+// change it.
+import {
+  SCHEMA_VERSION, checkCommit, checkDigest, checkEnum, checkFields, checkHeader, checkString, guardObject, isPlainObject, makeCtx, result,
+} from '../posture/assurance/schema-kit.js';
+import { digestOf, semanticId } from '../posture/assurance/identity.js';
+
+export const FIX_VERIFICATION_SCHEMA = 'agentic-security/fix-verification-record';
+export const LEG_STATUSES = Object.freeze(['passed', 'failed', 'blocked', 'not_run', 'not_applicable']);
+export const MODES = Object.freeze(['preview', 'verify', 'apply']);
+export const COMPLETENESS = Object.freeze(['FULL', 'MITIGATION', 'WORKAROUND', 'unverified', 'blocked']);
+export const RESIDUAL_LEVELS = Object.freeze(['none', 'low', 'medium', 'high', 'unknown']);
+export const CONFIDENCE_LEVELS = Object.freeze(['proven', 'inferred', 'unknown']);
+
+// The legs a record carries, in canonical order. Each is a { status, evidenceIds, reason } object.
+export const LEG_NAMES = Object.freeze([
+  'securityBefore', 'securityAfter', 'exploitProofBefore', 'exploitProofAfter', 'newFindingDelta', 'behaviorPreservation',
+  'behaviorTests', 'regressionTests', 'lint', 'typecheck', 'dependencyChecks',
+]);
+
+// What a leg means when it reads `passed`:
+//   securityBefore       the weakness was present on the original code (reproduced or statically established)
+//   securityAfter        the weakness is not present on the patched code
+//   exploitProofBefore   an exploit succeeded against the original code
+//   exploitProofAfter    the same exploit failed against the patched code
+//   newFindingDelta      the patch introduced no new finding of equal or higher severity
+//   behaviorPreservation intended functionality survived (authorised use still works, the sensitive operation is not simply gone)
+//   behaviorTests        the project's tests for the affected scope passed on the PATCHED tree
+//   regressionTests      the wider project tests passed on the patched tree
+//   lint / typecheck     the configured linter / type checker passed on the patched tree
+//   dependencyChecks     dependency manifests and lockfiles are consistent and free of new known advisories
+export const LEG_MEANING = Object.freeze({
+  securityBefore: 'the weakness was present on the original code',
+  securityAfter: 'the weakness is not present on the patched code',
+  exploitProofBefore: 'an exploit succeeded against the original code',
+  exploitProofAfter: 'the same exploit failed against the patched code',
+  newFindingDelta: 'the patch introduced no new finding of equal or higher severity',
+  behaviorPreservation: 'intended functionality survived',
+  behaviorTests: 'the affected-scope tests passed on the patched tree',
+  regressionTests: 'the wider project tests passed on the patched tree',
+  lint: 'the configured linter passed on the patched tree',
+  typecheck: 'the configured type checker passed on the patched tree',
+  dependencyChecks: 'dependency manifests are consistent and carry no new advisory',
+});
+
+const ALLOWED = ['schema', 'schemaVersion', 'id', 'findingId', 'findingStableId', 'hypothesisId', 'mode', 'route', 'preCommit', 'preTreeHash', 'postPatchHash', 'patchHash',
+  'affectedFiles', ...LEG_NAMES, 'requiredLegs', 'coverage', 'degradedLegs', 'verifiedFull', 'fixCompleteness', 'residualRisk', 'confidence', 'tools', 'failures', 'evidence', 'timestamps'];
+const REQUIRED = ['schema', 'schemaVersion', 'id', 'findingId', 'mode', 'route', 'patchHash', 'affectedFiles', ...LEG_NAMES, 'requiredLegs', 'coverage', 'degradedLegs', 'verifiedFull', 'fixCompleteness', 'residualRisk', 'confidence', 'tools', 'failures', 'evidence'];
+
+/** Fields that determine identity. Timestamps, tool paths and evidence locations are deliberately absent. */
+export const FIX_RECORD_ID_FIELDS = Object.freeze(['findingId', 'findingStableId', 'preCommit', 'preTreeHash', 'postPatchHash', 'patchHash', 'affectedFiles', ...LEG_NAMES, 'requiredLegs', 'verifiedFull', 'fixCompleteness']);
+
+export const fixRecordId = (record) => semanticId('fvrec', record, FIX_RECORD_ID_FIELDS);
+
+export const leg = (status, { evidenceIds = [], reason = null } = {}) => ({ status, evidenceIds, reason });
+export const NOT_RUN = (reason) => leg('not_run', { reason });
+
+/** Content-addressed evidence item. `sha256` is the digest of the bytes it stands for (a log, a scan result, a patch). */
+export function evidenceItem({ kind, mediaType = 'text/plain', sha256, uri = null, note = null }) {
+  const body = { kind, mediaType, sha256 };
+  return { id: `ev:${digestOf(body).slice('sha256:'.length, 'sha256:'.length + 16)}`, ...body, ...(uri ? { uri } : {}), ...(note ? { note } : {}) };
+}
+
+/** Required legs that did not pass, as `name: status (reason)`. */
+export function degradedLegsOf(record) {
+  return record.requiredLegs.filter((n) => record[n].status !== 'passed').map((n) => `${n}: ${record[n].status}${record[n].reason ? ` (${record[n].reason})` : ''}`);
+}
+
+/** True only when every required leg passed and no leg failed. Everything else is not a full verification. */
+export function deriveVerifiedFull(record) {
+  if (LEG_NAMES.some((n) => record[n].status === 'failed')) return false;
+  if (record.failures.length) return false;
+  return record.requiredLegs.every((n) => record[n].status === 'passed');
+}
+
+/**
+ * The completeness tier of a verified patch.
+ *   blocked      a required leg is blocked, or a failure was recorded
+ *   unverified   the weakness is not shown to be gone
+ *   FULL         verifiedFull
+ *   MITIGATION   the weakness is gone but a required check did not run, or the exploit leg did not run
+ *   WORKAROUND   supplied by the caller when the route knows the change reduces exposure without removing the cause
+ */
+export function deriveCompleteness(record, { workaround = false } = {}) {
+  if (record.failures.length || record.requiredLegs.some((n) => record[n].status === 'blocked')) return 'blocked';
+  if (record.securityAfter.status !== 'passed') return 'unverified';
+  if (LEG_NAMES.some((n) => record[n].status === 'failed')) return 'unverified';
+  if (workaround) return 'WORKAROUND';
+  return deriveVerifiedFull(record) ? 'FULL' : 'MITIGATION';
+}
+
+// Residual risk after a patch, from what was and was not established (also used by patch-policy.js).
+export function deriveResidualRiskOf(record) {
+  const notes = [...record.degradedLegs];
+  const c = record.fixCompleteness;
+  let level;
+  if (c === 'FULL') level = record.exploitProofAfter.status === 'passed' ? 'low' : 'medium';
+  else if (c === 'MITIGATION') level = 'medium';
+  else if (c === 'WORKAROUND') level = 'high';
+  else level = 'unknown';
+  if (c === 'FULL' && record.exploitProofAfter.status !== 'passed') notes.push('no exploit replay confirmed the weakness is closed');
+  if (c === 'WORKAROUND') notes.push('exposure is reduced but the underlying cause remains');
+  return { level, notes };
+}
+
+export function buildFixVerificationRecord(f) {
+  const legs = {};
+  for (const n of LEG_NAMES) legs[n] = f[n] ? { status: f[n].status, evidenceIds: [...(f[n].evidenceIds || [])], reason: f[n].reason ?? null } : NOT_RUN('the route did not run this check');
+  const required = [...new Set(f.requiredLegs || [])].filter((n) => LEG_NAMES.includes(n)).sort((a, b) => LEG_NAMES.indexOf(a) - LEG_NAMES.indexOf(b));
+  const rec = {
+    schema: FIX_VERIFICATION_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    findingId: f.findingId, ...(f.findingStableId ? { findingStableId: f.findingStableId } : {}), ...(f.hypothesisId ? { hypothesisId: f.hypothesisId } : {}),
+    mode: f.mode, route: f.route,
+    preCommit: f.preCommit ?? null, preTreeHash: f.preTreeHash ?? null, postPatchHash: f.postPatchHash ?? null, patchHash: f.patchHash,
+    affectedFiles: [...new Set(f.affectedFiles || [])].sort(),
+    ...legs,
+    requiredLegs: required,
+    failures: (f.failures || []).map((x) => ({ leg: x.leg, reason: String(x.reason).slice(0, 400) })),
+    evidence: [...(f.evidence || [])].sort((a, b) => (a.id < b.id ? -1 : 1)),
+    residualRisk: f.residualRisk || { level: 'unknown', notes: ['not assessed'] },
+    confidence: f.confidence || { level: 'unknown', policy: null, evidenceIds: [] },
+    tools: f.tools || { engineVersion: null, verifier: 'unspecified' },
+  };
+  rec.verifiedFull = deriveVerifiedFull(rec);
+  rec.degradedLegs = degradedLegsOf(rec);
+  rec.coverage = { required: required.length, passed: required.filter((n) => rec[n].status === 'passed').length, notRun: required.filter((n) => rec[n].status === 'not_run').length, blocked: required.filter((n) => rec[n].status === 'blocked').length, failed: required.filter((n) => rec[n].status === 'failed').length };
+  rec.fixCompleteness = f.fixCompleteness && f.fixCompleteness !== 'derive' ? f.fixCompleteness : deriveCompleteness(rec, { workaround: f.workaround === true });
+  if (f.timestamps) rec.timestamps = f.timestamps;
+  if (!f.residualRisk) rec.residualRisk = deriveResidualRiskOf(rec);
+  rec.id = fixRecordId(rec);
+  return rec;
+}
+
+export function validateFixVerificationRecord(record) {
+  const g = guardObject(record);
+  const ctx = g.ctx;
+  if (!g.ok) return result(ctx);
+  if (!checkHeader(ctx, record, FIX_VERIFICATION_SCHEMA)) return result(ctx);
+  checkFields(ctx, record, ALLOWED, REQUIRED);
+  checkString(ctx, 'findingId', record.findingId);
+  checkString(ctx, 'route', record.route);
+  checkEnum(ctx, 'mode', record.mode, MODES);
+  checkEnum(ctx, 'fixCompleteness', record.fixCompleteness, COMPLETENESS);
+  checkDigest(ctx, 'patchHash', record.patchHash);
+  checkDigest(ctx, 'postPatchHash', record.postPatchHash, { nullable: true });
+  checkDigest(ctx, 'preTreeHash', record.preTreeHash, { nullable: true });
+  checkCommit(ctx, 'preCommit', record.preCommit);
+  if (!Array.isArray(record.affectedFiles) || !record.affectedFiles.length || record.affectedFiles.some((x) => typeof x !== 'string' || !x || x.startsWith('/') || x.split('/').includes('..'))) ctx.err('BAD_TYPE', 'affectedFiles', 'must be a non-empty list of repository-relative paths');
+
+  const evidenceIds = new Set();
+  if (!Array.isArray(record.evidence)) ctx.err('BAD_TYPE', 'evidence', 'must be a list');
+  else record.evidence.forEach((e, i) => {
+    const p = `evidence[${i}]`;
+    if (!isPlainObject(e)) { ctx.err('BAD_TYPE', p, 'must be an object'); return; }
+    for (const k of Object.keys(e)) if (!['id', 'kind', 'mediaType', 'sha256', 'uri', 'note'].includes(k)) ctx.err('UNKNOWN_FIELD', `${p}.${k}`, 'not part of an evidence item');
+    checkString(ctx, `${p}.kind`, e.kind);
+    if (typeof e.sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(e.sha256)) ctx.err('BAD_DIGEST', `${p}.sha256`, 'must be 64 lowercase hex characters');
+    if (typeof e.id !== 'string' || !/^ev:[0-9a-f]{16}$/.test(e.id)) ctx.err('BAD_ID', `${p}.id`, 'must look like ev:<16 hex>');
+    else if (evidenceIds.has(e.id)) ctx.err('DUPLICATE_ID', `${p}.id`, `duplicate evidence id ${e.id}`);
+    else evidenceIds.add(e.id);
+    if (typeof e.uri === 'string' && (/^[a-z]+:\/\/[^/]*@/i.test(e.uri) || /[?&](token|key|secret|password)=/i.test(e.uri))) ctx.err('RULE_VIOLATION', `${p}.uri`, 'an evidence location must not embed credentials');
+  });
+
+  for (const n of LEG_NAMES) {
+    const l = record[n];
+    const p = n;
+    if (!isPlainObject(l)) { ctx.err('BAD_TYPE', p, 'must be a leg object'); continue; }
+    for (const k of Object.keys(l)) if (!['status', 'evidenceIds', 'reason'].includes(k)) ctx.err('UNKNOWN_FIELD', `${p}.${k}`, 'not part of a leg');
+    checkEnum(ctx, `${p}.status`, l.status, LEG_STATUSES);
+    if (!Array.isArray(l.evidenceIds)) ctx.err('BAD_TYPE', `${p}.evidenceIds`, 'must be a list');
+    else for (const id of l.evidenceIds) if (!evidenceIds.has(id)) ctx.err('DANGLING_REF', `${p}.evidenceIds`, `cites ${id}, which is not in evidence`);
+    if (['not_run', 'not_applicable', 'blocked', 'failed'].includes(l.status) && !(typeof l.reason === 'string' && l.reason.trim())) ctx.err('RULE_VIOLATION', `${p}.reason`, `a leg that is ${l.status} must say why`);
+    if (l.status === 'passed' && !l.evidenceIds?.length) ctx.err('RULE_VIOLATION', `${p}.evidenceIds`, 'a leg that passed must cite the evidence of the run');
+  }
+
+  if (!Array.isArray(record.requiredLegs) || record.requiredLegs.some((n) => !LEG_NAMES.includes(n))) ctx.err('BAD_TYPE', 'requiredLegs', 'must list leg names');
+  else {
+    if (new Set(record.requiredLegs).size !== record.requiredLegs.length) ctx.err('DUPLICATE_ID', 'requiredLegs', 'a leg is required once');
+    if (!record.requiredLegs.includes('securityAfter')) ctx.err('RULE_VIOLATION', 'requiredLegs', 'securityAfter is always required: a patch that does not show the weakness gone fixes nothing');
+    for (const n of record.requiredLegs) if (record[n]?.status === 'not_applicable') ctx.err('RULE_VIOLATION', n, 'a required leg cannot be not_applicable; drop it from requiredLegs with a reason on the leg instead');
+  }
+  if (!Array.isArray(record.failures)) ctx.err('BAD_TYPE', 'failures', 'must be a list');
+
+  if (record.requiredLegs && Array.isArray(record.failures) && LEG_NAMES.every((n) => isPlainObject(record[n]))) {
+    const expectFull = deriveVerifiedFull(record);
+    if (record.verifiedFull !== expectFull) ctx.err('RULE_VIOLATION', 'verifiedFull', `verifiedFull is ${record.verifiedFull} but the legs imply ${expectFull}`);
+    const expectDegraded = degradedLegsOf(record);
+    if (JSON.stringify(record.degradedLegs) !== JSON.stringify(expectDegraded)) ctx.err('RULE_VIOLATION', 'degradedLegs', 'does not list exactly the required legs that did not pass');
+    if (record.fixCompleteness === 'FULL' && !expectFull) ctx.err('RULE_VIOLATION', 'fixCompleteness', 'FULL requires verifiedFull');
+    if (record.fixCompleteness === 'FULL' && record.securityAfter.status !== 'passed') ctx.err('RULE_VIOLATION', 'fixCompleteness', 'FULL requires securityAfter to have passed');
+    if (['FULL', 'MITIGATION', 'WORKAROUND'].includes(record.fixCompleteness) && record.securityAfter.status !== 'passed') ctx.err('RULE_VIOLATION', 'fixCompleteness', `${record.fixCompleteness} requires securityAfter to have passed`);
+    if (record.fixCompleteness !== 'blocked' && record.requiredLegs.some((n) => record[n].status === 'blocked')) ctx.err('RULE_VIOLATION', 'fixCompleteness', 'a blocked required leg makes the completeness blocked');
+    if (!isPlainObject(record.coverage)) ctx.err('BAD_TYPE', 'coverage', 'must be an object');
+  }
+
+  const rr = record.residualRisk;
+  if (!isPlainObject(rr)) ctx.err('BAD_TYPE', 'residualRisk', 'must be an object');
+  else { checkEnum(ctx, 'residualRisk.level', rr.level, RESIDUAL_LEVELS); if (!Array.isArray(rr.notes)) ctx.err('BAD_TYPE', 'residualRisk.notes', 'must be a list'); }
+  const c = record.confidence;
+  if (!isPlainObject(c)) ctx.err('BAD_TYPE', 'confidence', 'must be an object');
+  else {
+    checkEnum(ctx, 'confidence.level', c.level, CONFIDENCE_LEVELS);
+    if (c.level === 'proven') {
+      if (!(typeof c.policy === 'string' && c.policy)) ctx.err('RULE_VIOLATION', 'confidence.policy', 'proven confidence needs a named proof policy');
+      if (!Array.isArray(c.evidenceIds) || !c.evidenceIds.length) ctx.err('RULE_VIOLATION', 'confidence.evidenceIds', 'proven confidence needs evidence');
+      else for (const id of c.evidenceIds) if (!evidenceIds.has(id)) ctx.err('DANGLING_REF', 'confidence.evidenceIds', `cites ${id}, which is not in evidence`);
+      if (record.exploitProofAfter?.status !== 'passed') ctx.err('RULE_VIOLATION', 'confidence.level', 'proven requires the exploit replay leg to have passed against the patched code');
+    }
+  }
+  if (!isPlainObject(record.tools)) ctx.err('BAD_TYPE', 'tools', 'must be an object');
+  if (typeof record.id === 'string' && LEG_NAMES.every((n) => isPlainObject(record[n])) && Array.isArray(record.affectedFiles) && Array.isArray(record.requiredLegs)) {
+    const want = fixRecordId(record);
+    if (record.id !== want) ctx.err('ID_MISMATCH', 'id', `id does not follow from the record's content (expected ${want})`);
+  }
+  return result(ctx);
+}
+
+/** The shape every pre-existing consumer reads: ok, verified, verifiedFull, degradedLegs. Additive fields are not included. */
+export function legacyViewOf(record) {
+  const failedAny = LEG_NAMES.some((n) => record[n].status === 'failed') || record.failures.length > 0;
+  return {
+    ok: !failedAny && record.securityAfter.status === 'passed',
+    verified: !failedAny && record.securityAfter.status === 'passed',
+    verifiedFull: record.verifiedFull,
+    degradedLegs: [...record.degradedLegs],
+    completeness: record.fixCompleteness,
+  };
+}

package/src/fix/verify-patch.js

@@ -0,0 +1,89 @@
+// The one verifier every patch route calls (E3-03).
+//
+// Routes used to call verifyFix themselves, with different inputs (only verify_fix looked up the exploit PoC; one branch swapped the
+// verifier when an env flag was set), and each shaped the result its own way. verifyPatch runs verifyFix ONCE with one set of inputs and
+// returns the raw verdict beside the canonical patch-level record, so identical patch and settings give the same record id on every route.
+//
+// Route and mode are NOT part of the record id (see FIX_RECORD_ID_FIELDS): they say who asked, not what was established.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { verifyFix } from '../posture/fix-verify.js';
+import { verifyLastScan } from '../posture/integrity.js';
+import { stateDir } from '../posture/state-dir.js';
+import { recordFromVerifyFix } from './verification-adapters.js';
+import { replayExploit } from './exploit-replay.js';
+import { checkFootprint } from './footprint.js';
+import { checkSecretPersistence } from './secret-persistence.js';
+import { runTestsOnPatchedCopy } from './test-commands.js';
+import { legacyViewOf } from './verification-record.js';
+
+const REQUIRED_LEGS = Object.freeze(['securityAfter', 'newFindingDelta', 'behaviorPreservation', 'behaviorTests']);
+
+function readOriginal(scanRoot) {
+  return (rel) => { try { return fs.readFileSync(path.join(scanRoot, rel), 'utf8'); } catch { return null; } };
+}
+
+/** The scan, only when its signature verifies: a stored PoC is code that will be run, so an unsigned scan supplies none. */
+function readSignedScan(scanRoot) {
+  const file = path.join(stateDir(scanRoot), 'last-scan.json');
+  const body = fs.readFileSync(file, 'utf8');
+  return verifyLastScan(body, `${file}.sig`) === true ? JSON.parse(body) : null;
+}
+
+function lookupFinding(scanRoot, stableId, readScan) {
+  try {
+    const scan = (readScan || readSignedScan)(scanRoot);
+    return (scan?.findings || []).find((f) => f.stableId === stableId) || null;
+  } catch { return null; }
+}
+
+/**
+ * @param {{scanRoot:string, finding:{id?:string,stableId:string}, files:Record<string,string>, route:string, mode?:'preview'|'verify'|'apply',
+ *   fixMeta?:object, poc?:object|null, readScan?:(root:string)=>object|null, verify?:Function, extra?:object}} o
+ * @returns {Promise<{verdict:object, fixVerification:object, canonical:object}>}
+ */
+export async function verifyPatch(o) {
+  const { scanRoot, finding, files, route, mode = 'verify', fixMeta, readScan, extra } = o;
+  const run = o.verify || verifyFix;
+  const stored = lookupFinding(scanRoot, finding.stableId, readScan);
+  // One PoC rule for every route: the stored one for this finding, unless the caller supplied its own.
+  const poc = o.poc !== undefined ? o.poc : (stored?.poc?.code ? { ...stored.poc, finding: stored } : null);
+  // An explicit local reproducer turns the replay on for every route alike; without one the leg is not_run and says so.
+  const replay = o.reproducer ? await replayExploit({ scanRoot, reproducer: o.reproducer, files, attempts: o.replayAttempts, timeoutMs: o.replayTimeoutMs, attemptFn: o.attemptFn }) : null;
+  // The tests run on a copy WITH the patch applied. A suite that was already red says nothing about the patch, so it is reported as such.
+  const runTests = () => {
+    const t = runTestsOnPatchedCopy({ scanRoot, files, command: o.testCommand || fixMeta?.testCommand, timeoutMs: o.testTimeoutMs });
+    return t.preExistingFailure ? { ...t, status: 'skipped', passed: null, skipped: true, reason: 'suite-already-failing-before-the-patch' } : t;
+  };
+  const read = readOriginal(scanRoot);
+  const footprint = checkFootprint({ before: Object.fromEntries(Object.keys(files).map((r) => [r, read(r)])), after: files, cwe: stored?.cwe || o.cwe || null, intentionalRemoval: fixMeta?.intentionalRemoval || null });
+  // A secret finding is only fixed when the secret is gone from the source, not when it was re-encoded.
+  const isSecret = /CWE-(798|259|321|312)/i.test(String(stored?.cwe || o.cwe || ''));
+  const persistence = isSecret && stored?.file && files[stored.file] !== undefined ? checkSecretPersistence({ before: read(stored.file), after: files[stored.file], line: stored.line }) : null;
+  let verdict = await run({ scanRoot, originalFindingStableId: finding.stableId, files, fixMeta, runTests, ...(poc ? { poc } : {}), ...(extra || {}) });
+  // The finding disappearing is not enough: a patch that removed the feature is rejected here, for every route at once.
+  if (persistence?.status === 'failed' && verdict.ok) verdict = { ...verdict, ok: false, rejectedBy: 'secret-persists', summary: `${persistence.reason}\n${verdict.summary || ''}`.trim() };
+  if (footprint.status === 'failed' && verdict.ok) verdict = { ...verdict, ok: false, rejectedBy: 'behavior-preservation', summary: `${footprint.reason}\n${verdict.summary || ''}`.trim() };
+  const fixVerification = recordFromVerifyFix(verdict, {
+    finding: { id: finding.id ?? stored?.id ?? finding.stableId, stableId: finding.stableId },
+    files, route, mode, findingPresent: !!(stored || finding.present), preFiles: readOriginal(scanRoot),
+    requiredLegs: replay ? [...REQUIRED_LEGS, 'exploitProofAfter'] : REQUIRED_LEGS, replay, footprint, persistence,
+  });
+  const canonical = legacyViewOf(fixVerification);
+  // The record is the authority: a failed leg (a surviving exploit, tests that fail on the patched tree) rejects the patch on every route.
+  if (!canonical.ok && verdict.ok) {
+    const failed = ['securityAfter', 'exploitProofAfter', 'newFindingDelta', 'behaviorTests', 'behaviorPreservation', 'lint'].filter((n) => fixVerification[n].status === 'failed');
+    verdict = { ...verdict, ok: false, rejectedBy: verdict.rejectedBy || `leg:${failed[0] || 'failed'}`, summary: `${failed.map((n) => `${n}: ${fixVerification[n].reason}`).join('; ') || 'a verification leg failed'}\n${verdict.summary || ''}`.trim() };
+  }
+  return { verdict, fixVerification, canonical, replay, footprint, persistence };
+}
+
+/** The additive fields every route puts on its result. Existing fields are untouched. */
+export function additiveFields(fixVerification) {
+  return {
+    fixVerification,
+    fixCompleteness: fixVerification.fixCompleteness,
+    verifiedFull: fixVerification.verifiedFull,
+    degradedLegs: fixVerification.degradedLegs,
+  };
+}

package/src/ir/CLAUDE.md

@@ -266,3 +266,8 @@ down enterprise runners sometimes don't. Targets for retirement:
   every fallback to the regex parser is now also a silent loss of Python
   interprocedural analysis, not just the older, vaguer "some constructs get
   dropped" cost.
+
+## Semantic graph (`semantic-graph.js`, engineering-excellence E2-01)
+
+An additive, typed, versioned view over this IR: `Symbol`, `CallSite`, `Allocation`, `FieldAccess`, `ValueOrigin`, plus the schema-only lists `ServiceBoundary`, `StorageEdge`, `Sanitizer`, `Guard`. Ids are content-derived and never include a line, so a blank line above a function moves no id. It reads the CFG (the one structure every language's IR shares; `writes` exists for JavaScript only). Nothing on the scan path imports it, so findings and `chain[]` cannot change; a test pins that. Columns are `null` (the IR has lines only) and say `locationPrecision: "line"`. Contract and the measured per-language construct matrix: `docs/engineering-excellence/IR_CONTRACT.md` (regenerate with `node scripts/engineering-excellence/ir-matrix.mjs`). Do not add a `site` field: IR site ids come from a process-global counter and are not stable across builds.
+

package/src/ir/callgraph.js

@@ -28,6 +28,8 @@ export function functionRecord(callGraph, resolved) {
   return fns.get(resolved) || null;
 }
 
+import { buildModuleIndex } from './module-resolver.js';
+
 export function buildCallGraph(perFileIR, fileContents) {
   const functions = new Map();
   const byNameInFile = new Map();
@@ -186,11 +188,26 @@ export function buildCallGraph(perFileIR, fileContents) {
     return null;
   }
 
+  // E2-02: import-aware resolution. A call whose head identifier is an import binding is resolved by following the program's own
+  // import/export statements (exact, bounded, cycle-safe). It never throws: a failure to build the index leaves the older name-based
+  // resolution exactly as it was.
+  let moduleIndex = null;
+  if (fileContents) { try { moduleIndex = buildModuleIndex(fileContents, perFileIR); } catch { moduleIndex = null; } }
+  const viaImport = (callerFile, name) => {
+    if (!moduleIndex || !callerFile) return null;
+    try { return moduleIndex.resolveCall(callerFile, name); } catch { return null; }
+  };
+
   // Resolve each call site.
   const edges = []; // { caller, site, callee, ambiguous? }
   for (const fn of functions.values()) {
     for (const c of (fn.calls || [])) {
       if (!c.callee) { edges.push({ caller: fn.qid, site: c.site, callee: null, line: c.line }); continue; }
+      // 0. Import binding (E2-02): explicit evidence beats every name-based rule below. A binding to an external package or builtin resolves
+      // to nothing, so a same-named function elsewhere in the project can no longer be taken for it.
+      const imp = viaImport(fn.file, c.callee);
+      if (imp && imp.status === 'resolved') { edges.push({ caller: fn.qid, site: c.site, callee: imp.qid, calleeName: c.callee, line: c.line, via: 'import', hops: imp.hops }); continue; }
+      if (imp && imp.status === 'external') { edges.push({ caller: fn.qid, site: c.site, callee: null, calleeName: c.callee, line: c.line, external: true }); continue; }
       // 1. Direct name in same file
       const sameFileMap = byNameInFile.get(fn.file);
       const resolved = sameFileMap?.get(c.callee) ||
@@ -284,6 +301,11 @@ export function buildCallGraph(perFileIR, fileContents) {
   // because the guard lived only in that one file's helper instead of here).
   function _resolveImpl(name, callerFile, allowTailGuess) {
     if (!name || typeof name !== 'string') return null;
+    {
+      const imp = viaImport(callerFile, name);
+      if (imp && imp.status === 'resolved') return imp.qid;
+      if (imp && imp.status === 'external') return null;
+    }
     // Roadmap #3: same-file preference. A bare name (`handler`, `save`,
     // `query`) defined in several files would otherwise resolve to whichever
     // file Map is iterated first, mis-targeting interprocedural taint to a
@@ -363,5 +385,5 @@ export function buildCallGraph(perFileIR, fileContents) {
   function resolveKnownCallee(name, callerFile) {
     return _resolveImpl(name, callerFile, false);
   }
-  return { functions, edges, callersOf, resolve, resolveKnownCallee };
+  return { functions, edges, callersOf, resolve, resolveKnownCallee, moduleIndex };
 }