@cassiomc1/forgeloop 1.2.4 → 1.5.0

package/src/core/reconcile-closure.js

@@ -1,15 +1,17 @@
 import { readContract } from "./contract.js";
-import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { appendProtocolEvent, validateEventLedger, readEvents, validateCompletionRecoveryAuthorization } from "./events.js";
 import { runCommandExecution } from "./execution.js";
+import { createReceipt } from "./receipt.js";
 import { currentRepositoryFingerprint } from "./repository.js";
 import { taskArtifactPath } from "./task-paths.js";
-import { classifyLoadedWorkState, readWorkState, writeWorkState } from "./work-state.js";
+import { classifyLoadedWorkState, readWorkState, mutateWorkState } from "./work-state.js";
 
 export const RECONCILE_EVENT = "CHECKPOINT_RECONCILED";
 
 const RECONCILABLE_DRIFT = new Set(["REPOSITORY_CHANGED"]);
 
-const RECONCILABLE_PHASES = new Set(["EXECUTING", "VERIFYING"]);
+const RECONCILABLE_PHASES = new Set(["EXECUTING", "VERIFYING", "REVIEWING"]);
 
 function reconcileError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -19,12 +21,13 @@ function reconcileError(code, message, artifacts = []) {
 }
 
 /**
- * Canonical recovery for an EXECUTING or VERIFYING task whose objective is
- * already satisfied in the current repository but whose work-state
- * checkpoint is stale because the repository fingerprint moved.
+ * Canonical recovery for an EXECUTING, VERIFYING, or REVIEWING task whose
+ * objective is already satisfied in the current repository but whose
+ * work-state checkpoint is stale because the repository fingerprint moved.
  *
  * The command refreshes the checkpoint repository fingerprint only after:
- *   - the task is EXECUTING or VERIFYING,
+ *   - the task is EXECUTING, VERIFYING, or (with authorized completion
+ *     recovery) REVIEWING,
  *   - classification requires revalidation and the only drift is
  *     REPOSITORY_CHANGED,
  *   - the append-only event ledger is valid,
@@ -63,6 +66,7 @@ export async function runReconcileClosure({
   const stateRel = taskArtifactPath(taskId, "state");
   const contractRel = taskArtifactPath(taskId, "contract");
   const eventsRel = taskArtifactPath(taskId, "events");
+  const receiptRel = taskArtifactPath(taskId, "receipt");
 
   const state = await readWorkState(target, { packageRoot, taskId });
   if (!state) {
@@ -71,10 +75,28 @@ export async function runReconcileClosure({
   if (!RECONCILABLE_PHASES.has(state.phase)) {
     throw reconcileError(
       "E_RECONCILE_PHASE_INVALID",
-      `reconcile-closure supports EXECUTING or VERIFYING tasks whose objective is already satisfied; found ${state.phase}`,
+      `reconcile-closure supports EXECUTING, VERIFYING, or REVIEWING tasks whose objective is already satisfied; found ${state.phase}`,
       [stateRel],
     );
   }
+  if (state.phase === "REVIEWING") {
+    let receipt = null;
+    try {
+      receipt = (await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot))?.value ?? null;
+    } catch {
+      receipt = null;
+    }
+    const events = await readEvents(target, packageRoot, { taskId });
+    const recoveryAuth = validateCompletionRecoveryAuthorization({ state, receipt, events });
+    if (!recoveryAuth.authorized) {
+      const first = recoveryAuth.errors?.[0] ?? {};
+      throw reconcileError(
+        first.code ?? "E_COMPLETION_RECOVERY_UNAUTHORIZED",
+        `REVIEWING reconciliation requires authorized completion recovery: ${first.message ?? "unauthorized"}`,
+        [stateRel, receiptRel],
+      );
+    }
+  }
 
   const freshness = await classifyLoadedWorkState({ target, state, contractFile: contractRel });
   if (freshness.status !== "REVALIDATION_REQUIRED" || !freshness.reasons.includes("REPOSITORY_CHANGED")) {
@@ -104,9 +126,12 @@ export async function runReconcileClosure({
   }
 
   const contract = await readContract(target, packageRoot, { taskId });
-  const verificationItem = (contract.value.verification ?? []).find(
-    (item) => item.type === "VERIFICATION" && item.id === checkId && item.text === requirement,
-  );
+  const verificationItem = (contract.value.verification ?? []).find((item) => {
+    if (typeof item === "string") {
+      return item === requirement;
+    }
+    return item.type === "VERIFICATION" && item.id === checkId && item.text === requirement;
+  });
   if (!verificationItem) {
     throw reconcileError(
       "E_RECONCILE_REQUIREMENT_UNKNOWN",
@@ -154,11 +179,26 @@ export async function runReconcileClosure({
     },
   }, packageRoot, { taskId });
 
-  await writeWorkState(target, {
+  const nextState = await mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+  }, () => ({
     ...state,
     repositoryFingerprint: repository,
     lastUpdated: new Date().toISOString(),
-  }, { packageRoot, taskId });
+  }));
+
+  try {
+    const receipt = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
+    const reboundReceipt = await createReceipt({
+      ...receipt.value,
+      stateFingerprint: canonicalFingerprint(nextState),
+    }, packageRoot, { target, taskId, authorityContext, runtimeContext });
+    await writeJsonArtifact(target, receiptRel, reboundReceipt, "execution-receipt", packageRoot);
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
 
   return {
     taskId,
@@ -172,4 +212,4 @@ export async function runReconcileClosure({
     executionPath: execution.path,
     event: RECONCILE_EVENT,
   };
-}
+}

package/src/core/recovery-history.js

@@ -0,0 +1,116 @@
+import {
+  LEGACY_RECOVERY_MIGRATION_EVENT,
+  isLegacyRecoveryEventShape,
+} from "./task-recovery-migration.js";
+
+const RECOVERY_EVENT_TYPES = new Set([
+  "TASK_RECOVERY_RECORDED",
+  "OPERATOR_RECOVERY_RECORDED",
+  LEGACY_RECOVERY_MIGRATION_EVENT,
+]);
+
+function recoveryError(message) {
+  return {
+    code: "E_TASK_RECOVERY_INCONSISTENT",
+    message,
+  };
+}
+
+function recoveryIdOf(event) {
+  return typeof event?.details?.recoveryId === "string" && event.details.recoveryId !== ""
+    ? event.details.recoveryId
+    : null;
+}
+
+export function classifyRecoveryHistory(events = []) {
+  const recoveries = [];
+  const completedRecoveries = [];
+  const errors = [];
+  const seenRecoveryIds = new Set();
+  let activeCycle = null;
+
+  for (const event of events) {
+    if (RECOVERY_EVENT_TYPES.has(event?.event)) {
+      // The known legacy defect signature is never an owning recovery cycle by
+      // itself. It remains non-owning historical evidence; ownership comes
+      // exclusively from its valid LEGACY_RECOVERY_MIGRATION_RECORDED event,
+      // which is validated (binding, uniqueness) by the ledger validator.
+      if (!event.details?.recoveryId && isLegacyRecoveryEventShape(event)) continue;
+      // A migration event only counts as a canonical recovery cycle when it
+      // binds an actual legacy event present earlier in this ledger.
+      if (event.event === LEGACY_RECOVERY_MIGRATION_EVENT
+        && !events.some((candidate) => candidate.seq === event.details?.legacyEventSeq
+          && isLegacyRecoveryEventShape(candidate))) {
+        errors.push(recoveryError(
+          `Legacy migration event at seq ${event?.seq ?? "unknown"} does not bind a legacy recovery event in this ledger`,
+        ));
+        continue;
+      }
+      const recoveryId = recoveryIdOf(event);
+      if (!recoveryId) {
+        errors.push(recoveryError(`Recovery event at seq ${event?.seq ?? "unknown"} has no recoveryId`));
+        continue;
+      }
+      if (seenRecoveryIds.has(recoveryId)) {
+        errors.push(recoveryError(`Recovery event at seq ${event.seq} reuses recovery id ${recoveryId}`));
+        continue;
+      }
+      if (activeCycle) {
+        errors.push(recoveryError(
+          `Recovery ${recoveryId} was recorded while recovery ${activeCycle.recoveryId} is unresolved`,
+        ));
+        continue;
+      }
+
+      activeCycle = {
+        recoveryId,
+        recoveryEventSeq: event.seq,
+        resumedEventSeq: null,
+        active: true,
+        event,
+        resumedEvent: null,
+      };
+      seenRecoveryIds.add(recoveryId);
+      recoveries.push(activeCycle);
+      continue;
+    }
+
+    if (event?.event !== "TASK_RECOVERY_RESUMED") continue;
+
+    const recoveryId = recoveryIdOf(event);
+    if (!recoveryId || !activeCycle || activeCycle.recoveryId !== recoveryId) {
+      errors.push(recoveryError(
+        `TASK_RECOVERY_RESUMED at seq ${event?.seq ?? "unknown"} does not reference an active recovery`,
+      ));
+      continue;
+    }
+    if (!Number.isInteger(event.seq) || event.seq <= activeCycle.recoveryEventSeq) {
+      errors.push(recoveryError(
+        `Resume sequence for recovery ${recoveryId} must be greater than recovery sequence ${activeCycle.recoveryEventSeq}`,
+      ));
+      continue;
+    }
+
+    activeCycle.resumedEventSeq = event.seq;
+    activeCycle.resumedEvent = event;
+    activeCycle.active = false;
+    completedRecoveries.push(activeCycle);
+    activeCycle = null;
+  }
+
+  const valid = errors.length === 0;
+  return {
+    recoveries,
+    activeRecoveryId: valid ? activeCycle?.recoveryId ?? null : null,
+    activeRecovery: valid && activeCycle
+      ? { recoveryId: activeCycle.recoveryId, event: activeCycle.event }
+      : null,
+    completedRecoveries,
+    valid,
+    errors,
+  };
+}
+
+export function resolveRecoveryHistory(events = []) {
+  return classifyRecoveryHistory(events);
+}

package/src/core/resumability.js

@@ -1,5 +1,5 @@
 import { currentRepositoryFingerprint } from "./repository.js";
-import { createWorkState, readWorkState, writeWorkState } from "./work-state.js";
+import { createWorkState, initializeWorkState, readWorkState, mutateWorkState } from "./work-state.js";
 
 const DEFAULT_PENDING_STEPS = ["planning", "implementation", "verification"];
 
@@ -22,8 +22,7 @@ export async function ensureResumableState({ target, packageRoot, contract, rout
     blockers: [],
     verificationEvidence: [],
   });
-  await writeWorkState(target, state, { packageRoot, taskId, statePath });
-  return state;
+  return initializeWorkState(target, state, { packageRoot, taskId, statePath });
 }
 
 export async function synchronizePreflightState({
@@ -57,7 +56,10 @@ export async function synchronizePreflightState({
   if (JSON.stringify(withoutTimestamp(candidate)) === JSON.stringify(withoutTimestamp(state))) {
     return state;
   }
-  const next = { ...candidate, lastUpdated: new Date().toISOString() };
-  await writeWorkState(target, next, { packageRoot, taskId, statePath });
-  return next;
+  return mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId,
+    statePath,
+  }, () => ({ ...candidate, lastUpdated: new Date().toISOString() }));
 }

package/src/core/schema-validation.js

@@ -33,6 +33,7 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "execution",
   "authority",
   "task-descriptor",
+  "task-recovery",
 ]);
 
 export class SchemaValidationError extends Error {

package/src/core/task-claim-state.js

@@ -0,0 +1,272 @@
+import {
+  E_COMPLETION_OWNERSHIP_UNPROVEN,
+  E_TASK_CLAIM_OWNERSHIP_INCONSISTENT,
+  E_TASK_COMPLETE,
+  E_TASK_RECOVERED,
+  E_TASK_RECOVERY_INCONSISTENT,
+} from "./error-codes.js";
+import { validateCompletionOwnershipProof } from "./completion-ownership.js";
+import { validateEventLedger } from "./events.js";
+import { classifyRecoveryHistory } from "./recovery-history.js";
+import { readTaskDescriptor } from "./task-descriptor.js";
+import { normalizeWriteClaims } from "./task-scope.js";
+import {
+  readTaskRecovery,
+  validateTaskRecoveryConsistency,
+} from "./task-recovery.js";
+import { readWorkState } from "./work-state.js";
+
+function ownershipError(message, cause = null) {
+  return {
+    code: E_TASK_RECOVERY_INCONSISTENT,
+    message,
+    ...(cause?.code ? { causeCode: cause.code } : {}),
+  };
+}
+
+function appendClaims(target, claims, errors, source) {
+  if (claims === undefined || claims === null) return;
+  try {
+    target.push(...normalizeWriteClaims(claims));
+  } catch (error) {
+    errors.push(ownershipError(`Invalid ${source} write claims: ${error.message}`, error));
+  }
+}
+
+/**
+ * Collects every input needed to resolve claim ownership from one immutable
+ * snapshot: descriptor, work state, recovery tombstone, validated ledger, and
+ * classified recovery history. Classification is a pure function of this
+ * evidence, so conflict inspection can reuse it without rereading artifacts.
+ */
+export async function collectTaskClaimEvidence(target, {
+  taskId,
+  packageRoot,
+  descriptor: suppliedDescriptor = null,
+  state: suppliedState = null,
+} = {}) {
+  const errors = [];
+  let descriptor = suppliedDescriptor;
+  let state = suppliedState;
+  let recovery = null;
+  let ledger = { valid: false, events: [], errors: [] };
+
+  if (!descriptor) {
+    try {
+      descriptor = (await readTaskDescriptor(target, taskId, packageRoot)).value;
+    } catch (error) {
+      errors.push(ownershipError(`Task descriptor cannot establish claim ownership: ${error.message}`, error));
+    }
+  }
+  if (!state) {
+    try {
+      state = await readWorkState(target, { taskId, packageRoot });
+    } catch (error) {
+      errors.push(ownershipError(`Task work state cannot establish claim ownership: ${error.message}`, error));
+    }
+  }
+
+  try {
+    recovery = (await readTaskRecovery(target, { taskId, packageRoot }))?.value ?? null;
+  } catch (error) {
+    errors.push(ownershipError(`Task recovery artifact cannot establish claim ownership: ${error.message}`, error));
+  }
+
+  try {
+    ledger = await validateEventLedger(target, packageRoot, { taskId });
+  } catch (error) {
+    errors.push(ownershipError(`Task event ledger cannot establish claim ownership: ${error.message}`, error));
+  }
+  if (!ledger.valid) {
+    for (const error of ledger.errors) {
+      errors.push(ownershipError(`Task event ledger is invalid: ${error.message}`, error));
+    }
+  }
+  if (ledger.events.some((event) => event.taskId !== taskId)) {
+    errors.push(ownershipError(`Task event ledger contains an event for a different task`));
+  }
+
+  const history = classifyRecoveryHistory(ledger.events);
+  const descriptorClaims = [];
+  appendClaims(descriptorClaims, descriptor?.writeClaims, errors, "descriptor");
+  const normalizedDescriptorClaims = normalizeWriteClaims(descriptorClaims);
+
+  const historicalClaims = [...normalizedDescriptorClaims];
+  for (const cycle of history.recoveries) {
+    appendClaims(historicalClaims, cycle.event?.details?.releasedClaims, errors, "recovery ledger");
+  }
+  appendClaims(historicalClaims, recovery?.releasedClaims, errors, "recovery artifact");
+
+  return {
+    taskId,
+    phase: state?.phase ?? null,
+    descriptor,
+    state,
+    recovery,
+    ledger,
+    history,
+    normalizedDescriptorClaims,
+    historicalWriteClaims: normalizeWriteClaims(historicalClaims),
+    errors,
+  };
+}
+
+function inconsistentResult({ taskId, phase, historicalWriteClaims, recovery, errors }) {
+  const reasonCodes = [
+    E_TASK_CLAIM_OWNERSHIP_INCONSISTENT,
+    ...errors.flatMap((error) => [error.code, error.causeCode]).filter(Boolean),
+  ];
+  return {
+    taskId,
+    phase,
+    historicalWriteClaims,
+    effectiveWriteClaims: historicalWriteClaims,
+    writeClaims: historicalWriteClaims,
+    claimState: "INCONSISTENT",
+    mutationAllowed: false,
+    recovery,
+    recoveryStatus: "INCONSISTENT",
+    valid: false,
+    ownershipValid: false,
+    reasonCodes: [...new Set(reasonCodes)],
+    errors,
+    ownershipErrors: errors,
+  };
+}
+
+/**
+ * Deterministic claim-ownership decision table over collected evidence.
+ * Claims are released only for validated canonical completion or validated
+ * active recovery; everything else fails closed.
+ */
+export function classifyTaskClaimState(evidence) {
+  const {
+    taskId,
+    phase,
+    recovery,
+    ledger,
+    history,
+    normalizedDescriptorClaims,
+    historicalWriteClaims,
+  } = evidence;
+
+  // Classification is side-effect free: never mutate the supplied evidence.
+  const errors = [...(evidence.errors ?? [])];
+  errors.push(...validateTaskRecoveryConsistency({
+    taskId,
+    recovery,
+    events: ledger.events,
+    historicalWriteClaims: normalizedDescriptorClaims,
+    recoveryHistory: history,
+  }));
+
+  if (errors.length > 0) {
+    return inconsistentResult({ taskId, phase, historicalWriteClaims, recovery, errors });
+  }
+
+  if (phase === "COMPLETE") {
+    const proof = validateCompletionOwnershipProof({ taskId, state: evidence.state, ledger });
+    if (!proof.valid) {
+      return inconsistentResult({
+        taskId,
+        phase,
+        historicalWriteClaims,
+        recovery,
+        errors: [
+          ownershipError(
+            "COMPLETE work-state lacks canonical lifecycle/ledger completion proof; claims stay reserved",
+            { code: E_COMPLETION_OWNERSHIP_UNPROVEN },
+          ),
+          ...proof.errors.map((error) => ownershipError(error.message, { code: error.code })),
+        ],
+      });
+    }
+    return {
+      taskId,
+      phase,
+      historicalWriteClaims,
+      effectiveWriteClaims: [],
+      writeClaims: [],
+      claimState: "RELEASED_BY_COMPLETION",
+      mutationAllowed: false,
+      recovery: null,
+      recoveryStatus: "NOT_APPLICABLE",
+      valid: true,
+      ownershipValid: true,
+      reasonCodes: [],
+      errors: [],
+      ownershipErrors: [],
+    };
+  }
+
+  if (history.activeRecovery) {
+    // The consistency validator above guarantees that the active ledger cycle
+    // and recovery artifact identify the same recovery before this branch.
+    return {
+      taskId,
+      phase,
+      historicalWriteClaims,
+      effectiveWriteClaims: [],
+      writeClaims: [],
+      claimState: "RELEASED_BY_RECOVERY",
+      mutationAllowed: false,
+      recovery,
+      recoveryStatus: "ACTIVE",
+      valid: true,
+      ownershipValid: true,
+      reasonCodes: [],
+      errors: [],
+      ownershipErrors: [],
+    };
+  }
+
+  return {
+    taskId,
+    phase,
+    historicalWriteClaims,
+    effectiveWriteClaims: normalizedDescriptorClaims,
+    writeClaims: normalizedDescriptorClaims,
+    claimState: "ACTIVE",
+    mutationAllowed: true,
+    recovery: null,
+    recoveryStatus: history.completedRecoveries.length > 0 ? "COMPLETED" : "ABSENT",
+    valid: true,
+    ownershipValid: true,
+    reasonCodes: [],
+    errors: [],
+    ownershipErrors: [],
+  };
+}
+
+/**
+ * Resolve claim ownership from the task descriptor, work state, recovery
+ * tombstone, and the complete validated task ledger. Any disagreement retains
+ * every claim that can be recovered from validated inputs and fails closed.
+ */
+export async function resolveTaskClaimState(target, options = {}) {
+  const evidence = await collectTaskClaimEvidence(target, options);
+  return classifyTaskClaimState(evidence);
+}
+
+export async function assertTaskMutationAllowed(target, options = {}) {
+  const result = await resolveTaskClaimState(target, options);
+  if (result.mutationAllowed) return result;
+
+  const inconsistent = result.claimState === "INCONSISTENT";
+  const error = new Error(inconsistent
+    ? `Task ${result.taskId} claim ownership is inconsistent; ordinary mutation is blocked`
+    : result.claimState === "RELEASED_BY_COMPLETION"
+      ? `Task ${result.taskId} is COMPLETE and cannot be mutated`
+      : `Task ${result.taskId} is RECOVERED and its write claims are released; run task-resume before ordinary mutation`);
+  error.code = inconsistent
+    ? E_TASK_CLAIM_OWNERSHIP_INCONSISTENT
+    : result.claimState === "RELEASED_BY_COMPLETION"
+      ? E_TASK_COMPLETE
+      : E_TASK_RECOVERED;
+  error.taskId = result.taskId;
+  error.claimState = result.claimState;
+  error.reasonCodes = result.reasonCodes;
+  error.errors = result.errors;
+  error.recovery = result.recovery;
+  throw error;
+}

