@cassiomc1/forgeloop 1.2.4 → 1.5.0

package/src/core/completion-ownership.js

@@ -0,0 +1,88 @@
+import { LIFECYCLE_MILESTONES, validateStateLedgerCoherence } from "./events.js";
+
+export const CANONICAL_COMPLETION_EVENT = "COMPLETION_VALIDATED";
+
+/**
+ * Canonical completion ownership proof: the minimal, validator-backed evidence
+ * that the lifecycle itself officially reached COMPLETE. This is intentionally
+ * NOT a re-run of full publication/receipt/evidence semantics — it only proves
+ * that claim ownership may be released because canonical completion exists.
+ *
+ * Returns `{ valid: true, completionEvent }` or `{ valid: false, errors }`.
+ */
+export function validateCompletionOwnershipProof({ taskId, state, ledger }) {
+  const errors = [];
+  if (!taskId || typeof taskId !== "string") {
+    return { valid: false, errors: [{ code: "E_COMPLETION_OWNERSHIP_UNPROVEN", message: "Completion ownership proof requires a taskId" }] };
+  }
+  if (!state || state.phase !== "COMPLETE") {
+    errors.push({ code: "E_COMPLETION_OWNERSHIP_UNPROVEN", message: "Work-state phase is not COMPLETE" });
+  }
+  if (!ledger || ledger.valid !== true) {
+    errors.push({
+      code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+      message: `Task event ledger is invalid; completion cannot be proven${ledger?.errors?.length
+        ? `: ${ledger.errors.map((error) => error.message).join("; ")}`
+        : ""}`,
+    });
+  }
+
+  let completionEvent = null;
+  if (ledger && Array.isArray(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) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: `No canonical ${CANONICAL_COMPLETION_EVENT} event exists for this task`,
+      });
+    } else if (candidates.length > 1) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: `Multiple ${CANONICAL_COMPLETION_EVENT} events exist; completion is ambiguous`,
+      });
+    } else {
+      completionEvent = candidates[0];
+    }
+  }
+
+  if (state && ledger && Array.isArray(ledger.events)) {
+    const coherenceErrors = validateStateLedgerCoherence(state, ledger.events);
+    if (coherenceErrors.length > 0) {
+      for (const error of coherenceErrors) {
+        errors.push({
+          code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+          message: `State/ledger coherence invalid: ${error.message}`,
+        });
+      }
+    }
+  }
+
+  // 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)) {
+    const completionIndex = ledger.events.indexOf(completionEvent);
+    const contradiction = ledger.events.slice(completionIndex + 1).find((event) => {
+      const index = LIFECYCLE_MILESTONES.indexOf(event.event);
+      return index >= LIFECYCLE_MILESTONES.indexOf("VERIFICATION_RECORDED");
+    });
+    if (contradiction) {
+      errors.push({
+        code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+        message: `Lifecycle event ${contradiction.event} follows canonical completion; terminal state contradicted`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, completionEvent: null, errors };
+  }
+  return { valid: true, completionEvent };
+}

package/src/core/completion.js

