@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/command-input.js

@@ -19,10 +19,17 @@ function validatePolicyInput(command, options) {
   if (command !== "policy" && options.policy) throw inputError(`Policy name is not valid for ${command}`);
 }
 
-function validateTaskCreationInput(command, options) {
+function validateContractBootstrapRepairMigrationInput(command, options) {
+  if (command !== "task-migrate-contract-bootstrap-repair") return;
+  if (!options.taskId) throw inputError("task-migrate-contract-bootstrap-repair requires --task");
+  if (!options.acknowledgeMigration) throw inputError("task-migrate-contract-bootstrap-repair requires --acknowledge-migration");
+}
+
+function validateTaskCreationInput(command, options, help = false) {
+  if (help) return;
   if (command === "bundle" && !options.taskId) throw inputError("bundle requires --task");
   if (command === "task-create" && !options.taskId) throw inputError("task-create requires --task");
-  if (command !== "task-create" && (options.preset || options.preview)) {
+  if (!["task-create", "contract-create", "contract-revise"].includes(command) && (options.preset || options.preview)) {
     throw inputError(`preset/preview options are not valid for ${command}`);
   }
   if (command === "task-create" && options.preview && !options.preset && !options.contractFile) {
@@ -31,6 +38,15 @@ function validateTaskCreationInput(command, options) {
   if (command === "task-create" && options.preset && options.contractFile) {
     throw inputError("task-create accepts either --preset or --contract-file, not both");
   }
+  if (command === "contract-create" && !options.taskId) throw inputError("contract-create requires --task");
+  if (command === "contract-create" && !options.preset && !options.contractFile) throw inputError("contract-create requires --preset or --contract-file");
+  if (command === "contract-create" && options.preset && options.contractFile) throw inputError("contract-create accepts either --preset or --contract-file, not both");
+  if (command === "contract-revise" && !options.taskId) throw inputError("contract-revise requires --task");
+  if (command === "contract-revise" && !options.preset && !options.contractFile) throw inputError("contract-revise requires --preset or --contract-file");
+  if (command === "contract-revise" && options.preset && options.contractFile) throw inputError("contract-revise accepts either --preset or --contract-file, not both");
+  if (command === "task-repair-contract-bootstrap" && !options.taskId) throw inputError("task-repair-contract-bootstrap requires --task");
+  if (command === "task-repair-contract-bootstrap" && !options.acknowledgeRepair) throw inputError("task-repair-contract-bootstrap requires --acknowledge-repair");
+  validateContractBootstrapRepairMigrationInput(command, options);
   const hasTaskListFilter = Boolean(
     options.phase
       || options.active
@@ -42,6 +58,15 @@ function validateTaskCreationInput(command, options) {
   }
 }
 
+function validateGateRecordInput(command, options, help) {
+  if (command !== "gate-record" || help) return;
+  if (!options.taskId) throw inputError("gate-record requires --task");
+  if (!options.gate) throw inputError("gate-record requires --gate");
+  if (!["satisfied", "unverified", "blocked"].includes(options.gateStatus)) {
+    throw inputError("gate-record --status must be satisfied, unverified, or blocked");
+  }
+}
+
 function validateExecutionProfileInput(command, options) {
   if (options.executionProfile !== null && options.executionProfile !== undefined) {
     if (command !== "route") throw inputError(`executionProfile is not valid for ${command}`);
@@ -91,54 +116,91 @@ function validateOutputInput(command, options) {
   if (command !== "next" && options.explain === true) throw inputError(`explain output is not valid for ${command}`);
 }
 
-function validateTaskSelectorsInput(command, options, help) {
-  const taskCommands = ["workspace-bind", "workspace-status", "handoff-create", "handoff-list", "handoff-show", "handoff-accept", "responsibility-set", "responsibility-status", "verify-scope", "attestation-create", "attestation-status", "attestation-verify"];
-  if (taskCommands.includes(command) && !options.taskId) throw inputError(`${command} requires --task`);
-  if (command === "handoff-show" && !help && !options.handoffId) throw inputError("handoff-show requires --id");
-  if (command === "handoff-accept" && !help) {
-    if (!options.handoffId) throw inputError("handoff-accept requires --handoff");
-    if (!options.consumerId) throw inputError("handoff-accept requires --consumer-id");
+const TASK_SELECTOR_COMMANDS = new Set([
+  "context-plan",
+  "model-route",
+  "semantic-plan",
+  "test-utility",
+  "checkpoint-revalidate",
+  "workspace-bind",
+  "workspace-status",
+  "handoff-create",
+  "handoff-list",
+  "handoff-show",
+  "handoff-accept",
+  "responsibility-set",
+  "responsibility-status",
+  "verify-scope",
+  "attestation-create",
+  "attestation-status",
+  "attestation-verify",
+]);
+
+function validateRequiredTaskSelector(command, options, help) {
+  if (TASK_SELECTOR_COMMANDS.has(command) && !help && !options.taskId) {
+    throw inputError(`${command} requires --task`);
   }
+}
+
+function validateHandoffShowInput(command, options, help) {
+  if (command === "handoff-show" && !help && !options.handoffId) throw inputError("handoff-show requires --id");
+}
+
+function validateHandoffAcceptInput(command, options, help) {
+  if (command !== "handoff-accept" || help) return;
+  if (!options.handoffId) throw inputError("handoff-accept requires --handoff");
+  if (!options.consumerId) throw inputError("handoff-accept requires --consumer-id");
+}
+
+function validateResponsibilityInput(command, options, help) {
   if (command === "responsibility-set" && !help && !options.responsibilityLabel) {
     throw inputError("responsibility-set requires --label");
   }
-  if (command === "verify-scope" && !help) {
-    const mode = String(options.verificationScopeMode ?? "AUTO").toUpperCase();
-    if (!["AUTO", "CHANGED", "CLAIMED", "FULL"].includes(mode)) throw inputError("verify-scope --mode must be AUTO, CHANGED, CLAIMED, or FULL");
-  }
-  if (command === "attestation-verify-range" && !help) {
-    if (!options.baseRevision) throw inputError("attestation-verify-range requires --base");
-    if (!options.headRevision) throw inputError("attestation-verify-range requires --head");
+}
+
+function validateVerificationScopeInput(command, options, help) {
+  if (command !== "verify-scope" || help) return;
+  const mode = String(options.verificationScopeMode ?? "AUTO").toUpperCase();
+  if (!["AUTO", "CHANGED", "CLAIMED", "FULL"].includes(mode)) throw inputError("verify-scope --mode must be AUTO, CHANGED, CLAIMED, or FULL");
+}
+
+function validateAttestationRangeInput(command, options, help) {
+  if (command !== "attestation-verify-range" || help) return;
+  if (!options.baseRevision) throw inputError("attestation-verify-range requires --base");
+  if (!options.headRevision) throw inputError("attestation-verify-range requires --head");
+}
+
+function validateTaskSelectorsInput(command, options, help) {
+  validateRequiredTaskSelector(command, options, help);
+  validateHandoffShowInput(command, options, help);
+  validateHandoffAcceptInput(command, options, help);
+  validateResponsibilityInput(command, options, help);
+  validateVerificationScopeInput(command, options, help);
+  validateAttestationRangeInput(command, options, help);
+}
+
+function validateRecordCheckInput(options) {
+  if (!options.checkId) throw inputError("record-check requires --id");
+  if (!options.checkRequirement) throw inputError("record-check requires --requirement");
+  if (!options.checkStatus) throw inputError("record-check requires --status");
+  if (!options.checkEvidenceKind) throw inputError("record-check requires --evidence-kind");
+  if (!options.checkCommand && !options.checkResult) throw inputError("record-check requires --command or --result");
+}
+
+function validateCommandCheckInput(options, command) {
+  if (!options.checkId) throw inputError(`${command} requires --id`);
+  if (!options.checkRequirement) throw inputError(`${command} requires --requirement`);
+  if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
+    || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
+    throw inputError(`${command} accepts only --id, --requirement, --details,${command === "run-check" ? " --timeout-ms, --scope-ref," : ""} and -- <argv>`);
   }
+  if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) throw inputError(`${command} requires -- followed by an exact command argv`);
 }
 
 function validateCheckInput(command, options, help) {
-  if (command === "record-check" && !help) {
-    if (!options.checkId) throw inputError("record-check requires --id");
-    if (!options.checkRequirement) throw inputError("record-check requires --requirement");
-    if (!options.checkStatus) throw inputError("record-check requires --status");
-    if (!options.checkEvidenceKind) throw inputError("record-check requires --evidence-kind");
-    if (!options.checkCommand && !options.checkResult) throw inputError("record-check requires --command or --result");
-  }
-  if (command === "run-check" && !help) {
-    if (!options.checkId) throw inputError("run-check requires --id");
-    if (!options.checkRequirement) throw inputError("run-check requires --requirement");
-    if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
-      || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
-      throw inputError("run-check accepts only --id, --requirement, --details, --timeout-ms, --scope-ref, and -- <argv>");
-    }
-    if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) throw inputError("run-check requires -- followed by an exact command argv");
-  }
-  if (command === "reconcile-closure" && !help) {
-    if (!options.taskId) throw inputError("reconcile-closure requires --task");
-    if (!options.checkId) throw inputError("reconcile-closure requires --id");
-    if (!options.checkRequirement) throw inputError("reconcile-closure requires --requirement");
-    if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
-      || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
-      throw inputError("reconcile-closure accepts only --id, --requirement, --details, and -- <argv>");
-    }
-    if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) throw inputError("reconcile-closure requires -- followed by an exact command argv");
-  }
+  if (help) return;
+  if (command === "record-check") validateRecordCheckInput(options);
+  if (command === "run-check" || command === "reconcile-closure") validateCommandCheckInput(options, command);
 }
 
 /**
@@ -172,6 +234,8 @@ export function defaultCommandInputValues() {
     assetPath: null,
     binaryPath: null,
     force: false,
+    acknowledgeRepair: false,
+    acknowledgeMigration: false,
     workType: null,
     surfaces: [],
     risks: [],
@@ -193,6 +257,13 @@ export function defaultCommandInputValues() {
     file: null,
     contractFile: null,
     preset: null,
+    gate: null,
+    gateStatus: null,
+    gateArtifacts: [],
+    gateDecisions: [],
+    gateUnknowns: [],
+    gateAssumptions: [],
+    gateEvidenceFile: null,
     preview: false,
     phase: null,
     active: false,
@@ -253,6 +324,25 @@ export function defaultCommandInputValues() {
   };
 }
 
+function validateStorageRestoreInput(command, options, help) {
+  if (command === "storage-restore-resume" && !help && (options.writersQuiesced !== true || typeof options.operationId !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(options.operationId) || typeof options.expectedOwnerId !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(options.expectedOwnerId))) throw inputError("storage-restore-resume requires exact --operation and --expected-owner UUIDs and explicit --writers-quiesced");
+  if (["storage-restore", "storage-restore-resume"].includes(command) && options.replaceActive !== undefined && typeof options.replaceActive !== "boolean") throw inputError("Active replacement selection must be a boolean");
+  if (command === "storage-restore" && !help && (typeof options.source !== "string" || !options.source || options.writersQuiesced !== true)) throw inputError("storage-restore requires --source and explicit --writers-quiesced");
+  if (command === "storage-backup" && !help && (typeof options.destination !== "string" || !options.destination)) throw inputError("storage-backup requires --destination");
+}
+
+function validateStorageMigrationInput(command, options, help) {
+  if (command === "storage-rollback-resume" && !help && !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(options.expectedOwnerId ?? "")) throw inputError("storage-rollback-resume requires exact --expected-owner UUID");
+  if (["storage-rollback", "storage-rollback-resume"].includes(command) && !help && (typeof options.destination !== "string" || !options.destination || typeof options.legacyRoot !== "string" || !options.legacyRoot || options.writersQuiesced !== true || options.nativeWritesExcluded !== true)) throw inputError("storage-rollback requires --destination, --legacy-root, explicit --writers-quiesced and --native-writes-excluded");
+  if (command === "storage-migrate" && !help && (typeof options.destination !== "string" || !options.destination || options.writersQuiesced !== true)) throw inputError("storage-migrate requires --destination and explicit --writers-quiesced");
+  if (command === "storage-migration-resume" && !help && (typeof options.destination !== "string" || !options.destination || options.writersQuiesced !== true || typeof options.expectedOwnerId !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(options.expectedOwnerId))) throw inputError("storage-migration-resume requires --destination, exact --expected-owner UUID and explicit --writers-quiesced");
+  validateUnboundHandoffAcknowledgement(command, options);
+}
+
+function validateUnboundHandoffAcknowledgement(command, options) {
+  if (command === "storage-migration-resume" && options.acknowledgeUnboundHandoff !== undefined && typeof options.acknowledgeUnboundHandoff !== "boolean") throw inputError("--reconcile-unbound-handoff must be a boolean acknowledgement");
+}
+
 /**
  * Canonical semantic validation shared by the CLI argv parser and
  * programmatic integrations. JSON-Schema style checks cannot express these
@@ -261,9 +351,11 @@ export function defaultCommandInputValues() {
 export function validateForgeLoopCommandInput({ command, input, help = false } = {}) {
   const options = input ?? {};
   if (!command) return;
-
+  validateStorageRestoreInput(command, options, help);
+  validateStorageMigrationInput(command, options, help);
   validatePolicyInput(command, options);
-  validateTaskCreationInput(command, options);
+  validateTaskCreationInput(command, options, help);
+  validateGateRecordInput(command, options, help);
   validateSearchCommandInput(command, options, help);
   validateProfileAndUsageInput(command, options, help);
   validateOutputInput(command, options);

package/src/core/completion-artifacts.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 import {
   ARTIFACT_PATHS,
   canonicalFingerprint,
@@ -18,7 +19,7 @@ import { readPersistedRoute } from "./route-artifact.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { readWorkState, mutateWorkState } from "./work-state.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
-import { normalizeRequirements } from "./evidence-readiness.js";
+import { normalizeRequirements, terminalRequirementsForContract } from "./evidence-readiness.js";
 import { classifyCommandResolution, validateVerificationAuthority } from "./verification-capability.js";
 import { readExecutionArtifact, validateExecutionBinding } from "./execution.js";
 import { taskArtifactPath, taskExecutionPath } from "./task-paths.js";
@@ -80,10 +81,18 @@ function requiredString(value, label) {
   return value;
 }
 
+async function readBoundReceiptArtifact(target, receiptRel, packageRoot) {
+  try { return await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot); }
+  catch (error) {
+    if (error.code === "E_STORAGE_PAYLOAD_MISMATCH" && error.taskIdentityMismatch) throw artifactError("E_RECEIPT_TASK_MISMATCH", "Execution receipt does not belong to the current contract task", [receiptRel]);
+    throw error;
+  }
+}
+
 async function readCurrentReceipt(target, packageRoot, options = {}) {
   const receiptRel = options.receiptPath ?? (options.taskId ? taskArtifactPath(options.taskId, "receipt") : ARTIFACT_PATHS.receipt);
   try {
-    return await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
+    return await readBoundReceiptArtifact(target, receiptRel, packageRoot);
   } catch (error) {
     if (error.code === "ARTIFACT_MISSING") {
       throw artifactError(
@@ -245,7 +254,21 @@ export async function requiredEvidenceForTarget({
   ])].sort();
 }
 
-export async function prepareCompletion({
+async function resolveCompletionTaskOptions(options) {
+  if (options.taskId) return options;
+  const state = await readWorkState(options.target, { packageRoot: options.packageRoot, statePath: options.statePath });
+  return { ...options, taskId: state?.taskId };
+}
+
+export async function prepareCompletion(options = {}) {
+  options = await resolveCompletionTaskOptions(options);
+  if (!options.taskId) return prepareSelectedCompletion(options);
+  return withTaskTransaction({ target: options.target, packageRoot: options.packageRoot,
+    taskId: options.taskId, operation: "prepare-completion", recordCommitEvent: true },
+  () => prepareSelectedCompletion(options));
+}
+
+async function prepareSelectedCompletion({
   target,
   packageRoot,
   authorityContext,
@@ -255,6 +278,7 @@ export async function prepareCompletion({
   routePath = null,
   statePath = null,
   receiptPath = null,
+  eventsPath,
 }) {
   const contract = await readContract(target, packageRoot, { taskId, contractPath });
   const route = await readPersistedRoute(target, packageRoot, { taskId, routePath });
@@ -266,12 +290,12 @@ export async function prepareCompletion({
     throw artifactError("E_STATE_MISSING", "Work state is required before preparing completion", [stateRel]);
   }
   if (hasExecutionStarted(state.phase)) {
-    await assertExecutionPrerequisites({ target, state, packageRoot, taskId, statePath, contractPath, routePath });
+    await assertExecutionPrerequisites({ target, state, packageRoot, taskId, statePath, contractPath, routePath, eventsPath });
   }
 
   let existing = null;
   try {
-    existing = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
+    existing = await readBoundReceiptArtifact(target, receiptRel, packageRoot);
     await validateReceipt(existing.value, packageRoot, {
       target,
       taskId: contract.value.taskId,
@@ -463,7 +487,7 @@ export async function assertRecordCheckPrerequisites({
       [stateRel],
     );
   }
-  await assertExecutionPrerequisites({ target, state, packageRoot, taskId, statePath, contractPath, routePath });
+  await assertExecutionPrerequisites({ target, state, packageRoot, taskId, statePath, contractPath, routePath, eventsPath });
 
   const contract = await readContract(target, packageRoot, { taskId, contractPath });
   const route = await readPersistedRoute(target, packageRoot, { taskId, routePath });
@@ -478,10 +502,15 @@ export async function assertRecordCheckPrerequisites({
   const requested = normalizeRequirements(requiredEvidence).find((item) => (
     item.id === requirement || item.text === requirement
   ));
-  if (requested?.terminalOwned && status === "passed" && evidenceKind === "OBSERVED") {
+  const terminalRequested = terminalRequirementsForContract(contract.value, {
+    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+  }).find((item) => (
+    item.id === requirement || item.text === requirement
+  ));
+  if ((requested?.terminalOwned || terminalRequested) && status === "passed" && evidenceKind === "OBSERVED") {
     throw artifactError(
       "E_FUTURE_LIFECYCLE_EVIDENCE",
-      `Terminal-owned requirement cannot be recorded before its authoritative result: ${requested.text}`,
+      `Terminal-owned requirement cannot be recorded before its authoritative result: ${(requested ?? terminalRequested).text}`,
       [stateRel, eventsRel],
     );
   }
@@ -516,29 +545,15 @@ export async function assertRecordCheckPrerequisites({
   };
 }
 
-export async function recordCheck({
-  target,
-  packageRoot,
-  id,
-  kind = "command",
-  requirement,
-  status,
-  evidenceKind,
-  command,
-  result,
-  exitCode,
-  details,
-  executionRef,
-  provenance,
-  authorityContext,
-  runtimeContext,
-  taskId = null,
-  contractPath = null,
-  routePath = null,
-  statePath = null,
-  receiptPath = null,
-  eventsPath = null,
-}) {
+export async function recordCheck(options) {
+  validateRecordCheckInput(options);
+  options = await resolveCompletionTaskOptions(options);
+  if (!options.taskId) return recordValidatedCheck(options);
+  return withTaskTransaction({ target: options.target, packageRoot: options.packageRoot,
+    taskId: options.taskId, operation: "record-check", recordCommitEvent: true }, () => recordValidatedCheck(options));
+}
+
+function validateRecordCheckInput({ id, kind = "command", requirement, status, evidenceKind, command, result, details, executionRef, provenance }) {
   requiredString(id, "check id");
   requiredString(kind, "check kind");
   requiredString(requirement, "check requirement");
@@ -563,7 +578,31 @@ export async function recordCheck({
     && (typeof result !== "string" || result.trim() === "")) {
     throw artifactError("E_CHECK_INVALID", "record-check requires --command or --result");
   }
+}
 
+async function recordValidatedCheck({
+  target,
+  packageRoot,
+  id,
+  kind = "command",
+  requirement,
+  status,
+  evidenceKind,
+  command,
+  result,
+  exitCode,
+  details,
+  executionRef,
+  provenance,
+  authorityContext,
+  runtimeContext,
+  taskId = null,
+  contractPath = null,
+  routePath = null,
+  statePath = null,
+  receiptPath = null,
+  eventsPath = null,
+}) {
   const context = await assertRecordCheckPrerequisites({
     target,
     packageRoot,
@@ -775,7 +814,15 @@ export async function recordCheck({
   };
 }
 
-export async function recordTerminalResult({
+export async function recordTerminalResult(options = {}) {
+  if (!options.target) return recordTerminalResultInTransaction(options);
+  if (await getTaskTransaction(options.target)) return recordTerminalResultInTransaction(options);
+  const state = await readWorkState(options.target, { packageRoot: options.packageRoot, taskId: options.taskId, statePath: options.statePath });
+  if (!state) return recordTerminalResultInTransaction(options);
+  return withTaskTransaction({ target: options.target, taskId: state.taskId, packageRoot: options.packageRoot, operation: "record-terminal-result" }, () => recordTerminalResultInTransaction({ ...options, taskId: options.taskId ?? state.taskId }));
+}
+
+async function recordTerminalResultInTransaction({
   target,
   packageRoot,
   requirement,
@@ -827,8 +874,12 @@ export async function recordTerminalResult({
     additionalEvidence: preflight.policy?.requiredEvidence ?? [],
   });
 
-  const normalized = normalizeRequirements(requiredEvidence);
-  const requested = normalized.find((item) => (
+  const terminalRequirements = terminalRequirementsForContract(contract.value, {
+    additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+  });
+  const requested = terminalRequirements.find((item) => (
+    item.id === requirement || item.text === requirement
+  )) ?? normalizeRequirements(requiredEvidence).find((item) => (
     item.id === requirement || item.text === requirement
   ));
 

package/src/core/completion-ownership.js

@@ -1,7 +1,19 @@
+import { isLedgerEventCollection } from "./ledger-event-collection.js";
 import { LIFECYCLE_MILESTONES, validateStateLedgerCoherence } from "./events.js";
 
 export const CANONICAL_COMPLETION_EVENT = "COMPLETION_VALIDATED";
 
+function completionCandidates(events, taskId) {
+  let count = 0;
+  let candidate = null;
+  for (const event of events) {
+    if (event.event !== CANONICAL_COMPLETION_EVENT || event.taskId !== taskId) continue;
+    count += 1;
+    candidate = event;
+  }
+  return { count, candidate };
+}
+
 /**
  * Canonical completion ownership proof: the minimal, validator-backed evidence
  * that the lifecycle itself officially reached COMPLETE. This is intentionally
@@ -28,31 +40,30 @@ export function validateCompletionOwnershipProof({ taskId, state, ledger }) {
   }
 
   let completionEvent = null;
-  if (ledger && Array.isArray(ledger.events)) {
+  if (ledger && isLedgerEventCollection(ledger.events)) {
     if (ledger.events.some((event) => event.taskId !== taskId)) {
       errors.push({
         code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
         message: "Ledger contains an event belonging to a different task",
       });
     }
-    const candidates = ledger.events
-      .filter((event) => event.event === CANONICAL_COMPLETION_EVENT && event.taskId === taskId);
-    if (candidates.length === 0) {
+    const { count, candidate } = completionCandidates(ledger.events, taskId);
+    if (count === 0) {
       errors.push({
         code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
         message: `No canonical ${CANONICAL_COMPLETION_EVENT} event exists for this task`,
       });
-    } else if (candidates.length > 1) {
+    } else if (count > 1) {
       errors.push({
         code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
         message: `Multiple ${CANONICAL_COMPLETION_EVENT} events exist; completion is ambiguous`,
       });
     } else {
-      completionEvent = candidates[0];
+      completionEvent = candidate;
     }
   }
 
-  if (state && ledger && Array.isArray(ledger.events)) {
+  if (state && ledger && isLedgerEventCollection(ledger.events)) {
     const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
     if (coherenceErrors.length > 0) {
       for (const error of coherenceErrors) {
@@ -67,7 +78,7 @@ export function validateCompletionOwnershipProof({ taskId, state, ledger }) {
   // No contradictory lifecycle activity may follow the canonical completion:
   // any milestone at or after VERIFICATION_RECORDED occurring after the
   // completion event means the lifecycle moved past terminal state.
-  if (completionEvent && ledger && Array.isArray(ledger.events)) {
+  if (completionEvent && ledger && isLedgerEventCollection(ledger.events)) {
     const completionIndex = ledger.events.indexOf(completionEvent);
     const contradiction = ledger.events.slice(completionIndex + 1).find((event) => {
       const index = LIFECYCLE_MILESTONES.indexOf(event.event);

package/src/core/completion-recovery-rebind.js

@@ -3,6 +3,7 @@ import { appendProtocolEvent, validateCompletionRecoveryAuthorization, validateE
 import { createReceipt } from "./receipt.js";
 import { taskArtifactPath } from "./task-paths.js";
 import { mutateWorkState, readWorkState } from "./work-state.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
 
 function resolveArtifactPath(key, taskId, override) {
   if (override) return override;
@@ -65,7 +66,16 @@ function findMatchingRejectionEvent(events, attempt, cycle) {
  *     rejection carrying the current fingerprints is appended,
  *   - the execution receipt is re-bound to the current checkpoint when present.
  */
-export async function rebindCompletionRejectionSnapshot({
+export async function rebindCompletionRejectionSnapshot(options = {}) {
+  if (await getTaskTransaction(options.target)) return rebindRejectionInTransaction(options);
+  const state = await readWorkState(options.target, { packageRoot: options.packageRoot,
+    taskId: options.taskId, statePath: resolveArtifactPath("state", options.taskId, options.statePath) });
+  if (!state) return { rebound: false };
+  return withTaskTransaction({ target: options.target, taskId: options.taskId ?? state.taskId,
+    packageRoot: options.packageRoot, operation: "rebind-completion-rejection" }, () => rebindRejectionInTransaction(options));
+}
+
+async function rebindRejectionInTransaction({
   target,
   packageRoot,
   taskId = null,