@clear-capabilities/agentic-security-scanner 0.160.0 → 0.162.0

package/src/mcp/tools.js

@@ -26,6 +26,8 @@ import { withStateWritesDisabled } from '../posture/state-dir.js';
 import { analyzeTranscript, formatCacheReport, renderCacheStatusLine } from '../posture/cache-economics.js';
 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';
 // Git-origin provenance (Finding Provenance M0/M1). Distinct from
 // `finding.provenance` (AI-authorship) and from an SCA entry's `provenance`
 // (Sigstore/SLSA attestation) — see report/index.js's import comment.
@@ -349,7 +351,7 @@ function _maybeOffload(sessionRoot, toolName, items) {
 //
 // Exported under the `_internals` convention this codebase already uses
 // (see posture/poc-inprocess.js). Not part of the MCP tool surface.
-export const _internals = { _confine, isReservedWrite: _isReservedWritePath };
+export const _internals = { _confine, isReservedWrite: _isReservedWritePath, checkMultiFileTargets: _checkMultiFileTargets, multiFilePlanDigest: _multiFilePlanDigest };
 
 export const scan_diff = {
   name: 'scan_diff',
@@ -599,14 +601,161 @@ export const explain_finding = {
       findingProvenance: f.findingProvenance ? redactFindingProvenance(f.findingProvenance, {
         pseudonymize: process.env.AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS === '1',
       }) : null,
+      // X-206: the same verification projection the JSON and text reports carry; absent when the finding has no record.
+      ...(f.verificationRecord && typeof f.verificationRecord === 'object'
+        ? { verificationRecord: f.verificationRecord, ...verificationFields(f.verificationRecord, { replay: f.verificationReplay }) }
+        : {}),
     };
   },
 };
 