@@ -4,7 +4,7 @@ import { appendProtocolEvent, LIFECYCLE_MILESTONES, validateEventLedger, validat
 import { evaluatePreflight } from "./preflight.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
-import { readWorkState, writeWorkState, classifyLoadedWorkState } from "./work-state.js";
+import { readWorkState, mutateWorkState, classifyLoadedWorkState } from "./work-state.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { completionRelationshipErrors } from "./completion-relationships.js";
 import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
@@ -517,7 +517,13 @@ export async function runComplete({
       } catch {
         // The evaluator already reports a missing or invalid receipt; evidence-only rejection can persist without one.
       }
-      await writeWorkState(target, next, { packageRoot, taskId, statePath });
+      next.revision = (state.revision ?? 0) + 1;
+      await mutateWorkState(target, {
+        expectedRevision: state.revision ?? 0,
+        packageRoot,
+        taskId,
+        statePath,
+      }, () => next);
       let nextReceipt = null;
       if (receipt) {
         nextReceipt = await createReceipt({
@@ -565,12 +571,18 @@ export async function runComplete({
         publicationStatus: result.publicationStatus,
         lastUpdated: new Date().toISOString(),
       };
+      next.revision = (state.revision ?? 0) + 1;
       const nextReceipt = await createReceipt({
         ...receipt.value,
         stateFingerprint: canonicalFingerprint(next),
         verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
       }, packageRoot, { target, taskId: state.taskId, authorityContext, runtimeContext });
-      await writeWorkState(target, next, { packageRoot, taskId, statePath });
+      await mutateWorkState(target, {
+        expectedRevision: state.revision ?? 0,
+        packageRoot,
+        taskId,
+        statePath,
+      }, () => next);
       await writeJsonArtifact(target, receiptRel, nextReceipt, "execution-receipt", packageRoot);
     }
     const contract = await readContract(target, packageRoot, { taskId, contractPath });

package/src/core/diagnosis.js

@@ -1,5 +1,5 @@
 import { appendProtocolEvent, validateEventLedger } from "./events.js";
-import { readWorkState, writeWorkState } from "./work-state.js";
+import { readWorkState, mutateWorkState } from "./work-state.js";
 import {
   DIAGNOSIS_INFORMATION_GAIN,
   assertDiagnosisDetails,
@@ -110,16 +110,16 @@ export async function recordDiagnosis({
   });
 
   if (existingEvent?.details?.diagnosisFingerprint === requestedFingerprint) {
-    const updatedState = {
-      ...state,
-      diagnosedHypothesis: existingEvent.details.hypothesis,
-      lastUpdated: new Date().toISOString(),
-    };
-    await writeWorkState(target, updatedState, {
+    const updatedState = await mutateWorkState(target, {
+      expectedRevision: state.revision ?? 0,
       packageRoot,
       taskId: taskId ?? null,
       statePath,
-    });
+    }, () => ({
+      ...state,
+      diagnosedHypothesis: existingEvent.details.hypothesis,
+      lastUpdated: new Date().toISOString(),
+    }));
     return {
       event: existingEvent,
       state: updatedState,
@@ -155,12 +155,16 @@ export async function recordDiagnosis({
     { taskId: taskId ?? null, eventsPath },
   );
 
-  const updatedState = {
+  const updatedState = await mutateWorkState(target, {
+    expectedRevision: state.revision ?? 0,
+    packageRoot,
+    taskId: taskId ?? null,
+    statePath,
+  }, () => ({
     ...state,
     diagnosedHypothesis: hypothesis.trim(),
     lastUpdated: new Date().toISOString(),
-  };
-  await writeWorkState(target, updatedState, { packageRoot, taskId: taskId ?? null, statePath });
+  }));
 
   return {
     event,

package/src/core/error-codes.js

@@ -10,6 +10,7 @@ import {
 export const E_TASK_REQUIRED = "E_TASK_REQUIRED";
 export const E_TASK_NOT_FOUND = "E_TASK_NOT_FOUND";
 export const E_TASK_ALREADY_EXISTS = "E_TASK_ALREADY_EXISTS";
+export const E_TASK_COMPLETE = "E_TASK_COMPLETE";
 export const E_TASK_AMBIGUOUS = "E_TASK_AMBIGUOUS";
 export const E_TASK_SELECTOR_CONFLICT = "E_TASK_SELECTOR_CONFLICT";
 export const E_TASK_DESCRIPTOR_INVALID = "E_TASK_DESCRIPTOR_INVALID";
@@ -18,6 +19,7 @@ export const E_TASK_CONTEXT_MISMATCH = "E_TASK_CONTEXT_MISMATCH";
 
 export const E_TASK_LOCKED = "E_TASK_LOCKED";
 export const E_TASK_LOCK_INVALID = "E_TASK_LOCK_INVALID";
+export const E_PROJECT_CLAIMS_LOCK_INCONSISTENT = "E_PROJECT_CLAIMS_LOCK_INCONSISTENT";
 
 export const E_TASK_SCOPE_REQUIRED = "E_TASK_SCOPE_REQUIRED";
 export const E_TASK_SCOPE_CONFLICT = "E_TASK_SCOPE_CONFLICT";
@@ -28,7 +30,19 @@ export const E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE = "E_TASK_CHANGE_ATTRIBUTION_
 
 export const E_TASK_LAYOUT_LEGACY = "E_TASK_LAYOUT_LEGACY";
 export const E_TASK_MIGRATION_INVALID = "E_TASK_MIGRATION_INVALID";
+export const E_TASK_RECOVERY_UNSAFE = "E_TASK_RECOVERY_UNSAFE";
+export const E_TASK_RECOVERY_INCONSISTENT = "E_TASK_RECOVERY_INCONSISTENT";
+export const E_LEGACY_RECOVERY_MIGRATION_INVALID = "E_LEGACY_RECOVERY_MIGRATION_INVALID";
+export const E_COMPLETION_OWNERSHIP_UNPROVEN = "E_COMPLETION_OWNERSHIP_UNPROVEN";
+export const E_TASK_CLAIM_OWNERSHIP_INCONSISTENT = "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT";
+export const E_TASK_RECOVERY_AUTHORIZATION_REQUIRED = "E_TASK_RECOVERY_AUTHORIZATION_REQUIRED";
+export const E_TASK_RECOVERY_AUTHORITY_INVALID = "E_TASK_RECOVERY_AUTHORITY_INVALID";
+export const E_TASK_RECOVERED = "E_TASK_RECOVERED";
+export const E_TASK_NOT_RECOVERED = "E_TASK_NOT_RECOVERED";
+export const E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE = "E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE";
+export const E_TASK_ALREADY_RECOVERED = "E_TASK_ALREADY_RECOVERED";
 export const E_TASK_MIGRATION_IDENTITY_MISMATCH = "E_TASK_MIGRATION_IDENTITY_MISMATCH";
+export const E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED = "E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED";
 
 export const E_DIAGNOSIS_REQUIRED = "E_DIAGNOSIS_REQUIRED";
 export const E_DIAGNOSIS_INVALID = "E_DIAGNOSIS_INVALID";
@@ -150,6 +164,13 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
     meaning: "Multiple tasks exist in the project but no task selector was provided.",
     safeResolution: "Select a task explicitly using --task <id> or FORGELOOP_TASK=<id>.",
   }),
+  E_TASK_COMPLETE: Object.freeze({
+    code: "E_TASK_COMPLETE",
+    category: "task-resolution",
+    classification: "PUBLIC_STABLE",
+    meaning: "A validator-backed COMPLETE task is terminal and cannot be mutated.",
+    safeResolution: "Create or select a non-terminal task for further work; do not modify terminal task state.",
+  }),
   E_TASK_LOCKED: Object.freeze({
     code: "E_TASK_LOCKED",
     category: "concurrency",
@@ -157,12 +178,96 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
     meaning: "Task mutation is currently locked by another concurrent process or run-check.",
     safeResolution: "Wait for the active mutation to complete or inspect the lock with forgeloop task-show.",
   }),
+  E_PROJECT_CLAIMS_LOCK_INCONSISTENT: Object.freeze({
+    code: "E_PROJECT_CLAIMS_LOCK_INCONSISTENT",
+    category: "concurrency",
+    classification: "PUBLIC_STABLE",
+    meaning: "The project-wide claim reservation lock has unknown, corrupt, or concurrently changed ownership metadata.",
+    safeResolution: "Inspect .forgeloop/.claims.lock and retry only after its lease and owner identity can be validated; never force-delete unknown ownership.",
+  }),
   E_TASK_SCOPE_CONFLICT: Object.freeze({
     code: "E_TASK_SCOPE_CONFLICT",
     category: "scope",
     classification: "PUBLIC_STABLE",
     meaning: "Task write claims overlap with another non-complete task in the same checkout.",
-    safeResolution: "Adjust write claims to non-overlapping paths or run tasks in separate worktrees.",
+    safeResolution: "Inspect the conflicting task classification reported in error.conflicts, then reconcile or recover it through its reported official recovery commands before retrying task creation.",
+  }),
+  E_TASK_RECOVERY_UNSAFE: Object.freeze({
+    code: "E_TASK_RECOVERY_UNSAFE",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "Claim-release recovery was refused because the conflicting task is active, inconsistent, already complete, or holds a live lease.",
+    safeResolution: "Resolve the reported classification first; live leases must expire or be released by their owner before recovery.",
+  }),
+  E_TASK_RECOVERY_INCONSISTENT: Object.freeze({
+    code: "E_TASK_RECOVERY_INCONSISTENT",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "Claim-release recovery was refused because the task state, recovery artifact, lock, or event ledger is inconsistent.",
+    safeResolution: "Repair the underlying artifact through its dedicated recovery surface; do not force-complete an unreadable task.",
+  }),
+  E_LEGACY_RECOVERY_MIGRATION_INVALID: Object.freeze({
+    code: "E_LEGACY_RECOVERY_MIGRATION_INVALID",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "The legacy recovery-event repair was refused because the ledger does not match the exact known legacy defect signature, has incompatible later activity, holds a live lock, or is otherwise ambiguous.",
+    safeResolution: "Inspect the structured plan/errors; ambiguous or tampered ledgers stay INCONSISTENT and are never migrated.",
+  }),
+  E_COMPLETION_OWNERSHIP_UNPROVEN: Object.freeze({
+    code: "E_COMPLETION_OWNERSHIP_UNPROVEN",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "Work-state claims COMPLETE but the canonical lifecycle/ledger completion proof is missing or invalid, so historical claims stay reserved.",
+    safeResolution: "Restore the canonical completion event and a valid ledger, or re-run the official completion pipeline; phase=COMPLETE alone never releases claims.",
+  }),
+  E_TASK_CLAIM_OWNERSHIP_INCONSISTENT: Object.freeze({
+    code: "E_TASK_CLAIM_OWNERSHIP_INCONSISTENT",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "ForgeLoop cannot prove whether a task still owns its historical write claims.",
+    safeResolution: "Repair and validate the task descriptor, recovery artifact, and complete event ledger before acquiring overlapping claims or mutating the task.",
+  }),
+  E_TASK_RECOVERY_AUTHORIZATION_REQUIRED: Object.freeze({
+    code: "E_TASK_RECOVERY_AUTHORIZATION_REQUIRED",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "task-recover requires explicit caller acknowledgement; this is not host-attested authority.",
+    safeResolution: "Re-run with --acknowledge-recovery only when evidence shows the task is STALE or ABANDONED; --operator-authorized remains a deprecated alias.",
+  }),
+  E_TASK_RECOVERY_AUTHORITY_INVALID: Object.freeze({
+    code: "E_TASK_RECOVERY_AUTHORITY_INVALID",
+    category: "authority",
+    classification: "PUBLIC_STABLE",
+    meaning: "Recovery authority metadata is invalid or claims host attestation without a host-owned grant reference.",
+    safeResolution: "Use caller acknowledgement, or provide a host-attested recovery grant through a trusted host integration.",
+  }),
+  E_TASK_RECOVERED: Object.freeze({
+    code: "E_TASK_RECOVERED",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "The task released its write claims through recovery and ordinary mutation is suspended.",
+    safeResolution: "Run forgeloop task-resume --task <id> to reacquire the released claims before mutating the task.",
+  }),
+  E_TASK_NOT_RECOVERED: Object.freeze({
+    code: "E_TASK_NOT_RECOVERED",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "task-resume was requested for a task without active recovered state.",
+    safeResolution: "Inspect the task with forgeloop task-show; task-resume is only valid while recovery.json is active.",
+  }),
+  E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE: Object.freeze({
+    code: "E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "Claim-release recovery was refused because canonical lifecycle reconciliation is available.",
+    safeResolution: "Use forgeloop reconcile-closure and the normal verification/completion pipeline instead of task-recover.",
+  }),
+  E_TASK_ALREADY_RECOVERED: Object.freeze({
+    code: "E_TASK_ALREADY_RECOVERED",
+    category: "recovery",
+    classification: "PUBLIC_STABLE",
+    meaning: "The task already has active durable recovered state.",
+    safeResolution: "Inspect the existing recovery metadata; use task-resume to reacquire claims or leave the task recovered.",
   }),
   E_TASK_SCOPE_DIRTY: Object.freeze({
     code: "E_TASK_SCOPE_DIRTY",
@@ -445,6 +550,7 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_REQUIRED,
   E_TASK_NOT_FOUND,
   E_TASK_ALREADY_EXISTS,
+  E_TASK_COMPLETE,
   E_TASK_AMBIGUOUS,
   E_TASK_SELECTOR_CONFLICT,
   E_TASK_DESCRIPTOR_INVALID,
@@ -452,6 +558,7 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_CONTEXT_MISMATCH,
   E_TASK_LOCKED,
   E_TASK_LOCK_INVALID,
+  E_PROJECT_CLAIMS_LOCK_INCONSISTENT,
   E_TASK_SCOPE_REQUIRED,
   E_TASK_SCOPE_CONFLICT,
   E_TASK_SCOPE_DIRTY,
@@ -468,7 +575,19 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE,
   E_TASK_LAYOUT_LEGACY,
   E_TASK_MIGRATION_INVALID,
+  E_TASK_RECOVERY_UNSAFE,
+  E_TASK_RECOVERY_INCONSISTENT,
+  E_LEGACY_RECOVERY_MIGRATION_INVALID,
+  E_COMPLETION_OWNERSHIP_UNPROVEN,
+  E_TASK_CLAIM_OWNERSHIP_INCONSISTENT,
+  E_TASK_RECOVERY_AUTHORIZATION_REQUIRED,
+  E_TASK_RECOVERY_AUTHORITY_INVALID,
+  E_TASK_RECOVERED,
+  E_TASK_NOT_RECOVERED,
+  E_TASK_RECOVERY_OFFICIAL_PATH_AVAILABLE,
+  E_TASK_ALREADY_RECOVERED,
   E_TASK_MIGRATION_IDENTITY_MISMATCH,
+  E_PROTOCOL_MIGRATION_TARGET_UNSUPPORTED,
   E_CHECK_INERT,
   E_CHECK_MUTATION_NOT_DETECTED,
   E_POLICY_DRIFT,
@@ -487,3 +606,19 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_POLICY_INITIALIZATION_FAILED,
   E_INIT_KIT_CONFLICT,
 ]));
+
+/**
+ * Complete public registry.  Older callers can retain PUBLIC_ERROR_CODES while
+ * documentation and compatibility handshakes enumerate every stable code.
+ */
+export const PUBLIC_ERROR_REGISTRY = Object.freeze(
+  Object.fromEntries([...ALL_KNOWN_ERROR_CODES].sort().map((code) => [code, Object.freeze(
+    PUBLIC_ERROR_CODES[code] ?? {
+      code,
+      category: "protocol",
+      classification: "PUBLIC_STABLE",
+      meaning: "A ForgeLoop protocol validation or lifecycle condition was not satisfied.",
+      safeResolution: "Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json.",
+    },
+  )])),
+);