@cassiomc1/forgeloop 1.3.0 → 1.5.0

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/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 { 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,10 +31,12 @@ export async function withTaskMutation(
     taskId: taskOption,
     explicitRequired,
     packageRoot: options.packageRoot,
+    selectionMode: TASK_SELECTION_MODES.MUTATION,
   });
 
   if (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 });
     });
   }