+// FR-307/FR-1002/FR-1003: the high-impact-change approval gate (approval evidence, approver identity, separation of duties),
+// shared by the caller-patch branch and the multi-file plan branch so the two cannot drift. Returns a refusal result, or null
+// when the change is not high-impact or is properly approved.
+function _highImpactApprovalRefusal(ctx, materialClassification, fixMeta) {
+  if (!materialClassification.highImpactCategories.length) return null;
+  const cats = materialClassification.highImpactCategories.join(', ');
+  const approval = fixMeta && typeof fixMeta === 'object' ? fixMeta.approval : null;
+  const hasApprovalEvidence = !!(approval && typeof approval === 'object' &&
+    typeof approval.approvedBy === 'string' && approval.approvedBy.trim().length > 0 &&
+    typeof approval.reason === 'string' && approval.reason.trim().length > 0);
+  if (!hasApprovalEvidence) {
+    return {
+      _meta: META, applied: false,
+      reason: `high-impact change (${cats}) requires approval evidence — pass fixMeta.approval: {approvedBy, reason} — before it can be applied`,
+      materialClassification,
+    };
+  }
+  const approverRegistry = loadApproverRegistry(ctx.sessionRoot);
+  const requiredRoles = requiredRolesFor(approverRegistry, materialClassification.highImpactCategories);
+  const identityCheck = verifyApprover(approverRegistry, approval.approvedBy, requiredRoles);
+  if (!identityCheck.verified) {
+    return { _meta: META, applied: false, reason: `high-impact change (${cats}) approval rejected: ${identityCheck.reason}`, materialClassification };
+  }
+  // FR-1003: separation-of-duties, same no-op-unless-configured gate as apply-fix-service.js's own copy; see approver-registry.js.
+  const sodCheck = checkSeparationOfDuties(approverRegistry, fixMeta?.author, approval.approvedBy);
+  if (!sodCheck.ok) {
+    return { _meta: META, applied: false, reason: `high-impact change (${cats}) approval rejected: ${sodCheck.reason}`, materialClassification };
+  }
+  return null;
+}
+
+// ─── Multi-file plans (apply_fix with plan_digest) ───────────────────────────
+// A NixOS option fix can edit several files at once (every definition at the winning priority). apply_fix never accepts file
+// contents for this: it RECOMPUTES the plan from the signed finding and the live tree, and writes only if that plan's digest is
+// the one synthesize_fix returned. The digest binds the finding, every file path, the exact pre-image and the exact post-image
+// of each edit, so a changed tree, a changed finding, or an altered digest all refuse. The write itself is the language
+// lifecycle's all-or-nothing writeManyWithBackup (one backup per file, one history group, honest rollback).
+const MULTI_FILE_MAX = 8;
+const _sha256 = (t) => crypto.createHash('sha256').update(String(t), 'utf8').digest('hex');
+function _multiFilePlanDigest(finding, edits) {
+  const canon = edits.map((e) => ({ file: String(e.file), before: _sha256(e.before), after: _sha256(e.after) })).sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  return _sha256(JSON.stringify({ v: 'mf-plan/1', id: finding.id || null, stableId: finding.stableId || null, edits: canon }));
+}
+// Every file of a multi-file plan gets the SAME checks a single-file apply_fix target gets: root-relative lexical form,
+// confinement (no symlink leaf, no symlinked parent, no escape), reserved-write list, and existence. Returns {ok, reason, abs}.
+function _checkMultiFileTargets(sessionRoot, edits) {
+  if (!Array.isArray(edits) || edits.length < 2) return { ok: false, reason: 'a multi-file plan needs at least two edits' };
+  if (edits.length > MULTI_FILE_MAX) return { ok: false, reason: `a multi-file plan may edit at most ${MULTI_FILE_MAX} files` };
+  const rootReal = fs.realpathSync(path.resolve(sessionRoot));
+  const seen = new Set();
+  const abs = {};
+  for (const e of edits) {
+    const rel = e && e.file;
+    if (typeof rel !== 'string' || !rel || rel.includes('\0') || rel.includes('\\') || path.isAbsolute(rel) || rel.split('/').some((seg) => seg === '..' || seg === '.' || seg === '')) {
+      return { ok: false, reason: `path-escape refused: plan file "${path.isAbsolute(String(rel)) ? '(absolute path)' : String(rel).slice(0, 120)}" is not a clean root-relative path` };
+    }
+    if (seen.has(rel)) return { ok: false, reason: `the same file appears twice in the plan: ${rel}` };
+    seen.add(rel);
+    let real;
+    try { real = _confine(sessionRoot, rel, 'plan file'); }
+    catch (err) { return { ok: false, reason: `path-escape refused: ${String(err.message).split(rootReal).join('<root>')}` }; }
+    if (path.relative(rootReal, real).split(path.sep).join('/') !== rel) return { ok: false, reason: `path-escape refused: plan file "${rel}" resolves through a symbolic link` };
+    if (_isReservedWritePath(sessionRoot, real)) return { ok: false, reason: `reserved path refused: ${rel}` };
+    if (!fs.existsSync(real)) return { ok: false, reason: `plan file not found: ${rel}` };
+    abs[rel] = real;
+  }
+  return { ok: true, abs };
+}
+const _scrubRoot = (sessionRoot, text) => {
+  let out = String(text);
+  const roots = new Set([path.resolve(sessionRoot)]);
+  try { roots.add(fs.realpathSync(path.resolve(sessionRoot))); } catch { /* root vanished: the plain path is still scrubbed */ }
+  for (const r of roots) out = out.split(r).join('<root>');
+  return redactString(out);
+};
+const _gateSummary = (g) => (g ? {
+  path: g.path ? g.path.ok : undefined, syntax: g.syntax ? g.syntax.ok : undefined,
+  rescan: g.rescan ? { ok: g.rescan.ok, originalGone: g.rescan.originalGone, newMediumOrHigher: g.rescan.newMediumOrHigher } : undefined,
+  effective: g.effective ? { ok: g.effective.ok, ran: g.effective.ran === true, detail: g.effective.detail } : undefined,
+  compile: g.compile ? { ran: g.compile.ran === true, ok: g.compile.ok } : undefined,
+} : null);
+
+async function _applyMultiFilePlan({ f, planDigest, dryRun, fixMeta, ctx, status }) {
+  const refuse = (reason, extra = {}) => ({ _meta: META, applied: false, multiFile: true, reason, ...extra });
+  if (typeof planDigest !== 'string' || !/^[0-9a-f]{64}$/.test(planDigest)) return refuse('plan_digest must be the 64-character hex digest returned by synthesize_fix');
+  if (!f.stableId) return refuse('finding has no stableId, so a plan cannot be verified against it');
+  const lc = await import('../language/context.js');
+  if (lc.languageOfFinding(f) !== 'nix') return refuse('multi-file plans are produced for NixOS findings only');
+  const nf = await import('../language/nix-fix.js');
+  const proj = lc.loadLanguageProject(ctx.sessionRoot);
+  const files = proj.files;
+  // The plan is derived here, from the signed finding and the live tree. Nothing the caller sends can supply file content.
+  const plan = nf.planNixFix(f, files);
+  if (!plan || plan.ok === false) return refuse(`no applicable plan: ${_scrubRoot(ctx.sessionRoot, (plan && plan.reason) || 'no deterministic fix')}`);
+  if (!Array.isArray(plan.edits) || plan.edits.length < 2) return refuse('this finding has a single-file plan; use apply_fix without plan_digest');
+  if (_multiFilePlanDigest(f, plan.edits) !== planDigest) {
+    return refuse('plan_digest does not match the plan computed now for this finding: the project files or the finding changed since synthesize_fix, or the digest was altered. Run synthesize_fix again and review the new plan.', { stale: true });
+  }
+  const targets = _checkMultiFileTargets(ctx.sessionRoot, plan.edits);
+  if (!targets.ok) return refuse(targets.reason);
+  const classification = classifyFixMaterialRisk(Object.fromEntries(plan.edits.map((e) => [e.file, { before: e.before, after: e.after }])));
+  if (!dryRun) {
+    const approvalRefusal = _highImpactApprovalRefusal(ctx, classification, fixMeta);
+    if (approvalRefusal) return { ...approvalRefusal, multiFile: true };
+  }
+  // The verification gates (syntax, rescan with no new finding, effective value changed as intended) run inside the lifecycle,
+  // and the pre-write hook re-checks the digest of the VERIFIED edits and the targets immediately before the first byte is written.
+  const preWrite = (verifiedPlan) => {
+    const vedits = Array.isArray(verifiedPlan.edits) ? verifiedPlan.edits : [];
+    if (_multiFilePlanDigest(f, vedits) !== planDigest) return { ok: false, detail: 'the verified plan differs from the previewed plan' };
+    const again = _checkMultiFileTargets(ctx.sessionRoot, vedits);
+    return again.ok ? { ok: true } : { ok: false, detail: again.reason };
+  };
+  let res;
+  try { res = await nf.validateNixFix(f, { files, apply: !dryRun, root: ctx.sessionRoot, preWrite }); }
+  catch (e) { return refuse(`plan verification failed: ${_scrubRoot(ctx.sessionRoot, e.message)}`); }
+  const gates = _gateSummary(res.gates);
+  const touched = plan.edits.map((e) => e.file);
+  if (res.status === 'verified' && dryRun) {
+    return { _meta: META, applied: false, dryRun: true, verified: true, multiFile: true, files: touched, planDigest, gates, materialClassification: classification, diff: res.preview };
+  }
+  if (res.status === 'applied') {
+    let acceptance = null;
+    try { acceptance = fixAcceptanceRate(ctx.sessionRoot); } catch { /* best-effort */ }
+    const hist = Array.isArray(res.history) ? res.history : [];
+    const allRecorded = hist.length === touched.length && hist.every(Boolean);
+    return {
+      _meta: META, applied: true, verified: true, multiFile: true, files: touched, planDigest,
+      groupId: res.backup && res.backup.id, historyIds: hist.map((h) => (h ? h.id : null)),
+      ...(allRecorded ? {} : { warning: 'the files were written and backed up, but the fix history could not record every entry; restore with the group backup under .agentic-security/fix-backups' }),
+      gates, integrity: status, acceptance, materialClassification: classification,
+    };
+  }
+  // Blocked or failed: nothing is left changed unless rollbackIncomplete says otherwise.
+  const incomplete = res.rolledBack === false;
+  return {
+    _meta: META, applied: false, multiFile: true, files: touched,
+    reason: _scrubRoot(ctx.sessionRoot, res.reason || `plan not applied (${res.status})`),
+    gates,
+    ...(res.rolledBack !== undefined ? { rolledBack: res.rolledBack === true, rollbackIncomplete: incomplete, ...(incomplete ? { restoreManually: (res.rollbackFailed || []).map(String) } : {}) } : {}),
+  };
+}
+
 // ─── apply_fix ───────────────────────────────────────────────────────────────
 export const apply_fix = {
   name: 'apply_fix',
-  description: 'Apply a fix for a finding. Two modes: (1) the stored fix.replacement, or (2) a caller-supplied `patch` (a files map) which is RE-VERIFIED inline (rescan-clean + no new ≥medium + lint) before any write — this unblocks findings that ship only a template or description. Refuses if last-scan.json fails its HMAC check, if the finding is shadow-marked, or if a path escapes the session root via lexical traversal OR a symlink. Requires confirm:true. Supports dry_run:true to preview without writing. On success, `verified:true` means verification passed but `verifiedFull:true` is the honest signal that every required leg (lint when configured, tests when a runner exists) genuinely ran — a false `verifiedFull` with `verified:true` means the pass is real but degraded (see `verify.degradedLegs`), not a full verification.',
+  description: 'Apply a fix for a finding. Two modes: (1) the stored fix.replacement, or (2) a caller-supplied `patch` (a files map) which is RE-VERIFIED inline (rescan-clean + no new ≥medium + lint) before any write — this unblocks findings that ship only a template or description. Refuses if last-scan.json fails its HMAC check, if the finding is shadow-marked, or if a path escapes the session root via lexical traversal OR a symlink. Requires confirm:true. Supports dry_run:true to preview without writing. On success, `verified:true` means verification passed but `verifiedFull:true` is the honest signal that every required leg (lint when configured, tests when a runner exists) genuinely ran — a false `verifiedFull` with `verified:true` means the pass is real but degraded (see `verify.degradedLegs`), not a full verification. MULTI-FILE NixOS FIX: when synthesize_fix returns `languageFix.planDigest` (an option defined in several files, edited together), pass it back as `plan_digest`. apply_fix then RECOMPUTES the plan itself from the signed finding and the live files, refuses unless its digest matches (so a changed tree, a changed finding or an altered digest all refuse; you never send file content), applies the same confinement, reserved-path, shadow and high-impact-approval checks to EVERY file, runs the verification gates (syntax, rescan with no new finding, the option resolves to the intended value on the patched configuration) before writing, and writes all files or none with one backup per file and one history group that `undo` reverts together. A rollback that could not complete is reported as `rollbackIncomplete` with the files to restore. `plan_digest` cannot be combined with `patch`.',
   inputSchema: {
     type: 'object',
     additionalProperties: false,
@@ -614,6 +763,7 @@ export const apply_fix = {
       finding_id: { type: 'string', minLength: 1, maxLength: 256 },
       confirm: { type: 'boolean' },
       dry_run: { type: 'boolean' },
+      plan_digest: { type: 'string', minLength: 64, maxLength: 64 },
       patch: {
         type: 'object',
         additionalProperties: { type: 'string', maxLength: 500_000 },
@@ -673,7 +823,7 @@ export const apply_fix = {
     },
     required: ['finding_id', 'confirm'],
   },
-  async handler({ finding_id, confirm, dry_run = false, patch = null, fixMeta = null }, ctx) {
+  async handler({ finding_id, confirm, dry_run = false, patch = null, fixMeta = null, plan_digest = null }, ctx) {
     if (confirm !== true) {
       return { _meta: META, applied: false, reason: 'apply_fix requires confirm: true.' };
     }
@@ -687,6 +837,15 @@ export const apply_fix = {
       return { _meta: META, applied: false, reason: 'shadow findings cannot be auto-applied' };
     }
 
+    // Multi-file plan (a NixOS option defined in several files). The plan is recomputed here and bound by plan_digest; the
+    // caller can never supply file content on this path, and it cannot be combined with `patch`.
+    if (plan_digest !== null && plan_digest !== undefined) {
+      if (patch && typeof patch === 'object' && Object.keys(patch).length) {
+        return { _meta: META, applied: false, reason: 'plan_digest and patch cannot be combined: a multi-file plan is computed by the scanner, not supplied by the caller' };
+      }
+      return _applyMultiFilePlan({ f, planDigest: plan_digest, dryRun: dry_run === true, fixMeta, ctx, status });
+    }
+
     // #3 — verifier-approved patch path. When the caller supplies `patch` (a
     // files map, same shape as verify_fix), apply_fix re-runs the verifier
     // INLINE and writes only if it passes: the original finding's stableId is
@@ -722,7 +881,7 @@ export const apply_fix = {
           // 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 };
+          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({
@@ -740,6 +899,9 @@ export const apply_fix = {
           _meta: META, applied: false,
           reason: `patch rejected by verifier: ${verdict.summary || verdict.rescan?.reason || 'did not verify'}`,
           verify: { rescan: verdict.rescan, lint: { runner: verdict.lint?.runner, ok: verdict.lint?.ok }, honesty: verdict.honesty || null },
+          // 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),
         };
       }
       // FR-307/FR-1002/D-0024: this caller-supplied-patch branch writes via
@@ -760,41 +922,10 @@ 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, materialClassification };
-      }
-      if (materialClassification.highImpactCategories.length) {
-        const approval = fixMeta && typeof fixMeta === 'object' ? fixMeta.approval : null;
-        const hasApprovalEvidence = !!(approval && typeof approval === 'object' &&
-          typeof approval.approvedBy === 'string' && approval.approvedBy.trim().length > 0 &&
-          typeof approval.reason === 'string' && approval.reason.trim().length > 0);
-        if (!hasApprovalEvidence) {
-          return {
-            _meta: META, applied: false,
-            reason: `high-impact change (${materialClassification.highImpactCategories.join(', ')}) requires approval evidence — pass fixMeta.approval: {approvedBy, reason} — before it can be applied`,
-            materialClassification,
-          };
-        }
-        const approverRegistry = loadApproverRegistry(ctx.sessionRoot);
-        const requiredRoles = requiredRolesFor(approverRegistry, materialClassification.highImpactCategories);
-        const identityCheck = verifyApprover(approverRegistry, approval.approvedBy, requiredRoles);
-        if (!identityCheck.verified) {
-          return {
-            _meta: META, applied: false,
-            reason: `high-impact change (${materialClassification.highImpactCategories.join(', ')}) approval rejected: ${identityCheck.reason}`,
-            materialClassification,
-          };
-        }
-        // FR-1003: separation-of-duties, same no-op-unless-configured gate
-        // as apply-fix-service.js's own copy — see approver-registry.js.
-        const sodCheck = checkSeparationOfDuties(approverRegistry, fixMeta?.author, approval.approvedBy);
-        if (!sodCheck.ok) {
-          return {
-            _meta: META, applied: false,
-            reason: `high-impact change (${materialClassification.highImpactCategories.join(', ')}) approval rejected: ${sodCheck.reason}`,
-            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 };
       }
+      const approvalRefusal = _highImpactApprovalRefusal(ctx, materialClassification, fixMeta);
+      if (approvalRefusal) return approvalRefusal;
       const written = [];
       try {
         for (const [rel, v] of Object.entries(confinedAbs)) {
@@ -822,7 +953,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 }, 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 };
     }
 
     if (typeof f.fix?.replacement !== 'string') {
@@ -911,7 +1042,7 @@ export const apply_fix = {
 // proceed with apply_fix.
 export const verify_fix = {
   name: 'verify_fix',
-  description: 'Verify a proposed patch before applying. Re-scans the patched files in memory, runs the project linter, runs the project test suite, checks fix honesty (FULL/MITIGATION/WORKAROUND) when fixMeta is supplied, and re-runs the PoC when one exists. Returns { ok, rescan, lint, tests, honesty, poc, summary }. Does not write to the target project’s own files, but DOES append one record per attempt to .agentic-security/fix-metrics.jsonl for the measured fix-loop.',
+  description: 'Verify a proposed patch before applying. Re-scans the patched files in memory, runs the project linter, runs the project test suite, checks fix honesty (FULL/MITIGATION/WORKAROUND) when fixMeta is supplied, and re-runs the PoC when one exists. Returns { ok, rescan, lint, tests, honesty, poc, summary, verificationRecord } (verificationRecord is the shared version-1 record: outcome is one of not-run, unsupported, inconclusive, error, refuted, confirmed, and a static re-scan alone is never reported as confirmed; verificationView is the shared projection every interface shows for it, with state, scope, evidence ids, replay prerequisites and what was and was not verified). Does not write to the target project’s own files, but DOES append one record per attempt to .agentic-security/fix-metrics.jsonl for the measured fix-loop.',
   inputSchema: {
     type: 'object',
     additionalProperties: false,
@@ -1012,6 +1143,10 @@ export const verify_fix = {
         honesty: r.honesty,
         poc: r.poc ? { ...r.poc, reason: r.poc.reason ? redactString(r.poc.reason) : r.poc.reason } : r.poc,
         summary: r.summary,
+        // X-201: the one version-1 verification record (additive). It states what was actually established, e.g.
+        // `not-run` when no exploit oracle executed against the patch, never a bare pass/fail.
+        verificationRecord: r.verificationRecord ?? null,
+        ...verificationFields(r.verificationRecord),
       };
     } catch (e) {
       return { _meta: META, ok: false, reason: `verify_fix failed: ${e.message}` };
@@ -1025,7 +1160,7 @@ export const verify_fix = {
 // sequence with the returned blob.
 export const synthesize_fix = {
   name: 'synthesize_fix',
-  description: 'Return the stored fix replacement for a finding (replacement text + remediation + plan if the patch is too large). Read-only; never writes to disk. Use verify_fix → apply_fix to deploy.',
+  description: 'Return the stored fix replacement for a finding (replacement text + remediation + plan if the patch is too large). Read-only; never writes to disk. Use verify_fix → apply_fix to deploy. For a NixOS option defined in several files, `languageFix.multiFile` lists every file, `languageFix.edits` gives each file\'s before/after SHA-256 (no file content) and `languageFix.planDigest` is the value to pass to apply_fix as `plan_digest`; the preview is verified but nothing is written.',
   inputSchema: {
     type: 'object',
     additionalProperties: false,
@@ -1079,8 +1214,15 @@ export const synthesize_fix = {
             const proj = lc.loadLanguageProject(ctx.sessionRoot);
             const prev = await lc.languageFixPreview(f, proj.files);
             languageFix = { status: prev.status, ok: prev.ok, label: prev.label || null, tier: prev.tier || null, reason: prev.reason || null, diff: prev.diff || null, explanation: prev.explanation || null, consequences: prev.consequences || [] };
-            // apply_fix writes ONE file; a fix that spans several files must go through the CLI lifecycle (atomic, grouped undo).
-            if (prev.ok && prev.edits) languageFix.multiFile = prev.edits.map((e) => e.file);
+            // A fix that spans several files is applied with apply_fix + plan_digest (atomic, one history group); see _applyMultiFilePlan.
+            if (prev.ok && prev.edits) {
+              languageFix.multiFile = prev.edits.map((e) => e.file);
+              // The digest binds finding + every file + exact pre/post image. Pass it to apply_fix as plan_digest; apply_fix
+              // recomputes the plan itself and refuses on any difference. No file content is ever sent back to apply_fix.
+              languageFix.planDigest = _multiFilePlanDigest(f, prev.edits);
+              languageFix.edits = prev.edits.map((e) => ({ file: e.file, beforeSha256: _sha256(e.before), afterSha256: _sha256(e.after) }));
+              languageFix.applyWith = { finding_id: f.id, confirm: true, plan_digest: languageFix.planDigest };
+            }
             else if (prev.ok) autofix = { deterministic: true, ruleId: f.rule || f.family || null, patch: prev.after, file: prev.file, label: prev.label || null, verified: true };
           }
         } catch { /* best-effort: the preview is advisory */ }

package/src/posture/CLAUDE.md

@@ -96,6 +96,8 @@ Wired in `bin/agentic-security.js` after every filter and after `makeDeterminist
 
 **`verifyRunAttestation` now has two real callers.** `agentic-security verify-attestation <file>` auto-detects whether the given JSON is an evidence bundle (`.finding`+`.signature`, verified via `evidence-bundle.js`'s Ed25519 path, unchanged) or a run attestation (`.digest`+`.canonicalisation`, either bare or embedded under a full `last-scan.json`'s `.attestation` field) and dispatches accordingly. A run attestation isn't self-contained the way a bundle is — verifying it means re-scanning the project (`--against <path>`, default `.`) and confirming the fresh scan reproduces the attested digest, which is the actual, meaningful claim this artifact makes ("does this codebase, scanned now, match what was attested earlier"). Separately, `scripts/release-check.mjs`'s `attestation-self-check` gate round-trips a synthetic finding set through compute→verify (and a mutated copy through verify, which must fail) on every release, catching a broken canonicalisation or signing path before it ships — independent of whether any project ever calls `verify-attestation` on a real artifact.
 
+**Issuer and trust basis (CORE-003.AC03).** `evidence-bundle.js` signs an `issuance` block inside the canonical bytes (only when present, so pre-existing bundles keep their signatures): issuer id and key fingerprint, `trustBasis: 'self-issued-local-key'`, `independentlyCertified: false`, and a plain statement. `verifyEvidenceBundle` returns `trustBasis`/`issuer`/`trustNote`; a bundle with no `issuance` verifies and is reported `none-declared` (never as trusted); an unknown basis, an `independentlyCertified: true` claim, or an issuer fingerprint that is not the verifying key is rejected even when validly signed. The only basis this build can verify is the local one: a third-party basis needs a trust-root policy that does not exist here. A signed run attestation carries the same self-issued label. `verify-attestation` exit codes are unchanged. Signing keys are protected from workers by `sandbox/trust-boundary.js` (see `sandbox/CLAUDE.md`). Suite: `test/evidence-issuer.test.js`.
+
 **Integrity + signing** — `integrity.js` (per-install HMAC for `last-scan.json`), `rule-pack-signing.js`. The HMAC key lives at `$XDG_CONFIG_HOME/agentic-security/scan-key`; override via `$AGENTIC_SECURITY_HMAC_KEY`. Premortem-derived; do not regress to hostname-derived.
 
 **Rule lifecycle** — `custom-rules.js` (YAML pattern DSL), `rule-overrides.js` (`disable:` gated on signature), `rule-packs.js`, `rule-synthesis.js` (proposes suppressions from triage feedback), `ruleset-version.js`.
@@ -139,6 +141,178 @@ one was caught by the module's own test, not in review.
 - **No throwing.** Every annotation in `engine.js` is wrapped `try { … } catch (_) {}`. Your annotator must degrade gracefully — set `null` on the field and continue.
 - **Dead-module test.** `npm run test:lifecycle` fails the build if you export a public symbol from a posture module that no other source file imports. Wire it in `engine.js` (or allowlist it with a written reason in `test/no-dead-modules.test.js`).
 
+## Assurance contracts, baseline and rollout config — `assurance/` (9 modules)
+
+Foundation for the differentiation work (CORE-001, CORE-002, CORE-004). All of it is pure or read-only, and **nothing in it is wired into `engine.js` or the scan/report path**: a default scan is byte-for-byte unaffected, which `test/posture/assurance-config.test.js` pins. Consumers (X-201 and later) import it directly.
+
+- **`identity.js`**: ids for evidence records. Reuses `canonicalJson` (`evidence-bundle.js`) and `computeStableId` (`stable-id.js`, a hypothesis id is a finding's stable id). An id is a hash over an **allowlist** of semantic fields, so clocks (`createdAt`) and migration bookkeeping can never reach it. Prefixes `vrec/obind/capd/rlab/rev` are distinct from lineage's, and nothing here imports `lineage/` (a test checks that).
+- **`schema-kit.js`**: validator primitives. Closed-world (unknown fields rejected), typed error codes, supported major version 1 only, `sha256:<64 hex>` digests.
+- **`verification-record.js`**: the one verification record. Six distinct outcomes, a SEPARATE repair status, four evidence kinds. Structural rules: a model can only produce `inference`; `confirmed` needs referenced trusted-runtime-proof or independent-adjudication evidence; `confirmationLevel` must equal the level derived from the evidence (a forged level fails); `refuted` needs an applicable non-model oracle, valid preconditions and proving evidence.
+- **`contracts.js`**: observation binding (references a lineage observation by id only; absence in a sampled observation cannot establish `blocked`), capability decision (only runner/proxy mediation with a backend and an active-probe digest may claim `enforced`; a hook or in-process check never can), routing label (a decided label must name an adjudication or trusted-execution source), release evidence (`complete` is derived, never trusted), and `validateRecordSet` for duplicate ids, dangling references and conflicting claims.
+- **`migrations.js`**: explicit v1 adapters from legacy shapes (proof tier, boolean verified, egress decision, attestation, lineage observation) and a legacy view back out. Evidence can be lost, never invented: a legacy `true` is `inconclusive`, `proof-failed` is `inconclusive` not `refuted`, and the only route to `confirmed` is an explicit `trustedRunner` assertion bound to a commit. The legacy view's `verified` is `true` only for confirmed and `false` only for refuted, otherwise `null`.
+- **`config.js`**: the unified feature configuration. Reuses the env/`.agentic-security/*.yml` mechanism. Precedence: kill switch (`AGENTIC_SECURITY_NO_ASSURANCE` or `AGENTIC_SECURITY_NO_<FEATURE>`) > explicit override > `AGENTIC_SECURITY_ASSURANCE_<FEATURE>` > `.agentic-security/assurance.yml` > default (everything off). **A project file can never enable a `high-risk-execution` feature** (the file lives in the scanned repo); invalid configuration fails closed; unsupported platforms return a typed `unsupported` with the disclosure. `runFeature` returns typed `blocked`/`unsupported`/`degraded`/`disabled` results and never prompts.
+- **`bounded-io.js`**: `guardedModelCall` is the only route for new model/network calls. It owns no HTTP client (the transport is injected): feature gate, then `evaluateEgress` BEFORE the payload exists, then `redactPayload`, then the request-size limit, then deadline plus bounded retries, then output cap, with every decision appended to the existing egress audit chain. `readFileBounded`, `capOutput`, `withDeadline`, `retryBounded` enforce the limits `config.js` claims; `maxMemoryMiB` is carried for a runner and disclosed as not enforced here.
+- **`baseline.js`, `baseline-inventory.js`**: baseline capture (`scripts/baseline-capture.mjs`, `npm run baseline:capture`). Read-only; records HEAD, dirty paths, exact source and bundle digests, tool versions, entry points, the seven mappings and an 18-entry capability inventory (implemented / partial / unsupported / unmeasured, every path and exported symbol verified at capture time, a missing one is a reported problem). Unknown facts are `{status:'unknown', reason}` with no value. `evaluateBaseline` invalidates exactly the capabilities whose cited files changed and lists unrelated user changes as retained/introduced. The manifest is machine-specific, so it is generated on demand and not committed. When you change a capability's source or tests, update its inventory entry in the same change.
+
+Tests: `test/posture/assurance-{baseline,contracts,config}.test.js`, all in `test:posture`.
+
+## One verification record, trusted oracles and replay (X-201, X-202, X-203)
+
+Built on `assurance/` (the record schema, migrations, config) and `sandbox/trust-boundary.js` (the boundary). Three
+directories, all consumed rather than wired into the default scan: a default scan is unchanged, and every addition to an
+existing output is an additive field.
+
+**`verification/emit.js`: the one emit function (X-201).** `emitVerification(surface, source, ctx)` is what every
+verification surface calls to get the version-1 record (`{ ok, record, legacy, errors }`, never throws, validated before it
+returns). Surfaces and where they call it: `fix-verify.js` (`verificationRecord` on the result, which the MCP `verify_fix` and
+`apply_fix` tools forward), `fix-verify-loop.js`, `execution-proof.js` (`proveFinding` result), `verifier.js`
+(`verifierVerificationRecords`, called by the CLI `verify` command into its `verifier-runs/` run record, never onto the findings that
+are written back to `last-scan.json`), `autopilot.js` (`rec.verificationRecord`, `commit` option), `discovery/index.js` (hunt:
+`verificationRecords`, advisory) and `oracles/oracle.js` (the `oracle` surface). The rule for every mapping: evidence is lost,
+never invented, so no legacy surface can reach `confirmed` or `refuted`. A PoC run under the older sandbox path is `inconclusive`
+(not a trusted runner; `proof-failed` is a triage signal, not a refutation), a static re-scan with no exploit oracle is `not-run`,
+a family with no oracle is `unsupported`, a harness failure is `error`, a model verdict is `inference` evidence only. Only
+`oracle` emissions carry trusted-runner evidence, because only `oracles/oracle.js` builds them.
+
+Legacy consumers: nothing existing was renamed or removed. For a consumer that wants a status or a boolean, `toLegacyVerificationView`
+(`assurance/migrations.js`, also returned as `legacy`) maps `verified` to `true` only for `confirmed` and `false` only for `refuted`,
+`null` for the other four, and carries `status` with the real outcome name, so a skipped check can never read as a pass and an unrun
+check never as a failure. Native vocabularies keep their own fields (`proofTier`, `verifier_verdict`, autopilot `outcome`, fix-verify
+`ok`); the record sits beside them as `verificationRecord`. A boolean `true` migrated from a legacy record is `inconclusive`.
+
+**`oracles/` (X-202).** `oracle.js` is the adapter contract (`validateOracleSpec`, `defineOracle`) and the runner (`runOracle`).
+`adapters.js` holds the five class adapters (injection-execution, authorization-decision, state-transition,
+side-effect-reachability, parser-resource), `registry.js` the frozen registry and `oracleManifest()`, the machine-readable
+description X-208 gates on (class, prerequisites, platforms with an honest per-platform status, budgets, negative controls,
+fixture locations, limitations, logic digest). Fixtures: `test/fixtures/oracles/<class>/{positive,negative,inconclusive}`.
+- A run is: feature gate (`verification-oracles`, off by default, operator-only), request validation (closed-world: labels,
+  verdicts and receipts are never accepted; reserved `__oracle_*` names and path escapes are refused), prerequisite check
+  (an unmet one is `unsupported` with a typed reason and the target is never executed), a fresh workspace plus a verifier-owned
+  evidence directory outside it, the target through `runInBoundary` ONLY (a test pins that `oracle.js` imports no other way to
+  run code), a digest check of the adapter's own harness (a target that rewrote it makes the run `error`), then verifier-side
+  interpretation of what the run left behind, read after the whole process tree is dead. The settled status comes from
+  `settleVerification` with `observedBy: 'verifier'` evidence; a decided result (`confirmed`/`refuted`) additionally needs an
+  exact commit, else it is held at `inconclusive`.
+- `refuted` needs the adapter's own precondition (a benign control passed); a target that failed to load, exited early or never
+  reported is `inconclusive`. A run cut by its deadline decides nothing except for the parser/resource class, where the supervisor's
+  own deadline observation IS the measurement.
+- Receipts are issued only by `runOracle` (a WeakSet records them; they are deep-frozen; a copy or hand-built one is not
+  `isIssuedReceipt`). They carry the observed output (capped), the logic digest, sanitized environment metadata (an allowlist: no
+  hostname, paths or environment values) and the record id. Unsigned: signing belongs to the signer domain.
+- Platforms: macOS (userspace backend) is the only host these have been executed on. Linux is declared `unverified` in the
+  manifest and cannot be `supported`; today the boundary refuses to run on the namespace backend, which the runner reports as
+  `unsupported`. Changing what an adapter asserts means bumping its `version` (the harness text and version feed `logicDigest`).
+- KNOWN LIMIT: the target is imported into the harness process. A target written to recognise the oracle's payload and forge the
+  effect artifact is not distinguishable from a real injection; the oracle bounds the effect it tests, it is not a defence
+  against a target built to fool it. Tamper controls cover what a worker or target can do to adapter logic, labels, receipts and
+  status text.
+
+**`replay/replay.js` (X-203).** A replay manifest pins the repository commit, the patch hash, the fixture hash, the toolchain
+(runtime version, platform, architecture, and a container digest when there is one), the oracle id, version and logic digest, the
+inputs and the budgets. It is a description of an oracle run, not a second runner: `replayManifest` ends in `runOracle`, so the
+supervised process tree, output cap and cleanup are the existing ones. It rejects, and nothing executes, on a content hash that does
+not match, an oracle that changed since the manifest was made, a scope wider than "exactly the named oracle, no network,
+workspace-only writes", a budget over the oracle's ceiling, an unsafe file path or an unknown field. Missing toolchain, container
+runtime or image, a denied network (acquisition is never attempted: this build fetches nothing), a disabled feature or a boundary
+that cannot run are typed prerequisites with `resumable` set honestly; the attempt is parked (`awaiting-prerequisites`) and
+`resume` re-evaluates the prerequisites against the real host (a claim that they are met does nothing). Outcome while parked is
+`not-run` (or `unsupported` when this build can never meet it, such as container execution, which is not implemented), with no
+evidence; nothing is substituted for the execution that did not happen. Toolchain identity is exact. Persistence of attempts is
+the caller's (the attempt object is plain data). Suites: `test/verification/{verification-record,oracle-adapters,replay-manifest}.test.js`
+(`npm run test:verification`).
+
+## Patch-negative verification and non-taint classes (X-204, X-205)
+
+Same posture as the three directories above: consumed, not wired into the default scan, every output addition additive, and
+nothing changes with the feature flags off. Suites: `test/verification/{patch-negative,non-taint-classes}.test.js`
+(`npm run test:verification`).
+
+**`verification/patch-negative.js` (X-204).** `verifyPatchNegative(req, { config, runOptions })` is `verified-fix` only when four
+`replayManifest` runs (so each is pinned, boundary-confined and receipted) show: the exploit oracle CONFIRMS on the original
+revision, REFUTES on original-plus-diff, and the `functional-regression` oracle (the requester's declared cases) is clean on the
+original (a baseline: wrong expectations are reported, not blamed on the patch) and on the patched revision. It stops at the first
+non-passing step and names it: the result carries `incompleteStep` and a typed `failureCode` (`original-not-reproduced`,
+`patched-still-exploitable`, `patched-build-broken`, `functional-omitted`, `functional-baseline-invalid`,
+`functional-regression-detected`, `oracle-changed`, `revision-unbound`, `prerequisite-unmet` (resumable where stated),
+`environment-mismatch`, `promotion-refused`) and a `summary` that says what was and was not exercised. Gate: the
+`patch-negative-verification` feature (high-risk execution, operator-only, off by default) plus `verification-oracles`.
+Wiring: `fix-verify.js` (`verifyFix({ patchNegative, assuranceConfig })` adds `patchNegative` and `fixStatus`, and `ok` requires
+`verified-fix`), `fix-verify-loop.js` (a `patchNegative` leg and the `verified-fix` verdict) and `fix/apply-fix-service.js`
+(`applyVerifiedFix({ patchNegative })` writes only a promoted patch and returns `repairRecords`). With the flag off or no request,
+those return exactly what they did before.
+
+**`verification/patch-promotion.js`.** `promotePatch({ proposal, receipts })` re-derives the diff digest and revision from the
+PROPOSAL and refuses any receipt that was not issued by `runOracle` (`isIssuedReceipt`: copies and hand-built receipts fail), that
+covers different content than the exact diff on the original revision, that was issued for another commit or hypothesis, whose
+oracle or inputs differ between the original and patched runs, whose environment identity differs, or that is reused in two roles.
+Receipts are valid inside the verifier's process only; carrying a promotion across processes needs a signing domain (not here).
+
+**`verification/repair-records.js`.** The CORE-002 record has one repair status and no value for a rejection, so the history is an
+append-only ledger of separate, frozen, chained records: `proposed`, `rejected`, `promoted` (only through `recordPromotion`, which
+accepts nothing but a result `promotePatch` returned `ok`), `applied` (only after a promotion for that exact diff) and
+`rolled-back`. `verificationRepairFor`/`withRepairStatus` map the ledger onto the CORE-002 `repair` field (`replay-verified` carries the
+patched-negative record id); a rejection leaves it at `proposed` because the foundation enum is not widened here. The ledger is
+returned to the caller and not persisted: persisting it would need an artifact-registry classification.
+
+**New adapters.** `replay-idempotency` (a factory receiving a recording stand-in for the effect: a request and a distinct request
+are delivered as a control, then the same request is redelivered, and the verifier counts effects) and `functional-regression`
+(declared cases against expected JSON values; the hypothesis is that behaviour REGRESSED, so a clean patch is `refuted`). Both have
+the usual positive, negative and inconclusive fixtures under `test/fixtures/oracles/`.
+
+**`oracles/scenario-classes.js` (X-205).** The supported-class manifest for non-taint defects, surfaced as
+`oracleManifest().nonTaint`: tenant authorization and privileged action (REUSE `authorization-decision`), workflow order (REUSES
+`state-transition`), bounded resource exhaustion (REUSES `parser-resource`) and replay/idempotency (the new adapter). Each class
+lists what the requester must supply, its fixtures (`test/fixtures/non-taint/<class>/{positive,negative,scenario.json}`, application-style
+code), its limitations and the report lines a reader sees; every `runOracle` result additionally carries a `disclosure`
+(prerequisites, platform statement, limitations, class report). Unsupported non-taint classes (concurrent races, CSRF, authentication
+throttling) are named with a reason. `judgeNonTaintHypothesis` is the rule that taint absence is never an input to a refutation:
+without an executed oracle of the class's own adapter with proven preconditions the outcome is `not-run` (or `unsupported`); the hunt
+mapper in `verification/emit.js` uses it. `trustedNegativeDenominator` counts only decided results of an executed oracle of an
+advertised class with proven preconditions and trusted runtime proof, and lists every exclusion with its reason (its runtime consumer is `verificationCoverage` in
+`verification/projection.js`, which the JSON report, the CLI report and the MCP/autopilot surfaces use for the trusted-negative line).
+
+Not verified: Linux (the oracle platform statements stay `unverified`); only the declared exploit scenario and functional cases are
+exercised, never the patch's correctness elsewhere.
+
+## One projection for every interface, advisory/gating separation, conformance (X-206, X-207, X-208)
+
+Same posture as the sections above: consumed, not wired into the default scan, every output addition additive and present only
+when a verification record is. Suites: `test/verification/{interface-equivalence,advisory-gating,oracle-conformance}.test.js`
+(`npm run test:verification`). Docs: `docs/guides/verification-schema-migration.md`, `docs/guides/verification-oracle-conformance.md`.
+
+**`verification/projection.js` (X-206).** `projectVerification(record, { replay })` is the ONE place a record becomes something a
+person or another tool reads: state, scope, oracle, evidence ids, replay prerequisites (derived from the record, plus the typed
+ones a replay attempt reported), a what-was-verified / what-was-not summary, the legacy boolean view, and `text` lines. The JSON
+report (`report/index.js` `normalizeFindings`), the CLI and Markdown reports (`verificationBlock`), MCP `explain_finding`,
+`verify_fix` and `apply_fix`, and the autopilot response (`serializeAutopilotResult`, used by `scripts/autopilot.mjs --json`) all
+call it; none formats its own verification text. The key is **`verificationView`**, never `verification`: a finding's existing
+`verification` field is the producer/verifier separation record (`verification-separation.js`) and a first draft of this work
+collided with it. An invalid record yields `verificationView: null` plus `verificationViewErrors`, never a guessed state. The text
+never says "safe" or "fixed" for a partial result (a lint-style test covers every state, every repair status and the wording the real
+surfaces emit; the fix-verify leg's native status word `fixed` is deliberately not echoed into a record reason). `verificationCoverage`
+wraps `trustedNegativeDenominator`. Previous output schemas are pinned in `test/fixtures/verification-compat/`.
+
+**`verification/advisory-state.js`, `verification/hypothesis-promotion.js` (X-207).** Hunt (`discovery/`) is advisory.
+`writeAdvisoryState` is the only way advisory code writes: a closed file-name allowlist (the one hunt memory file), authoritative names
+refused, write to a temp file and rename (a symlink or hard link planted at the target is replaced, never written through), the state
+directory must resolve inside the project root. `discovery/memory.js` `saveMemory` uses it. `normalizeFindings` excludes any hunt
+hypothesis (`parser: DISCOVERY` or a `discovery` object) from every finding list and exit code and records `advisoryExcluded`.
+`promoteHypothesis({ hypothesis, result, policy })` is the only crossing: it verifies (not just checks presence of) a receipt issued by
+`runOracle` (`isIssuedReceipt`), bound to the hypothesis and an exact commit and to a valid record settled `confirmed` at the
+`runtime-confirmed` level, applies an EXPLICIT policy (fail-closed on an unknown key; the receipt rules are mandatory and cannot be
+waived; `minConfidence`/`minAgreement` can only add a requirement), reuses `verification-separation.js` for hunter != verifier, and
+returns a frozen audit record for every decision (`promoted`, `rejected`, `unsupported`, `inconclusive`) with no clock in it.
+`runDiscovery` calls it only when `opts.promote = { policy, verify }` is given. The audit record is returned, not persisted:
+persisting needs an artifact-registry classification and a signing domain, which are not decided here.
+
+**`oracles/conformance.js` and `scripts/verification-conformance-check.mjs` (X-208).** One contract over every registered adapter:
+static (class scope, budgets under `BUDGET_CEILINGS`, negative controls with an on-disk fixture, verifier-side evidence logic bound by
+a digest, fixtures and logic pinned in `test/fixtures/oracles/conformance-pins.json`) and execution (state mappings, issued and frozen
+receipts, three tamper attempts, an unavailable prerequisite, cancellation, replay). Wired into `scripts/release-check.mjs`
+(`verification-conformance-gate`, in `RELEASE_GROUPS['benches-b']`) and, static half only, the pre-push gate
+(`verification-conformance-static`). Where the boundary cannot run, execution is reported `not-run`, never passed; `--require-execution`
+makes that a failure. A new adapter must be pinned deliberately (`--update-pins`).
+
 ## Execution-proof tiers (R2)
 
 `proof-tier.js` + `execution-proof.js` add a fourth axis to a finding's