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

package/src/fix/footprint.js

@@ -0,0 +1,65 @@
+// Functional footprint of a patch (E3-05): did the patch fix the weakness, or remove the feature?
+//
+// A rescan only proves the finding stopped firing. A patch that deletes the vulnerable behaviour (a blanket 403 on an IDOR route, a 501 on
+// the SQL endpoint, an emptied file) satisfies that just as well, so it is checked separately: the kinds of sensitive operation the
+// changed files performed BEFORE the patch must still be performed AFTER it. A parameterised query is still a database read; an
+// execFile call is still a process execution; a deny-all handler is neither.
+//
+// This is a HEURISTIC over source text, not a proof of equivalence. It catches the removal of a whole operation kind, not a subtler
+// behaviour change. When it cannot see any operation kind in the original it says `unobservable` and the leg is not_run, never passed.
+const KINDS = {
+  'process-exec': /require\s*\(\s*['"](?:node:)?child_process['"]\s*\)|from\s+['"](?:node:)?child_process['"]|\b(?:execSync|execFileSync|execFile|spawnSync|spawn|exec|system|popen|Runtime\s*\.\s*getRuntime\s*\(\s*\)\s*\.\s*exec|ProcessBuilder|subprocess\s*\.\s*\w+|os\s*\.\s*system|shell_exec|passthru|proc_open)\s*\(/,
+  'data-access': /\b(?:SELECT|INSERT\s+INTO|UPDATE|DELETE\s+FROM)\b|\.(?:find|findOne|findById|findAll|findUnique|findFirst|query|execute|executeQuery|executemany|prepare|raw|where|get_object_or_404|createQuery|queryForObject)\s*\(|\b(?:db|database|conn|connection|pool|cursor|collection|repository|repo|prisma|knex|sequelize|session)\w*\s*\.\s*\w+\s*\(/i,
+  'file-access': /\b(?:readFile|readFileSync|createReadStream|writeFile|writeFileSync|createWriteStream|sendFile|readdir|readdirSync|unlink|open|os\.Open|ioutil\.ReadFile|file_get_contents|File\s*\(|FileInputStream|FileReader|Files\s*\.\s*\w+)\s*\(/,
+  'network-out': /\b(?:fetch|axios|got|request|urlopen|requests\s*\.\s*\w+|http\s*\.\s*(?:get|request)|https\s*\.\s*(?:get|request)|HttpClient|http\.Get|curl_exec)\s*\(/,
+  'html-output': /\b(?:res|response|reply|ctx)\b[^;\n]*\.\s*(?:send|write|render|json|end)\s*\(|\b(?:render_template|HttpResponse|JsonResponse|jsonify|innerHTML|echo|ResponseEntity|c\.JSON|c\.String)\b/,
+};
+const DENIAL = /\b(?:status\s*\(\s*(?:401|403|404|405|410|501|503)\s*\)|(?:abort|HTTPException|http_error|ResponseStatusException)\s*\(\s*(?:401|403|404|501)|(?:PermissionDenied|Forbidden|NotImplemented|AccessDenied|Unauthorized)\b|(?:forbidden|not implemented|access denied|disabled)\b|return\s+(?:403|401|501)\b|StatusForbidden|StatusNotImplemented)/i;
+// Which kinds a CWE's fix must keep. Unlisted weaknesses are held to every kind the original had.
+const CWE_KINDS = {
+  'CWE-78': ['process-exec'], 'CWE-77': ['process-exec'], 'CWE-89': ['data-access'], 'CWE-564': ['data-access'], 'CWE-22': ['file-access'], 'CWE-73': ['file-access'],
+  'CWE-918': ['network-out'], 'CWE-79': ['html-output'], 'CWE-639': ['data-access'], 'CWE-284': ['data-access'], 'CWE-285': ['data-access'], 'CWE-862': ['data-access'], 'CWE-863': ['data-access'], 'CWE-566': ['data-access'],
+};
+
+const stripComments = (t) => String(t || '').replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:\\])\/\/[^\n]*/g, '$1').replace(/(^|\s)#[^\n!][^\n]*/g, '$1');
+const codeLines = (t) => stripComments(t).split('\n').filter((l) => l.trim() && !/^\s*[{}();,]*\s*$/.test(l)).length;
+
+export function kindsOf(text) {
+  const src = stripComments(text);
+  return Object.entries(KINDS).filter(([, re]) => re.test(src)).map(([k]) => k).sort();
+}
+
+/**
+ * @param {{before:Record<string,string|null>, after:Record<string,string>, cwe?:string|null, intentionalRemoval?:{reason:string}|null}} o
+ * @returns {{status:'passed'|'failed'|'not_run', reason:string|null, files:object[], lost:string[]}}
+ */
+export function checkFootprint({ before, after, cwe = null, intentionalRemoval = null }) {
+  const required = CWE_KINDS[String(cwe || '').toUpperCase()] || null;
+  const files = [];
+  const lostAll = new Set();
+  let observed = false;
+  for (const [rel, afterText] of Object.entries(after)) {
+    const b = before[rel];
+    if (b === null || b === undefined) { files.push({ file: rel, note: 'new file' }); continue; }
+    const kb = kindsOf(b); const ka = kindsOf(afterText);
+    const held = required ? kb.filter((k) => required.includes(k)) : kb;
+    if (held.length) observed = true;
+    let lost = held.filter((k) => !ka.includes(k));
+    const emptied = codeLines(afterText) === 0 && codeLines(b) > 0;
+    const denialOnly = lost.length > 0 && DENIAL.test(stripComments(afterText)) && !DENIAL.test(stripComments(b));
+    // With no known weakness class, losing an operation kind is not by itself a defect (an auth fix may legitimately drop a response path).
+    // What marks feature REMOVAL is the signature of it: the file emptied, or the lost operation replaced by a deny response.
+    if (!required && !emptied && !denialOnly) lost = [];
+    const shrunk = codeLines(b) >= 6 && codeLines(afterText) <= Math.floor(codeLines(b) * 0.25);
+    files.push({ file: rel, kindsBefore: kb, kindsAfter: ka, lost, emptied, denialOnly, shrunk });
+    if (emptied) { lost.push('everything'); observed = true; }
+    for (const k of lost) lostAll.add(k);
+  }
+  if (!observed && ![...lostAll].length) return { status: 'not_run', reason: 'unobservable: no sensitive operation was recognised in the original files, so removal of the feature cannot be judged', files, lost: [] };
+  if (lostAll.size) {
+    if (intentionalRemoval && typeof intentionalRemoval.reason === 'string' && intentionalRemoval.reason.trim()) return { status: 'not_run', reason: `the patch removes ${[...lostAll].join(', ')} and the caller declared that intentional (${intentionalRemoval.reason.trim().slice(0, 200)}); a person must confirm it`, files, lost: [...lostAll] };
+    const why = files.filter((f) => f.lost?.length).map((f) => `${f.file}: no longer performs ${f.lost.join(', ')}${f.denialOnly ? ' (replaced by a deny response)' : ''}${f.emptied ? ' (file emptied)' : ''}`).join('; ');
+    return { status: 'failed', reason: `the patch removes functionality instead of fixing it: ${why}`, files, lost: [...lostAll] };
+  }
+  return { status: 'passed', reason: null, files, lost: [] };
+}

package/src/fix/patch-policy.js

@@ -0,0 +1,49 @@
+// Risk-tiered patch policy (E3-06): given a verified-patch record, may it be applied without a person, proposed for a person, or refused?
+//
+// Two modes. `requested` is a person (or an agent acting for one) who asked for the write: it proceeds on any tier that is not
+// unverified or blocked, and the result carries the degraded legs as warnings so nothing about the pass is hidden. `automatic` is
+// anything that would write with nobody asking: it is OFF unless the policy enables it, and even then it applies only a configured
+// low-risk patch whose every REQUIRED check passed. Absent tests, a replay that did not run, an unobservable footprint, or any other
+// degraded leg make an automatic write a proposal, never a silent write. Preview and undo are never removed by this module.
+//
+// Pure: no fs, no clock.
+const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+const AUTH_CATEGORIES = /auth|crypto|permission|access|privilege|session|tenant/i;
+
+export const DEFAULT_POLICY = Object.freeze({
+  automatic: Object.freeze({ enabled: false, maxSeverity: 'medium', allowedMaterialRisk: Object.freeze(['low']), requireExploitProof: false, maxResidualRisk: 'low' }),
+});
+const RESIDUAL_RANK = { none: 0, low: 1, medium: 2, high: 3, unknown: 4 };
+
+export { deriveResidualRiskOf as deriveResidualRisk } from './verification-record.js';
+
+const decide = (decision, record, reasons, extra = {}) => ({ decision, tier: record.fixCompleteness, verifiedFull: record.verifiedFull, residualRisk: record.residualRisk, reasons, warnings: record.degradedLegs, preview: true, undo: true, ...extra });
+
+/**
+ * @param {{record:object, finding?:{severity?:string}, materialClassification?:{highImpactCategories?:string[], risk?:string}, mode?:'requested'|'automatic', policy?:object}} o
+ */
+export function decidePatchApplication({ record, finding = {}, materialClassification = {}, mode = 'requested', policy = DEFAULT_POLICY }) {
+  const tier = record.fixCompleteness;
+  if (tier === 'blocked') return decide('refuse', record, ['a required check was blocked or a failure was recorded, so the patch cannot be applied']);
+  if (tier === 'unverified') return decide('refuse', record, ['the weakness is not shown to be gone, or a check failed']);
+  if (mode === 'requested') return decide('apply', record, [`${tier}: applied at the request of a person`]);
+
+  const a = { ...DEFAULT_POLICY.automatic, ...(policy?.automatic || {}) };
+  if (!a.enabled) return decide('propose', record, ['automatic application is not enabled by policy; the patch is proposed for a person to apply']);
+  const reasons = [];
+  if (tier !== 'FULL') reasons.push(`completeness is ${tier}, automatic application needs FULL`);
+  if (!record.verifiedFull) reasons.push('not every required check passed');
+  for (const d of record.degradedLegs) reasons.push(`degraded: ${d}`);
+  if (a.requireExploitProof && record.exploitProofAfter.status !== 'passed') reasons.push('policy requires an exploit replay and none confirmed the fix');
+  for (const leg of ['behaviorTests', 'behaviorPreservation']) if (record[leg].status !== 'passed') reasons.push(`${leg} did not pass (${record[leg].status})`);
+  const sev = SEVERITY_RANK[String(finding.severity || '').toLowerCase()];
+  if (sev === undefined) reasons.push('the finding severity is unknown');
+  else if (sev > SEVERITY_RANK[a.maxSeverity]) reasons.push(`severity ${finding.severity} is above the automatic limit (${a.maxSeverity})`);
+  const cats = materialClassification.highImpactCategories || [];
+  if (cats.length) reasons.push(`high-impact change (${cats.join(', ')}) needs a person`);
+  if (cats.some((c) => AUTH_CATEGORIES.test(c))) reasons.push('the change alters authentication, authorization or cryptography');
+  if (materialClassification.risk && !a.allowedMaterialRisk.includes(materialClassification.risk)) reasons.push(`material risk ${materialClassification.risk} is not in the allowed set`);
+  if ((RESIDUAL_RANK[record.residualRisk.level] ?? 4) > RESIDUAL_RANK[a.maxResidualRisk]) reasons.push(`residual risk ${record.residualRisk.level} is above ${a.maxResidualRisk}`);
+  if (reasons.length) return decide('propose', record, reasons);
+  return decide('apply', record, ['FULL, low risk, every required check passed']);
+}

package/src/fix/secret-persistence.js

@@ -0,0 +1,39 @@
+// Did the patch REMOVE a hard-coded secret, or only change how it is written? (E3-08)
+//
+// Moving `const k = 'abc123...'` to `const k = atob('YWJjMTIz...')`, splitting it in two literals, reversing it or hex-encoding it all
+// make a pattern-based scanner stop seeing a secret that is still in the source. This looks for the original literal after the patch in
+// the forms a lazy "fix" uses. It cannot catch encryption with a key kept next to it or other transformations; it says what it checked.
+const MIN_LEN = 8;
+
+const literalsOnLines = (text, lines) => {
+  const out = new Set();
+  const all = String(text).split('\n');
+  for (const n of lines) {
+    const l = all[n - 1];
+    if (!l) continue;
+    for (const m of l.matchAll(/(["'`])((?:\\.|(?!\1).){8,})\1/g)) out.add(m[2]);
+  }
+  return [...out].filter((s) => s.length >= MIN_LEN);
+};
+const squash = (t) => String(t).replace(/["'`+\s]/g, '');
+const forms = (v) => {
+  const b64 = Buffer.from(v).toString('base64');
+  return [v, [...v].reverse().join(''), Buffer.from(v).toString('hex'), b64, b64.replace(/=+$/, ''), encodeURIComponent(v)].filter((x) => x.length >= MIN_LEN);
+};
+
+/**
+ * @param {{before:string, after:string, line:number|null}} o
+ * @returns {{status:'passed'|'failed'|'not_run', reason:string|null, checked:number}}
+ */
+export function checkSecretPersistence({ before, after, line }) {
+  if (!Number.isInteger(line) || line < 1) return { status: 'not_run', reason: 'the finding has no line, so the secret literal cannot be located', checked: 0 };
+  const lits = literalsOnLines(before, [line - 1, line, line + 1].filter((n) => n >= 1));
+  if (!lits.length) return { status: 'not_run', reason: 'no string literal of 8 or more characters near the finding line', checked: 0 };
+  const flat = squash(after);
+  for (const lit of lits) {
+    for (const f of forms(lit)) {
+      if (String(after).includes(f) || flat.includes(squash(f))) return { status: 'failed', reason: `the secret is still in the source (${f === lit ? 'unchanged' : 'as a re-encoded or split form'}); moving or encoding it does not remove it`, checked: lits.length };
+    }
+  }
+  return { status: 'passed', reason: null, checked: lits.length };
+}

package/src/fix/test-commands.js

@@ -0,0 +1,84 @@
+// Run the project's tests against the PATCHED tree, in a throwaway copy (E3-05).
+//
+// verifyFix used to run the tests on the tree as it was before the patch was written, which says nothing about the patch. Here the
+// patch is overlaid on a copy and the tests run there; the real tree is never touched.
+//
+// Runner discovery covers what the existing detector does (npm/pnpm/yarn/bun scripts, pytest, go test) plus cargo, dotnet, maven,
+// gradle and rspec, and an explicit argv from the caller (`command`) which always wins. Commands are argv arrays, never a shell string.
+// When the patched run fails the pristine copy is run too, so "the suite was already red" is not mistaken for "the patch broke it".
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { detectTestCommand } from '../posture/test-runner.js';
+import { STATE_DIR_NAME } from '../posture/state-dir.js';
+
+const MAX_COPY_BYTES = 200 * 1024 * 1024;
+const SKIP_DIRS = new Set(['.git', STATE_DIR_NAME, 'node_modules', 'target', 'dist', 'build', '.venv', '__pycache__', 'bin', 'obj']);
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+const has = (root, rel) => { try { return fs.existsSync(path.join(root, rel)); } catch { return false; } };
+const available = (cmd) => { try { const r = spawnSync(cmd, ['--version'], { timeout: 8000, stdio: 'ignore' }); return !(r.error && r.error.code === 'ENOENT'); } catch { return false; } };
+
+/** @returns {{cmd:string,args:string[],kind:string}|null} */
+export function discoverTestCommand(root, { available: avail = available } = {}) {
+  const base = detectTestCommand(root);
+  if (base) return base;
+  if (has(root, 'Cargo.toml') && avail('cargo')) return { cmd: 'cargo', args: ['test', '--quiet'], kind: 'cargo' };
+  try { if (fs.readdirSync(root).some((f) => /\.(sln|csproj)$/.test(f)) && avail('dotnet')) return { cmd: 'dotnet', args: ['test', '--nologo'], kind: 'dotnet' }; } catch { /* unreadable root */ }
+  if (has(root, 'pom.xml') && avail('mvn')) return { cmd: 'mvn', args: ['-q', 'test'], kind: 'maven' };
+  if ((has(root, 'build.gradle') || has(root, 'build.gradle.kts')) && avail('gradle')) return { cmd: 'gradle', args: ['test', '--quiet'], kind: 'gradle' };
+  if ((has(root, '.rspec') || has(root, 'spec')) && has(root, 'Gemfile') && avail('bundle')) return { cmd: 'bundle', args: ['exec', 'rspec'], kind: 'rspec' };
+  return null;
+}
+
+function copyTree(root, dest) {
+  let bytes = 0;
+  fs.cpSync(root, dest, {
+    recursive: true, dereference: false, verbatimSymlinks: true,
+    filter: (src) => {
+      const rel = path.relative(root, src);
+      if (!rel) return true;
+      if (rel.split(path.sep).some((s) => SKIP_DIRS.has(s))) return false;
+      try { const st = fs.lstatSync(src); if (st.isFile()) { bytes += st.size; if (bytes > MAX_COPY_BYTES) throw new Error('tree-too-large'); } } catch (e) { if (e.message === 'tree-too-large') throw e; }
+      return true;
+    },
+  });
+  // dependencies are linked, not copied: tests need them, and the copy must not be able to change them
+  const nm = path.join(root, 'node_modules');
+  if (fs.existsSync(nm)) { try { fs.symlinkSync(nm, path.join(dest, 'node_modules'), 'dir'); } catch { /* best effort */ } }
+}
+
+function run(cwd, cmd, args, timeoutMs) {
+  const t0 = Date.now();
+  const r = spawnSync(cmd, args, { cwd, encoding: 'utf8', timeout: timeoutMs, env: { ...process.env, CI: '1' } });
+  const durationMs = Date.now() - t0;
+  if (r.error && r.error.code === 'ENOENT') return { status: 'skipped', passed: null, skipped: true, reason: `${cmd}-not-installed`, exitCode: null, timedOut: false, durationMs };
+  if (r.status === null) return { status: 'failed', passed: false, skipped: false, reason: 'timed-out', exitCode: null, timedOut: true, durationMs };
+  return { status: r.status === 0 ? 'passed' : 'failed', passed: r.status === 0, skipped: false, reason: r.status === 0 ? null : `exit-${r.status}`, exitCode: r.status, timedOut: false, durationMs };
+}
+
+/**
+ * @param {{scanRoot:string, files:Record<string,string>, command?:string[], timeoutMs?:number}} o
+ */
+export function runTestsOnPatchedCopy({ scanRoot, files, command, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const spec = command && command.length ? { cmd: command[0], args: command.slice(1), kind: 'explicit' } : discoverTestCommand(scanRoot);
+  if (!spec) return { status: 'skipped', passed: null, skipped: true, reason: 'no-test-command-detected', exitCode: null, timedOut: false, durationMs: 0, onPatchedTree: false };
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'patched-tests-'));
+  try {
+    const patched = path.join(work, 'patched');
+    try { copyTree(scanRoot, patched); } catch (e) { return { status: 'skipped', passed: null, skipped: true, reason: e.message === 'tree-too-large' ? 'tree-too-large-to-copy' : `copy-failed: ${e.message}`, exitCode: null, timedOut: false, durationMs: 0, onPatchedTree: false }; }
+    for (const [rel, text] of Object.entries(files || {})) {
+      const abs = path.resolve(patched, rel);
+      if (abs !== patched && !abs.startsWith(patched + path.sep)) return { status: 'skipped', passed: null, skipped: true, reason: 'patch-path-escapes-the-copy', exitCode: null, timedOut: false, durationMs: 0, onPatchedTree: false };
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, String(text));
+    }
+    const result = { ...run(patched, spec.cmd, spec.args, timeoutMs), runner: spec.kind, onPatchedTree: true, preExistingFailure: false };
+    if (result.status === 'failed') {
+      const pristine = path.join(work, 'pristine');
+      try { copyTree(scanRoot, pristine); const base = run(pristine, spec.cmd, spec.args, timeoutMs); if (base.status === 'failed') result.preExistingFailure = true; } catch { /* attribution is best effort */ }
+    }
+    return result;
+  } finally { fs.rmSync(work, { recursive: true, force: true }); }
+}

package/src/fix/verification-adapters.js

@@ -0,0 +1,97 @@
+// Adapters from the results the existing routes already produce to the patch-level verification record (E3-02).
+//
+// An adapter only RELAYS: it maps what a route observed onto legs, and anything the route did not observe becomes `not_run` with the
+// reason. It never upgrades a result. In particular a test run that happened before the patch was written (verifyFix sets
+// `testedPrePatch`) is recorded as `not_run` for the patched tree, not as passed.
+import { createHash } from 'node:crypto';
+import { digestOf } from '../posture/assurance/identity.js';
+import { buildFixVerificationRecord, evidenceItem, leg } from './verification-record.js';
+
+const sha256Hex = (s) => createHash('sha256').update(s).digest('hex');
+
+/** Digest of a patch: the files it writes, by path and content digest. Independent of key order. */
+export function patchHashOf(files) {
+  const rows = Object.keys(files || {}).sort().map((p) => [p, sha256Hex(String(files[p]))]);
+  return digestOf({ files: rows });
+}
+
+/** Digest of the files as they were before the patch, for the paths the patch touches. `read(path)` returns the text or null. */
+export function treeHashOf(paths, read) {
+  const rows = [...paths].sort().map((p) => { const t = read(p); return [p, t === null || t === undefined ? null : sha256Hex(String(t))]; });
+  return digestOf({ files: rows });
+}
+
+const asEvidence = (kind, value, note = null) => evidenceItem({ kind, mediaType: 'application/json', sha256: digestOf(value).slice('sha256:'.length), note });
+
+/**
+ * @param {object} v        the object verifyFix returns
+ * @param {object} ctx      { finding:{id,stableId}, files, route, mode, preCommit, preFiles(read), tools, requiredLegs, findingPresent }
+ */
+export function recordFromVerifyFix(v, ctx) {
+  const evidence = [];
+  const add = (kind, value, note) => { const e = asEvidence(kind, value, note); if (!evidence.some((x) => x.id === e.id)) evidence.push(e); return e.id; };
+  const failures = [];
+
+  const rescanId = v.rescan ? add('rescan-result', v.rescan, 'verifyFix rescan leg') : null;
+  const securityAfter = !v.rescan ? leg('not_run', { reason: 'the route returned no rescan result' })
+    : v.rescan.ok ? leg('passed', { evidenceIds: [rescanId] }) : leg('failed', { evidenceIds: [rescanId], reason: `the original finding is still present (${v.rescan.reason})` });
+  if (ctx.persistence?.status === 'failed') {
+    const id = add('secret-persistence', ctx.persistence, 'the original secret literal searched for in the patched source');
+    securityAfter.status = 'failed'; securityAfter.evidenceIds = [...securityAfter.evidenceIds, id]; securityAfter.reason = ctx.persistence.reason;
+  }
+  const introduced = v.rescan?.introduced || [];
+  const newFindingDelta = !v.rescan ? leg('not_run', { reason: 'the route returned no rescan result' })
+    : introduced.length ? leg('failed', { evidenceIds: [rescanId], reason: `${introduced.length} finding(s) introduced by the patch` }) : leg('passed', { evidenceIds: [rescanId] });
+
+  let lint;
+  if (!v.lint) lint = leg('not_run', { reason: 'the route returned no lint result' });
+  else if (v.lint.runner === 'none') lint = leg('not_applicable', { reason: 'no linter is configured for this project' });
+  else lint = v.lint.ok ? leg('passed', { evidenceIds: [add('lint-result', v.lint)] }) : leg('failed', { evidenceIds: [add('lint-result', v.lint)], reason: 'the linter reported errors on the patched files' });
+
+  let behaviorTests;
+  if (!v.tests) behaviorTests = leg('not_run', { reason: 'the route returned no test result' });
+  else if (v.tests.skipped) behaviorTests = leg('not_run', { reason: `tests were skipped (${v.tests.reason || 'no reason recorded'})` });
+  else if (v.tests.preExistingFailure || v.tests.reason === 'suite-already-failing-before-the-patch') behaviorTests = leg('not_run', { reason: 'the project test suite was already failing before the patch, so it cannot show the patch preserved behaviour' });
+  else if (v.testedPrePatch) behaviorTests = leg('not_run', { evidenceIds: [], reason: 'the tests ran on the tree BEFORE the patch was written, so they say nothing about the patch' });
+  else behaviorTests = v.tests.passed ? leg('passed', { evidenceIds: [add('test-result', v.tests)] }) : leg('failed', { evidenceIds: [add('test-result', v.tests)], reason: 'the project tests failed on the patched tree' });
+
+  const poc = v.poc?.status;
+  const pocId = v.poc && poc !== 'not-requested' ? add('exploit-replay', v.poc) : null;
+  const replay = ctx.replay || null;
+  const replayId = replay ? add('exploit-replay', replay, 'pre/post replay of the same reproducer') : null;
+  const replayLeg = (status, ok, bad) => status === 'passed' ? leg('passed', { evidenceIds: [replayId] }) : status === 'failed' ? leg('failed', { evidenceIds: [replayId], reason: bad }) : leg('not_run', { reason: replay.reason || ok });
+  const exploitProofAfter = replay ? replayLeg(replay.afterStatus, 'the replay did not run', replay.reason) : !v.poc || poc === 'not-requested' ? leg('not_run', { reason: 'no exploit replay was requested by this route' })
+    : poc === 'no-longer-proven' ? leg('passed', { evidenceIds: [pocId] })
+    : poc === 'still-exploitable' ? leg('failed', { evidenceIds: [pocId], reason: 'the exploit still works against the patched code' })
+    : leg('not_run', { evidenceIds: [], reason: `the exploit replay was inconclusive (${v.poc.reason || 'no reason recorded'})` });
+  const exploitProofBefore = replay ? replayLeg(replay.beforeStatus, 'the replay did not run', replay.reason) : !v.poc || poc === 'not-requested' ? leg('not_run', { reason: 'no exploit replay was requested by this route' })
+    : poc === 'inconclusive' ? leg('not_run', { reason: 'the exploit could not be reproduced on the original code' })
+    : leg('passed', { evidenceIds: [pocId] });
+
+  const findingEv = ctx.findingPresent === true && ctx.finding ? add('finding', { id: ctx.finding.id, stableId: ctx.finding.stableId ?? null }, 'the finding in the signed scan') : null;
+  const securityBefore = findingEv ? leg('passed', { evidenceIds: [findingEv] }) : leg('not_run', { reason: 'the finding was not shown to be present on the original code' });
+
+  if (v.honesty && v.honesty.ok === false) failures.push({ leg: 'securityAfter', reason: 'the honesty gate refused the claimed fix quality' });
+
+  const fp = ctx.footprint || null;
+  const footprintLeg = !fp ? leg('not_run', { reason: 'this route does not check that intended functionality survived' })
+    : fp.status === 'passed' ? leg('passed', { evidenceIds: [add('footprint', fp, 'sensitive operation kinds before and after the patch')] })
+    : fp.status === 'failed' ? leg('failed', { evidenceIds: [add('footprint', fp, 'sensitive operation kinds before and after the patch')], reason: fp.reason })
+    : leg('not_run', { reason: fp.reason });
+  const files = ctx.files || {};
+  return buildFixVerificationRecord({
+    findingId: ctx.finding?.id ?? 'unknown', findingStableId: ctx.finding?.stableId, mode: ctx.mode || 'verify', route: ctx.route || 'verify-fix',
+    preCommit: ctx.preCommit ?? null, preTreeHash: ctx.preFiles ? treeHashOf(Object.keys(files), ctx.preFiles) : null, postPatchHash: patchHashOf(files), patchHash: patchHashOf(files),
+    affectedFiles: Object.keys(files),
+    securityBefore, securityAfter, exploitProofBefore, exploitProofAfter, newFindingDelta, behaviorTests, lint,
+    behaviorPreservation: footprintLeg,
+    regressionTests: leg('not_run', { reason: 'this route runs a single test leg' }),
+    typecheck: leg('not_run', { reason: 'this route does not run a type checker' }),
+    dependencyChecks: leg('not_applicable', { reason: 'a source patch changes no dependency' }),
+    requiredLegs: ctx.requiredLegs || ['securityAfter', 'newFindingDelta', 'behaviorTests'],
+    failures, evidence, tools: ctx.tools || { engineVersion: null, verifier: 'verifyFix' },
+    residualRisk: ctx.residualRisk,
+    confidence: ctx.confidence || (replay?.executionProven ? { level: 'proven', policy: 'exploit-replay-v1', evidenceIds: [replayId] } : undefined),
+    ...(ctx.timestamps ? { timestamps: ctx.timestamps } : {}),
+  });
+}

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,
+  };
+}