package/src/core/task-command.js

@@ -1,5 +1,6 @@
-import { resolveTaskContext } from "./task-context.js";
-import { withTaskLock } from "./task-lock.js";
+import { resolveTaskContext, TASK_SELECTION_MODES } from "./task-context.js";
+import { withTaskTransaction } from "./transaction.js";
+import { assertTaskMutationAllowed } from "./task-claim-state.js";
 
 export async function withResolvedTask(
   target,
@@ -12,6 +13,7 @@ export async function withResolvedTask(
     taskId: taskOption,
     explicitRequired,
     packageRoot: options.packageRoot,
+    selectionMode: TASK_SELECTION_MODES.READ,
   });
 
   return callback(taskContext);
@@ -29,11 +31,13 @@ export async function withTaskMutation(
     taskId: taskOption,
     explicitRequired,
     packageRoot: options.packageRoot,
+    selectionMode: TASK_SELECTION_MODES.MUTATION,
   });
 
   if (taskContext) {
-    return withTaskLock(target, taskContext.taskId, operation, async () => {
-      return callback(taskContext);
+    return withTaskTransaction({ target, taskId: taskContext.taskId, operation, packageRoot: options.packageRoot, recordCommitEvent: true }, async (transaction) => {
+      await assertTaskMutationAllowed(target, { taskId: taskContext.taskId, packageRoot: options.packageRoot });
+      return callback({ ...taskContext, transaction });
     });
   }