owlrunkit 0.19.1 → 0.19.2

package/scripts/runkit-contract/formal-workflow.mjs

@@ -13,6 +13,8 @@ import {
   validateCoreArtifact,
 } from "./core-contract.mjs";
 import { runFinalize } from "./finalize.mjs";
+import { preflightFormalEnvelopeV1 } from "./formal-preflight.mjs";
+import { readWorkspaceJsonBounded } from "./onboarding-doctor.mjs";
 import { derivedVerificationContext } from "./lifecycle-orchestration.mjs";
 import { withControlTransaction } from "./lease-lifecycle.mjs";
 import {
@@ -30,12 +32,18 @@ import {
 } from "./snapshot.mjs";
 import {
   freezeSourceCandidateWithinControlTransactionV2,
+  previewSourceCandidateWithinControlTransactionV2,
+  verifySourceCandidateDetailsV2,
   verifySourceCandidateV2,
 } from "./source-candidate.mjs";
 import { validateReceiptLineage } from "./receipt-lineage.mjs";
-import { verificationContextFingerprint } from "./verification-context.mjs";
+import {
+  validateVerificationContext,
+  verificationContextFingerprint,
+} from "./verification-context.mjs";
 import {
   runVerificationEnvelopeV1,
+  validateEnvelopeSourceCandidateBoundaryV1,
   validateVerificationEnvelopeV1,
   verifyVerificationEnvelopeReceiptV1,
 } from "./verification-envelope.mjs";
@@ -126,6 +134,17 @@ function canonicalJson(value) {
   return encoded;
 }
 
+function formalCheckHash(value) {
+  return `sha256:${sha256(canonicalJson(value))}`;
+}
+
+function hasExactKeys(value, keys) {
+  return Boolean(value)
+    && typeof value === "object"
+    && !Array.isArray(value)
+    && canonicalJson(Object.keys(value).sort()) === canonicalJson([...keys].sort());
+}
+
 function readRegularJson(filePath, label) {
   const stat = lstatSync(filePath);
   if (stat.isSymbolicLink() || !stat.isFile()) {
@@ -137,6 +156,20 @@ function readRegularJson(filePath, label) {
   return JSON.parse(readFileSync(filePath, "utf8"));
 }
 
+function readWorkspaceRegularJson(workspaceRoot, filePath, label) {
+  try {
+    return readWorkspaceJsonBounded(
+      workspaceRoot,
+      relativeToWorkspace(workspaceRoot, filePath),
+      { maxBytes: 64 * 1024 * 1024, maxNodes: 2_000_000 },
+    );
+  } catch (error) {
+    throw new Error(`${label} must be bounded regular JSON inside the workspace.`, {
+      cause: error,
+    });
+  }
+}
+
 function writeOrResumeExactJson(filePath, value, label) {
   if (!existsSync(filePath)) {
     writeJsonExclusiveAtomically(filePath, value);
@@ -335,7 +368,224 @@ export function validateLegacyVerificationSideEffectsV1({ commandArgv }) {
   };
 }
 
-function readChecks(executionRoot) {
+const FORMAL_CHECK_V2_KEYS = [
+  "schemaVersion",
+  "runId",
+  "checkId",
+  "sequence",
+  "status",
+  "candidatePath",
+  "candidateSha256",
+  "payloadSha256",
+  "sourceFingerprint",
+  "verificationContext",
+  "verificationContextFingerprint",
+  "snapshotRequestPath",
+  "snapshotPath",
+  "commandExitCode",
+  "verificationCommandPolicy",
+  "envelopePath",
+  "envelopeSha256",
+  "envelopeReceiptPath",
+  "envelopeReceiptSha256",
+  "envelopeFormalEligible",
+  "failureCategory",
+  "failureDetail",
+  "finalized",
+  "authorizationGranted",
+  "formalCheckSha256",
+];
+
+const FORMAL_POLICY_V2_KEYS = [
+  "schemaVersion",
+  "mode",
+  "riskClassification",
+  "profileCommandIds",
+  "envelopeSha256",
+  "envelopeReceiptSha256",
+  "authorizationGranted",
+];
+
+function expectedFormalPath(workspaceRoot, executionRoot, ...segments) {
+  return relativeToWorkspace(
+    workspaceRoot,
+    path.join(executionRoot, ...segments),
+  );
+}
+
+function validateFormalCheckV2({
+  workspaceRoot,
+  executionRoot,
+  runId,
+  fileName,
+  check,
+}) {
+  const checkId = path.basename(fileName, ".json");
+  const { formalCheckSha256, ...checkBody } = check ?? {};
+  if (
+    !hasExactKeys(check, FORMAL_CHECK_V2_KEYS)
+    || check.schemaVersion !== "OwlCodaRunKitFormalCheckV2"
+    || check.runId !== runId
+    || check.checkId !== checkId
+    || !Number.isSafeInteger(check.sequence)
+    || check.sequence < 1
+    || !new Set(["formal_check_passed", "formal_check_failed"]).has(check.status)
+    || check.finalized !== false
+    || check.authorizationGranted !== false
+    || !/^sha256:[a-f0-9]{64}$/u.test(formalCheckSha256)
+    || formalCheckSha256 !== formalCheckHash(checkBody)
+  ) {
+    throw new Error(`Formal Check V2 contract is invalid: ${fileName}`);
+  }
+  const expected = {
+    candidatePath: expectedFormalPath(
+      workspaceRoot,
+      executionRoot,
+      "source-candidates",
+      `${checkId}.json`,
+    ),
+    snapshotRequestPath: expectedFormalPath(
+      workspaceRoot,
+      executionRoot,
+      "formal-check-requests",
+      `${checkId}.json`,
+    ),
+    snapshotPath: expectedFormalPath(
+      workspaceRoot,
+      executionRoot,
+      "snapshots",
+      `${checkId}-snapshot.json`,
+    ),
+    envelopePath: expectedFormalPath(
+      workspaceRoot,
+      executionRoot,
+      "formal-envelopes",
+      `${checkId}.json`,
+    ),
+    envelopeReceiptPath: expectedFormalPath(
+      workspaceRoot,
+      executionRoot,
+      "verification-envelopes",
+      checkId,
+      "verification-envelope-receipt.json",
+    ),
+  };
+  for (const [field, expectedPath] of Object.entries(expected)) {
+    if (check[field] !== expectedPath) {
+      throw new Error(`Formal Check V2 ${field} is invalid: ${fileName}`);
+    }
+  }
+  const candidate = verifySourceCandidateDetailsV2({
+    workspaceRoot,
+    candidatePath: check.candidatePath,
+    requireCurrentWorkspace: false,
+  });
+  const candidateDocument = candidate.candidateDocument;
+  if (
+    candidate.gate.status !== "valid"
+    || candidateDocument === null
+    || candidateDocument.runId !== runId
+    || candidateDocument.candidateId !== checkId
+    || candidateDocument.candidateSha256 !== check.candidateSha256
+    || candidateDocument.payload.sha256 !== check.payloadSha256
+    || candidateDocument.sourceFingerprint.sha256 !== check.sourceFingerprint
+  ) {
+    throw new Error(`Formal Check V2 candidate binding is invalid: ${fileName}`);
+  }
+  const context = validateVerificationContext(check.verificationContext);
+  if (
+    !context.valid
+    || verificationContextFingerprint(check.verificationContext)
+      !== check.verificationContextFingerprint
+  ) {
+    throw new Error(`Formal Check V2 verification context is invalid: ${fileName}`);
+  }
+  if (
+    !hasExactKeys(check.verificationCommandPolicy, FORMAL_POLICY_V2_KEYS)
+    || check.verificationCommandPolicy.schemaVersion
+      !== "OwlCodaRunKitFormalVerificationCommandPolicyV1"
+    || check.verificationCommandPolicy.mode !== "verification_envelope_v1"
+    || check.verificationCommandPolicy.riskClassification
+      !== "enforced_verification_envelope"
+    || canonicalJson(check.verificationCommandPolicy.profileCommandIds) !== "[]"
+    || check.verificationCommandPolicy.envelopeSha256 !== check.envelopeSha256
+    || check.verificationCommandPolicy.envelopeReceiptSha256
+      !== check.envelopeReceiptSha256
+    || check.verificationCommandPolicy.authorizationGranted !== false
+  ) {
+    throw new Error(`Formal Check V2 command policy is invalid: ${fileName}`);
+  }
+  const envelope = readWorkspaceRegularJson(
+    workspaceRoot,
+    path.join(workspaceRoot, check.envelopePath),
+    "Formal Verification Envelope",
+  );
+  const validatedEnvelope = validateVerificationEnvelopeV1({
+    workspaceRoot,
+    envelope,
+    requireCurrentEnvironment: false,
+  });
+  if (validatedEnvelope.envelopeSha256 !== check.envelopeSha256) {
+    throw new Error(`Formal Check V2 envelope binding is invalid: ${fileName}`);
+  }
+  const envelopeReceiptPath = path.join(workspaceRoot, check.envelopeReceiptPath);
+  const envelopeReceipt = readWorkspaceRegularJson(
+    workspaceRoot,
+    envelopeReceiptPath,
+    "Verification Envelope receipt",
+  );
+  const verifiedEnvelope = verifyVerificationEnvelopeReceiptV1({
+    workspaceRoot,
+    receiptPath: envelopeReceiptPath,
+    requireCurrentSource: false,
+  });
+  if (
+    verifiedEnvelope.receiptSha256 !== check.envelopeReceiptSha256
+    || verifiedEnvelope.envelopeSha256 !== check.envelopeSha256
+    || verifiedEnvelope.formalEligible !== check.envelopeFormalEligible
+  ) {
+    throw new Error(`Formal Check V2 envelope receipt binding is invalid: ${fileName}`);
+  }
+  const snapshot = readWorkspaceRegularJson(
+    workspaceRoot,
+    path.join(workspaceRoot, check.snapshotPath),
+    "Formal snapshot",
+  );
+  const snapshotGate = verifySnapshotEvidence({
+    workspaceRoot,
+    runId,
+    snapshot,
+    requirePassed: false,
+  });
+  if (
+    !snapshotGate.valid
+    || snapshot.snapshotId !== `${checkId}-snapshot`
+    || snapshot.verificationContextFingerprint !== check.verificationContextFingerprint
+    || snapshot.command.exitCode !== check.commandExitCode
+    || snapshot.command.exitCode !== (envelopeReceipt.formalEligible ? 0 : 2)
+  ) {
+    throw new Error(`Formal Check V2 snapshot binding is invalid: ${fileName}`);
+  }
+  const expectedStatus = snapshot.status === "snapshot_passed"
+    && envelopeReceipt.formalEligible
+    ? "formal_check_passed"
+    : "formal_check_failed";
+  const expectedFailure = classifyFormalEnvelopeFailureV1({
+    envelopeReceipt,
+    snapshotStatus: snapshot.status,
+    finalStatus: expectedStatus,
+  });
+  if (
+    check.status !== expectedStatus
+    || check.failureCategory !== expectedFailure.failureCategory
+    || check.failureDetail !== expectedFailure.failureDetail
+  ) {
+    throw new Error(`Formal Check V2 derived fields are invalid: ${fileName}`);
+  }
+  return check;
+}
+
+function readChecks(workspaceRoot, executionRoot, runId) {
   const root = checkRoot(executionRoot);
   if (!existsSync(root)) return [];
   const stat = lstatSync(root);
@@ -349,11 +599,27 @@ function readChecks(executionRoot) {
       if (entry.isSymbolicLink() || !entry.isFile()) {
         throw new Error(`Formal check must be a regular file: ${entry.name}`);
       }
-      const value = readJson(path.join(root, entry.name));
+      const value = readWorkspaceRegularJson(
+        workspaceRoot,
+        path.join(root, entry.name),
+        "Formal check",
+      );
+      if (value.schemaVersion === "OwlCodaRunKitFormalCheckV2") {
+        return validateFormalCheckV2({
+          workspaceRoot,
+          executionRoot,
+          runId,
+          fileName: entry.name,
+          check: value,
+        });
+      }
       if (
         value.schemaVersion !== "OwlCodaRunKitFormalCheckV1"
+        || value.runId !== runId
+        || value.checkId !== path.basename(entry.name, ".json")
         || !Number.isSafeInteger(value.sequence)
         || value.sequence < 1
+        || value.authorizationGranted !== false
       ) {
         throw new Error(`Formal check contract is invalid: ${entry.name}`);
       }
@@ -362,6 +628,60 @@ function readChecks(executionRoot) {
     .sort((left, right) => left.sequence - right.sequence);
 }
 
+export function readFormalChecksV1({ workspaceRoot, executionRoot, runId }) {
+  return readChecks(realpathSync(workspaceRoot), executionRoot, runId);
+}
+
+export function classifyFormalEnvelopeFailureV1({
+  envelopeReceipt,
+  snapshotStatus,
+  finalStatus,
+}) {
+  if (finalStatus === "formal_check_passed") {
+    return { failureCategory: null, failureDetail: null };
+  }
+  if (
+    envelopeReceipt.status === "policy_backend_unavailable"
+    || envelopeReceipt.commandExecuted === false
+  ) {
+    return {
+      failureCategory: "envelope_capability_missing",
+      failureDetail: envelopeReceipt.backend?.reason ?? "enforcement_backend_unavailable",
+    };
+  }
+  const phases = envelopeReceipt.phases ?? [];
+  const launched = phases.find(phase => phase.launchError !== null && phase.launchError !== undefined);
+  if (launched) {
+    return {
+      failureCategory: "toolchain_resolution_failed",
+      failureDetail: `phase_${launched.name}_launch_failed`,
+    };
+  }
+  if (snapshotStatus === "invalidated_by_target_write") {
+    return {
+      failureCategory: "envelope_capability_missing",
+      failureDetail: "verification_evidence_snapshot_not_current",
+    };
+  }
+  if (
+    phases.some(phase => phase.timedOut || phase.outputOverflow)
+    || envelopeReceipt.source?.unchanged === false
+    || envelopeReceipt.cleanup?.teardownCompleted === false
+    || (envelopeReceipt.cleanup?.terminatedProcessIds?.length ?? 0) > 0
+    || (envelopeReceipt.cleanup?.remainingProcessIds?.length ?? 0) > 0
+    || (envelopeReceipt.cleanup?.issues?.length ?? 0) > 0
+  ) {
+    return {
+      failureCategory: "envelope_capability_missing",
+      failureDetail: "verification_envelope_constraints_not_satisfied",
+    };
+  }
+  return {
+    failureCategory: "source_check_failed",
+    failureDetail: "verification_command_returned_nonzero",
+  };
+}
+
 function resumeOrFreezeCandidate({
   workspaceRoot,
   executionRoot,
@@ -375,30 +695,41 @@ function resumeOrFreezeCandidate({
     `${checkId}.json`,
   );
   if (!existsSync(candidatePath)) {
+    const candidate = freezeSourceCandidateWithinControlTransactionV2({
+      workspaceRoot,
+      runId,
+      workItemId,
+      candidateId: checkId,
+    });
+    if (candidate.status !== "source_candidate_frozen") {
+      return { candidate, candidateDocument: null, resumed: false };
+    }
+    const verified = verifySourceCandidateDetailsV2({
+      workspaceRoot,
+      candidatePath: candidate.candidatePath,
+    });
+    if (verified.gate.status !== "valid" || verified.candidateDocument === null) {
+      throw new Error(`New Formal source candidate failed verification: ${checkId}`);
+    }
     return {
-      candidate: freezeSourceCandidateWithinControlTransactionV2({
-        workspaceRoot,
-        runId,
-        workItemId,
-        candidateId: checkId,
-      }),
+      candidate,
+      candidateDocument: verified.candidateDocument,
       resumed: false,
     };
   }
-  const candidateDocument = readRegularJson(
-    candidatePath,
-    "Formal source candidate",
-  );
   const candidateRelativePath = relativeToWorkspace(
     workspaceRoot,
     candidatePath,
   );
-  const gate = verifySourceCandidateV2({
+  const verified = verifySourceCandidateDetailsV2({
     workspaceRoot,
     candidatePath: candidateRelativePath,
   });
+  const gate = verified.gate;
+  const candidateDocument = verified.candidateDocument;
   if (
     gate.status !== "valid"
+    || candidateDocument === null
     || candidateDocument.runId !== runId
     || candidateDocument.candidateId !== checkId
     || candidateDocument.discovery?.fromLease !== workItemId
@@ -421,6 +752,7 @@ function resumeOrFreezeCandidate({
       ownedPaths: [...candidateDocument.sourceManifest.ownedPaths],
       authorizationGranted: false,
     },
+    candidateDocument,
     resumed: true,
   };
 }
@@ -464,6 +796,7 @@ function resumeSnapshot({
     workspaceRoot,
     runId,
     snapshot,
+    requirePassed: false,
   });
   if (
     !evidence.valid
@@ -577,7 +910,7 @@ function recordFormalCheckWithinControlTransaction({
     ? readRegularJson(receiptPath, "Formal check receipt")
     : null;
   const sequence = existingReceipt?.sequence
-    ?? readChecks(executionRoot).length + 1;
+    ?? readChecks(root, executionRoot, runId).length + 1;
   const status = snapshot.status === "snapshot_passed"
     ? "formal_check_passed"
     : "formal_check_failed";
@@ -646,11 +979,137 @@ async function recordFormalEnvelopeCheckWithinControlTransaction({
   const root = realpathSync(workspaceRoot);
   const { executionRoot, pinGate } = loadActiveExecution(root, runId);
   if (pinGate.status !== "valid") return { ...pinGate, authorizationGranted: false };
-  const validatedEnvelope = validateVerificationEnvelopeV1({
+  const structurallyValidatedEnvelope = validateVerificationEnvelopeV1({
     workspaceRoot: root,
     envelope,
+    requireCurrentEnvironment: false,
   });
   const receiptPath = path.join(checkRoot(executionRoot), `${checkId}.json`);
+  if (existsSync(receiptPath)) {
+    const existing = readChecks(root, executionRoot, runId)
+      .find(check => check.checkId === checkId);
+    if (
+      existing?.schemaVersion !== "OwlCodaRunKitFormalCheckV2"
+      || existing.envelopeSha256 !== structurallyValidatedEnvelope.envelopeSha256
+    ) {
+      throw new Error(`Existing Formal check differs from the resumed command: ${checkId}`);
+    }
+    const current = verifySourceCandidateDetailsV2({
+      workspaceRoot: root,
+      candidatePath: existing.candidatePath,
+    });
+    if (
+      current.gate.status !== "valid"
+      || current.candidateDocument?.discovery?.fromLease !== workItemId
+    ) {
+      throw new Error(`Existing Formal check source differs from the resumed command: ${checkId}`);
+    }
+    return {
+      ...existing,
+      exitCode: existing.status === "formal_check_passed" ? 0 : 2,
+      checkReceiptPath: relativeToWorkspace(root, receiptPath),
+      resumed: true,
+    };
+  }
+  const envelopePath = path.join(
+    executionRoot,
+    "formal-envelopes",
+    `${checkId}.json`,
+  );
+  if (existsSync(envelopePath)) {
+    const existingEnvelope = readRegularJson(
+      envelopePath,
+      "Formal Verification Envelope",
+    );
+    if (
+      canonicalJson(existingEnvelope)
+        !== canonicalJson(structurallyValidatedEnvelope.envelope)
+    ) {
+      throw new Error("Existing Formal Verification Envelope differs from the resumed command.");
+    }
+  }
+  const candidatePath = path.join(
+    executionRoot,
+    "source-candidates",
+    `${checkId}.json`,
+  );
+  const requestPath = path.join(
+    executionRoot,
+    "formal-check-requests",
+    `${checkId}.json`,
+  );
+  const snapshotPath = path.join(
+    executionRoot,
+    "snapshots",
+    `${checkId}-snapshot.json`,
+  );
+  const envelopeReceiptPath = path.join(
+    executionRoot,
+    "verification-envelopes",
+    checkId,
+    "verification-envelope-receipt.json",
+  );
+  if (
+    !existsSync(candidatePath)
+    && [requestPath, snapshotPath, envelopeReceiptPath].some(existsSync)
+  ) {
+    throw new Error("Incomplete Formal check artifacts require a new check id.");
+  }
+  if (existsSync(snapshotPath) && !existsSync(requestPath)) {
+    throw new Error("Incomplete Formal snapshot artifacts require a new check id.");
+  }
+  const preflight = preflightFormalEnvelopeV1({
+    workspaceRoot: root,
+    envelope: structurallyValidatedEnvelope.envelope,
+  });
+  if (preflight.status === "blocked") return preflight;
+  const validatedEnvelope = validateVerificationEnvelopeV1({
+    workspaceRoot: root,
+    envelope: structurallyValidatedEnvelope.envelope,
+  });
+  const preview = previewSourceCandidateWithinControlTransactionV2({
+    workspaceRoot: root,
+    runId,
+    workItemId,
+  });
+  if (preview.status !== "source_candidate_previewed") return preview;
+  validateEnvelopeSourceCandidateBoundaryV1({
+    envelope: validatedEnvelope.envelope,
+    sourceManifest: preview.sourceManifest,
+  });
+  const context = derivedVerificationContext(root);
+  const commandArgv = [
+    realpathSync(process.execPath),
+    VERIFICATION_ENVELOPE_CHECKER,
+    "--workspace",
+    root,
+    "--receipt",
+    envelopeReceiptPath,
+  ];
+  const buildSnapshotRequest = sourceManifest => ({
+    schemaVersion: "OwlCodaRunKitSnapshotRequestV1",
+    snapshotId: `${checkId}-snapshot`,
+    mode: "project",
+    targetRoot: root,
+    cwd: ".",
+    executable: commandArgv[0],
+    argv: commandArgv.slice(1),
+    launcherVersion: "owlrunkit-formal-envelope-v1",
+    toolVersions: structuredClone(context.toolchains),
+    selectedPaths: sourceManifest.entries
+      .filter(entry => entry.operation !== "deleted")
+      .map(entry => entry.path)
+      .sort(),
+    statusMode: "porcelain-v1-z-untracked-all-runkit-excluded",
+    verificationContext: context,
+  });
+  const previewRequest = buildSnapshotRequest(preview.sourceManifest);
+  if (existsSync(requestPath)) {
+    const existingRequest = readRegularJson(requestPath, "Formal check request");
+    if (canonicalJson(existingRequest) !== canonicalJson(previewRequest)) {
+      throw new Error("Existing Formal check request differs from the resumed command.");
+    }
+  }
   const candidateResult = resumeOrFreezeCandidate({
     workspaceRoot: root,
     executionRoot,
@@ -661,12 +1120,15 @@ async function recordFormalEnvelopeCheckWithinControlTransaction({
   const candidate = candidateResult.candidate;
   if (candidate.status !== "source_candidate_frozen") return candidate;
   hooks.afterCandidatePersist?.();
-  const candidateDocument = readJson(path.join(root, candidate.candidatePath));
-  const envelopePath = path.join(
-    executionRoot,
-    "formal-envelopes",
-    `${checkId}.json`,
-  );
+  const candidateDocument = candidateResult.candidateDocument;
+  validateEnvelopeSourceCandidateBoundaryV1({
+    envelope: validatedEnvelope.envelope,
+    sourceManifest: candidateDocument.sourceManifest,
+  });
+  const request = buildSnapshotRequest(candidateDocument.sourceManifest);
+  if (canonicalJson(request) !== canonicalJson(previewRequest)) {
+    throw new Error("Formal source changed after preflight; create a new check id.");
+  }
   const envelopeResult = writeOrResumeExactJson(
     envelopePath,
     validatedEnvelope.envelope,
@@ -683,14 +1145,6 @@ async function recordFormalEnvelopeCheckWithinControlTransaction({
     artifactRoot: envelopeArtifactRoot,
   });
   hooks.afterEnvelopePersist?.();
-  const commandArgv = [
-    realpathSync(process.execPath),
-    VERIFICATION_ENVELOPE_CHECKER,
-    "--workspace",
-    root,
-    "--receipt",
-    envelopeReceipt.receiptPath,
-  ];
   const verificationCommandPolicy = {
     schemaVersion: "OwlCodaRunKitFormalVerificationCommandPolicyV1",
     mode: "verification_envelope_v1",
@@ -702,29 +1156,6 @@ async function recordFormalEnvelopeCheckWithinControlTransaction({
     envelopeReceiptSha256: envelopeReceipt.receiptSha256,
     authorizationGranted: false,
   };
-  const context = derivedVerificationContext(root);
-  const request = {
-    schemaVersion: "OwlCodaRunKitSnapshotRequestV1",
-    snapshotId: `${checkId}-snapshot`,
-    mode: "project",
-    targetRoot: root,
-    cwd: ".",
-    executable: verificationCommandPolicy.executable,
-    argv: verificationCommandPolicy.argv,
-    launcherVersion: "owlrunkit-formal-envelope-v1",
-    toolVersions: structuredClone(context.toolchains),
-    selectedPaths: candidateDocument.sourceManifest.entries
-      .filter((entry) => entry.operation !== "deleted")
-      .map((entry) => entry.path)
-      .sort(),
-    statusMode: "porcelain-v1-z-untracked-all-runkit-excluded",
-    verificationContext: context,
-  };
-  const requestPath = path.join(
-    executionRoot,
-    "formal-check-requests",
-    `${checkId}.json`,
-  );
   const requestResult = writeOrResumeExactJson(
     requestPath,
     request,
@@ -745,13 +1176,18 @@ async function recordFormalEnvelopeCheckWithinControlTransaction({
     ? readRegularJson(receiptPath, "Formal check receipt")
     : null;
   const sequence = existingReceipt?.sequence
-    ?? readChecks(executionRoot).length + 1;
+    ?? readChecks(root, executionRoot, runId).length + 1;
   const status = snapshot.status === "snapshot_passed"
     && envelopeReceipt.formalEligible
     ? "formal_check_passed"
     : "formal_check_failed";
-  const receipt = {
-    schemaVersion: "OwlCodaRunKitFormalCheckV1",
+  const failure = classifyFormalEnvelopeFailureV1({
+    envelopeReceipt,
+    snapshotStatus: snapshot.status,
+    finalStatus: status,
+  });
+  const receiptBody = {
+    schemaVersion: "OwlCodaRunKitFormalCheckV2",
     runId,
     checkId,
     sequence,
@@ -779,9 +1215,15 @@ async function recordFormalEnvelopeCheckWithinControlTransaction({
     envelopeReceiptPath: relativeToWorkspace(root, envelopeReceipt.receiptPath),
     envelopeReceiptSha256: envelopeReceipt.receiptSha256,
     envelopeFormalEligible: envelopeReceipt.formalEligible,
+    failureCategory: failure.failureCategory,
+    failureDetail: failure.failureDetail,
     finalized: false,
     authorizationGranted: false,
   };
+  const receipt = {
+    ...receiptBody,
+    formalCheckSha256: formalCheckHash(receiptBody),
+  };
   const receiptResult = writeOrResumeExactJson(
     receiptPath,
     receipt,
@@ -812,7 +1254,7 @@ export function recordFormalEnvelopeCheckV1(options) {
   );
 }
 
-function finalizeFormalChecksWithinControlTransaction({
+export function finalizeFormalChecksWithinControlTransaction({
   workspaceRoot,
   runId,
   finalizeId,
@@ -822,7 +1264,7 @@ function finalizeFormalChecksWithinControlTransaction({
   const root = realpathSync(workspaceRoot);
   const { executionRoot, pinGate } = loadActiveExecution(root, runId);
   if (pinGate.status !== "valid") return { ...pinGate, authorizationGranted: false };
-  const checks = readChecks(executionRoot);
+  const checks = readChecks(root, executionRoot, runId);
   if (checks.length === 0) throw new Error("Formal finish requires at least one check.");
   const latest = checks.at(-1);
   const currentCandidate = verifySourceCandidateV2({
@@ -917,6 +1359,9 @@ export function resumeCompletedFormalFinishV1({
   const closeout = readRegularJson(closeoutPath, "Formal closeout receipt");
   const gate = validateCoreArtifact(closeout.artifact);
   const payload = closeout.artifact?.payload;
+  const formalEvidenceBinding = closeout.artifact?.extensions?.[
+    "dev.owlcoda.formal-evidence"
+  ] ?? null;
   if (
     !gate.valid
     || closeout.acceptanceSha256 !== gate.acceptanceSha256
@@ -944,9 +1389,33 @@ export function resumeCompletedFormalFinishV1({
       closeoutArtifactSha256: closeout.artifactSha256,
       releasedLeaseIds: [],
       resumed: true,
+      formalEvidenceBinding: null,
       authorizationGranted: false,
     };
   }
+  if (
+    closeout.artifact.core?.coreVersion === "0.19.2"
+    && (
+      !hasExactKeys(formalEvidenceBinding, [
+        "schemaVersion",
+        "summaryPath",
+        "summarySha256",
+        "formalCheckCount",
+        "supplementalEvidenceCount",
+        "staleSupplementalEvidenceCount",
+        "authorizationGranted",
+      ])
+      || formalEvidenceBinding.schemaVersion
+        !== "OwlCodaRunKitFormalEvidenceCloseoutBindingV1"
+      || formalEvidenceBinding.summaryPath
+        !== `.owlcoda/runkit/executions/${runId}`
+          + `/formal-evidence-summaries/${finalizeId}-evidence.json`
+      || !/^[a-f0-9]{64}$/u.test(formalEvidenceBinding.summarySha256)
+      || formalEvidenceBinding.authorizationGranted !== false
+    )
+  ) {
+    throw new Error("Existing closeout Formal evidence summary binding is invalid.");
+  }
   const requestPath = path.join(
     executionRoot,
     "formal-finalize-requests",
@@ -1016,7 +1485,7 @@ export function resumeCompletedFormalFinishV1({
       "Existing closeout Formal sourceArtifact bytes changed.",
     );
   }
-  const checks = readChecks(executionRoot);
+  const checks = readChecks(root, executionRoot, runId);
   const selected = checks.filter((check) => (
     check.status === "formal_check_passed"
     && check.sourceFingerprint === active.receipt.sourceFingerprint
@@ -1046,6 +1515,7 @@ export function resumeCompletedFormalFinishV1({
       ...payload.verification.releasedLeaseIds,
     ],
     resumed: true,
+    formalEvidenceBinding,
     authorizationGranted: false,
   };
 }