@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

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

@@ -1,3 +1,6 @@
+import { needsExistingProjectScope } from "../storage/existing-project-scope.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+import { ledgerTypeSummary } from "./ledger-event-collection.js";
 import {
   E_COMPLETION_OWNERSHIP_UNPROVEN,
   E_TASK_CLAIM_OWNERSHIP_INCONSISTENT,
@@ -6,8 +9,8 @@ import {
   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 { validateEventLedger, validatePortableEventLedger, validateStateLedgerCoherence, withEventLedgerAudit } from "./events.js";
+import { classifyRecoveryHistory, summarizeRecoveryHistory } from "./recovery-history.js";
 import { readTaskDescriptor } from "./task-descriptor.js";
 import { normalizeWriteClaims } from "./task-scope.js";
 import {
@@ -15,6 +18,35 @@ import {
   validateTaskRecoveryConsistency,
 } from "./task-recovery.js";
 import { readWorkState } from "./work-state.js";
+import { readContract } from "./contract.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+  resolveEffectiveContractBootstrapRepairAnchor,
+  resolveCanonicalPostRepairCheckpointBinding,
+  resolveCanonicalPostRepairRouteBinding,
+  sameCanonicalGuideList,
+} from "./contract-bootstrap-recovery.js";
+import { canonicalFingerprint } from "./artifacts.js";
+import { stateIdentityErrors } from "./completion-relationships.js";
+import { routeCheckpointMustMatchCurrentRoute } from "./resumability.js";
+
+const REPAIR_PHASE_EVENTS = Object.freeze({
+  CONTRACT_READY: "CONTRACT_VALIDATED",
+  ROUTED: "ROUTE_VALIDATED",
+  DESIGNING: "DESIGN_GATE_STARTED",
+  PLANNED: "PLAN_RECORDED",
+  EXECUTING: "EXECUTION_STARTED",
+  VERIFYING: "VERIFICATION_STARTED",
+  DIAGNOSING: "VERIFICATION_STARTED",
+  CORRECTING: "VERIFICATION_STARTED",
+  REVIEWING: "REVIEW_STARTED",
+  COMPLETE: "COMPLETION_VALIDATED",
+});
+
+const REPAIR_ROUTE_PHASES = new Set([
+  "ROUTED", "DESIGNING", "PLANNED", "EXECUTING", "VERIFYING", "DIAGNOSING", "CORRECTING", "REVIEWING", "COMPLETE",
+]);
 
 function ownershipError(message, cause = null) {
   return {
@@ -24,10 +56,173 @@ function ownershipError(message, cause = null) {
   };
 }
 
+function repairInvalid(message) {
+  return ownershipError(message, { code: "E_CONTRACT_BOOTSTRAP_REPAIR_INVALID" });
+}
+
+function lateRouteCheckpointErrors(events, state, marker) {
+  if (routeCheckpointMustMatchCurrentRoute(state.phase) || !REPAIR_PHASE_EVENTS[state.phase]) return [];
+  const checkpoint = resolveCanonicalPostRepairCheckpointBinding(events, marker);
+  if (!checkpoint) {
+    return [repairInvalid("Repaired late-phase state lacks an immutable route checkpoint binding")];
+  }
+  if (state.routeFingerprint !== checkpoint.routeFingerprint
+    || !sameCanonicalGuideList(state.selectedGuides, checkpoint.selectedGuides)) {
+    return [repairInvalid("Late-phase checkpoint route identity was rewritten after the canonical checkpoint binding")];
+  }
+  return [];
+}
+
+function repairArtifactErrors(artifacts) {
+  return [
+    ...(artifacts?.contractError
+      ? [repairInvalid(`Current contract artifact is invalid after a recorded repair: ${artifacts.contractError}`)]
+      : []),
+    ...(artifacts?.routeError
+      ? [repairInvalid(`Current route artifact is invalid after a recorded repair: ${artifacts.routeError}`)]
+      : []),
+  ];
+}
+
+function repairAnchorErrors(details, state, artifacts) {
+  const errors = [];
+  if (state.phase !== details.reconstructedPhase) {
+    errors.push(repairInvalid(
+      `Work-state phase ${state.phase} does not match repair anchor phase ${details.reconstructedPhase}`,
+    ));
+  }
+  if (canonicalFingerprint(state) !== details.reconstructedStateFingerprint) {
+    errors.push(repairInvalid("Work-state fingerprint does not match the repair anchor"));
+  }
+  const stateRouteFingerprint = state.routeFingerprint ?? null;
+  const currentRouteFingerprint = artifacts?.route?.fingerprint ?? null;
+  if (stateRouteFingerprint !== details.routeFingerprint
+    || currentRouteFingerprint !== details.routeFingerprint) {
+    errors.push(repairInvalid("Current route identity does not match the repair anchor"));
+  }
+  return errors;
+}
+
+function evolvedRepairErrors(anchor, events, state, artifacts) {
+  const errors = [];
+  const contract = artifacts?.contract ?? null;
+  const route = artifacts?.route ?? null;
+  if (!contract) errors.push(repairInvalid("Current contract is unavailable after a recorded repair"));
+  const routeRequired = REPAIR_ROUTE_PHASES.has(state.phase) || state.routeFingerprint !== undefined;
+  if (routeRequired && !route) {
+    errors.push(repairInvalid("Current route is required by the evolved task state but is unavailable"));
+  }
+  if (contract) {
+    const routeErrors = stateIdentityErrors({ contract, route, state });
+    const checkpointMustMatch = routeCheckpointMustMatchCurrentRoute(state.phase);
+    errors.push(...routeErrors
+      .filter((error) => checkpointMustMatch || error.code !== "E_ROUTE_GUIDE_MISMATCH")
+      .map((error) => repairInvalid(error.message)));
+  }
+  const currentRouteFingerprint = route?.fingerprint ?? null;
+  const binding = currentRouteFingerprint !== anchor.details.routeFingerprint
+    ? resolveCanonicalPostRepairRouteBinding(events, anchor.sourceMarker, currentRouteFingerprint)
+    : null;
+  if (currentRouteFingerprint !== anchor.details.routeFingerprint && !binding) {
+    errors.push(repairInvalid("Changed route identity lacks a canonical post-repair route binding"));
+  }
+  errors.push(...lateRouteCheckpointErrors(events, state, anchor.sourceMarker));
+  errors.push(...validateStateLedgerCoherence(state, events).map((error) => repairInvalid(error.message)));
+  const requiredEvent = REPAIR_PHASE_EVENTS[state.phase];
+  if (requiredEvent && !ledgerTypeSummary(events, requiredEvent).count) {
+    errors.push(repairInvalid(`Current work-state phase ${state.phase} is not supported by the repair ledger history`));
+  }
+  return errors;
+}
+
+function validateContractBootstrapRepairConsistency(taskId, events, state, artifacts) {
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+  if (!anchor) {
+    if (!ledgerTypeSummary(events, CONTRACT_BOOTSTRAP_REPAIR_EVENT).count) return [];
+    return [repairInvalid("Contract bootstrap repair marker is invalid")];
+  }
+  if (!state) return [repairInvalid("Work-state is missing after a recorded contract bootstrap repair")];
+  const details = anchor.details;
+  const errors = [];
+  if (state.taskId !== taskId) errors.push(repairInvalid("Work-state taskId does not match the repaired task"));
+  if (!Number.isInteger(state.revision) || state.revision < 0) {
+    return [...errors, repairInvalid("Work-state revision is missing or invalid after a recorded repair")];
+  }
+  const anchorRevision = details.reconstructedStateRevision;
+  if (state.revision < anchorRevision) {
+    return [...errors, repairInvalid("Work-state revision rolled back behind the repair anchor")];
+  }
+  if (state.contractFingerprint !== details.contractFingerprint) {
+    errors.push(repairInvalid("Work-state contract fingerprint does not match repair-time contract identity"));
+  }
+  errors.push(...repairArtifactErrors(artifacts));
+  return state.revision === anchorRevision
+    ? [...errors, ...repairAnchorErrors(details, state, artifacts)]
+    : [...errors, ...evolvedRepairErrors(anchor, events, state, artifacts)];
+}
+
+/**
+ * Async cross-artifact consistency collector for a recorded contract bootstrap
+ * repair. The pure classifier stays filesystem-free; this reads the current
+ * task-scoped contract and route artifacts through their canonical readers so
+ * schema validation, artifact bounds, task-scoped paths, and fingerprint
+ * semantics stay consistent with the rest of the protocol.
+ *
+ * With no repair marker this performs no extra work.
+ */
+async function collectContractBootstrapRepairConsistency(target, packageRoot, taskId, events, state) {
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(events);
+  if (!anchor) return null;
+  const details = anchor.details;
+  const artifacts = { contract: null, route: null, contractError: null, routeError: null };
+
+  // Contract binding: the current contract must exist, validate, and bind to
+  // the marker and work state.
+  try {
+    const contract = await readContract(target, packageRoot, { taskId });
+    artifacts.contract = contract;
+    if (contract.fingerprint !== details.contractFingerprint) {
+      artifacts.contractError = `contract fingerprint ${contract.fingerprint} does not match marker contract fingerprint ${details.contractFingerprint}`;
+    } else if (state && state.contractFingerprint !== details.contractFingerprint) {
+      artifacts.contractError = "work-state contract fingerprint does not match marker contract fingerprint";
+    }
+  } catch (error) {
+    if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
+    artifacts.contractError = error.code === "ARTIFACT_MISSING"
+      ? "contract artifact is missing after a recorded repair"
+      : `contract artifact is invalid after a recorded repair: ${error.message}`;
+  }
+
+  // Route binding is anchored exactly at repair time, then follows the
+  // current state/route identity after the checkpoint advances.
+  const routeRequired = state && (REPAIR_ROUTE_PHASES.has(state.phase)
+    || state.routeFingerprint !== undefined);
+  if (routeRequired || details.routeFingerprint !== null) {
+    try {
+      const route = await readPersistedRoute(target, packageRoot, { taskId });
+      artifacts.route = route;
+      if (route.value?.contractFingerprint !== undefined
+        && route.value.contractFingerprint !== details.contractFingerprint) {
+        artifacts.routeError = "route artifact contract binding does not match repair anchor contract fingerprint";
+      }
+    } catch (error) {
+      if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
+      artifacts.routeError = error.code === "ARTIFACT_MISSING"
+        ? "route artifact is missing after a routed repair"
+        : `route artifact is invalid after a routed repair: ${error.message}`;
+    }
+  }
+
+  return artifacts;
+}
+
 function appendClaims(target, claims, errors, source) {
   if (claims === undefined || claims === null) return;
   try {
-    target.push(...normalizeWriteClaims(claims));
+    const normalized = normalizeWriteClaims(claims);
+    if (target instanceof Set || typeof target.add === "function") {
+      for (const claim of normalized) target.add(claim);
+    } else target.push(...normalized);
   } catch (error) {
     errors.push(ownershipError(`Invalid ${source} write claims: ${error.message}`, error));
   }
@@ -39,12 +234,12 @@ function appendClaims(target, claims, errors, source) {
  * 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, {
+async function collectClaimEvidence(target, {
   taskId,
   packageRoot,
   descriptor: suppliedDescriptor = null,
   state: suppliedState = null,
-} = {}) {
+} = {}, suppliedLedger = null) {
   const errors = [];
   let descriptor = suppliedDescriptor;
   let state = suppliedState;
@@ -55,6 +250,7 @@ export async function collectTaskClaimEvidence(target, {
     try {
       descriptor = (await readTaskDescriptor(target, taskId, packageRoot)).value;
     } catch (error) {
+      if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
       errors.push(ownershipError(`Task descriptor cannot establish claim ownership: ${error.message}`, error));
     }
   }
@@ -62,6 +258,7 @@ export async function collectTaskClaimEvidence(target, {
     try {
       state = await readWorkState(target, { taskId, packageRoot });
     } catch (error) {
+      if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
       errors.push(ownershipError(`Task work state cannot establish claim ownership: ${error.message}`, error));
     }
   }
@@ -69,14 +266,27 @@ export async function collectTaskClaimEvidence(target, {
   try {
     recovery = (await readTaskRecovery(target, { taskId, packageRoot }))?.value ?? null;
   } catch (error) {
+    if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
     errors.push(ownershipError(`Task recovery artifact cannot establish claim ownership: ${error.message}`, error));
   }
 
   try {
-    ledger = await validateEventLedger(target, packageRoot, { taskId });
+    ledger = suppliedLedger ?? await (getOperationalStore(target) || await needsExistingProjectScope(target) ? validateEventLedger : validatePortableEventLedger)(target, packageRoot, { taskId });
   } catch (error) {
+    if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
     errors.push(ownershipError(`Task event ledger cannot establish claim ownership: ${error.message}`, error));
   }
+  const repairArtifacts = await collectContractBootstrapRepairConsistency(target, packageRoot, taskId, ledger.events, state);
+  return buildTaskClaimEvidence({ taskId, descriptor, state, recovery, ledger, repairArtifacts, initialErrors: errors });
+}
+
+export async function collectTaskClaimEvidence(target, options = {}) {
+  return collectClaimEvidence(target, options);
+}
+
+/** Shared pure ownership evidence projection for filesystem and store snapshots. */
+export function buildTaskClaimEvidence({ taskId, descriptor, state, recovery, ledger, repairArtifacts = null, initialErrors = [] }) {
+  const errors = [...initialErrors];
   if (!ledger.valid) {
     for (const error of ledger.errors) {
       errors.push(ownershipError(`Task event ledger is invalid: ${error.message}`, error));
@@ -85,16 +295,29 @@ export async function collectTaskClaimEvidence(target, {
   if (ledger.events.some((event) => event.taskId !== taskId)) {
     errors.push(ownershipError(`Task event ledger contains an event for a different task`));
   }
+  if (state) {
+    for (const error of validateStateLedgerCoherence(state, ledger.events)) {
+      if (![
+        "E_CHECKPOINT_REVALIDATION_UNSAFE",
+        "E_CONTRACT_REVISION_UNSAFE",
+      ].includes(error.code)) continue;
+      errors.push(ownershipError(`Task state and event ledger are incoherent: ${error.message}`, error));
+    }
+  }
+
+  const repairConsistencyErrors = validateContractBootstrapRepairConsistency(taskId, ledger.events, state, repairArtifacts);
+  errors.push(...repairConsistencyErrors);
 
-  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");
-  }
+  const historicalClaims = new Set(normalizedDescriptorClaims);
+  const observeRecovery = cycle => appendClaims(historicalClaims, cycle.event?.details?.releasedClaims, errors, "recovery ledger");
+  const history = Array.isArray(ledger.events)
+    ? classifyRecoveryHistory(ledger.events)
+    : summarizeRecoveryHistory(ledger.events, observeRecovery);
+  if (Array.isArray(ledger.events)) for (const cycle of history.recoveries) observeRecovery(cycle);
   appendClaims(historicalClaims, recovery?.releasedClaims, errors, "recovery artifact");
 
   return {
@@ -106,7 +329,7 @@ export async function collectTaskClaimEvidence(target, {
     ledger,
     history,
     normalizedDescriptorClaims,
-    historicalWriteClaims: normalizeWriteClaims(historicalClaims),
+    historicalWriteClaims: normalizeWriteClaims([...historicalClaims]),
     errors,
   };
 }
@@ -229,7 +452,7 @@ export function classifyTaskClaimState(evidence) {
     claimState: "ACTIVE",
     mutationAllowed: true,
     recovery: null,
-    recoveryStatus: history.completedRecoveries.length > 0 ? "COMPLETED" : "ABSENT",
+    recoveryStatus: (history.completedRecoveryCount ?? history.completedRecoveries.length) > 0 ? "COMPLETED" : "ABSENT",
     valid: true,
     ownershipValid: true,
     reasonCodes: [],
@@ -243,9 +466,20 @@ export function classifyTaskClaimState(evidence) {
  * 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 withTaskClaimEvidence(target, options, callback) {
+  let store;
+  try { store = getOperationalStore(target); } catch { /* Preserve collected fail-closed evidence for invalid contexts. */ }
+  if (store && !store.hasPreparedMutations()
+    && typeof options.taskId === "string" && options.taskId) {
+    return withEventLedgerAudit(target, options.packageRoot, { taskId: options.taskId }, async ledger => (
+      callback(await collectClaimEvidence(target, options, ledger))
+    ));
+  }
+  return callback(await collectTaskClaimEvidence(target, options));
+}
+
 export async function resolveTaskClaimState(target, options = {}) {
-  const evidence = await collectTaskClaimEvidence(target, options);
-  return classifyTaskClaimState(evidence);
+  return withTaskClaimEvidence(target, options, classifyTaskClaimState);
 }
 
 export async function assertTaskMutationAllowed(target, options = {}) {

package/src/core/task-command.js

@@ -2,6 +2,8 @@ import { resolveTaskContext, TASK_SELECTION_MODES } from "./task-context.js";
 import { withTaskTransaction } from "./transaction.js";
 import { assertTaskMutationAllowed } from "./task-claim-state.js";
 import { assertWorkspaceBinding } from "./workspace-binding.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+import { withTaskLock } from "./task-lock.js";
 
 export async function withResolvedTask(
   target,
@@ -27,15 +29,33 @@ export async function withTaskMutation(
   callback,
   { explicitRequired = false, skipWorkspaceBinding = false } = {},
 ) {
+  if (!getOperationalStore(target)) {
+    const { withProjectStorage } = await import("../storage/project-boundary.js");
+    return withProjectStorage(target, () => withTaskMutation(target, options, operation, callback, { explicitRequired, skipWorkspaceBinding }));
+  }
   const taskOption = options.taskId ?? options.task ?? null;
   const taskContext = await resolveTaskContext(target, {
     taskId: taskOption,
-    explicitRequired,
+    explicitRequired: explicitRequired || Boolean(getOperationalStore(target)),
     packageRoot: options.packageRoot,
     selectionMode: TASK_SELECTION_MODES.MUTATION,
   });
 
   if (taskContext) {
+    if (getOperationalStore(target) && ["run-action", "run-check"].includes(operation)) {
+      return withTaskLock(target, taskContext.taskId, operation, async () => {
+        await withTaskTransaction({ target, taskId: taskContext.taskId, operation: `${operation}:prepare`, packageRoot: options.packageRoot }, async () => {
+          await assertTaskMutationAllowed(target, { taskId: taskContext.taskId, packageRoot: options.packageRoot });
+          if (!skipWorkspaceBinding) await assertWorkspaceBinding(target, { taskId: taskContext.taskId, packageRoot: options.packageRoot, operation });
+        });
+        // External work runs with a durable semantic reservation and no open
+        // database transaction. Its domain services commit intent/outcome in
+        // separate transactions, so a crash cannot erase a durable start.
+        const result = await callback(taskContext);
+        await withTaskTransaction({ target, taskId: taskContext.taskId, operation, packageRoot: options.packageRoot, recordCommitEvent: true }, () => undefined);
+        return result;
+      });
+    }
     return withTaskTransaction({ target, taskId: taskContext.taskId, operation, packageRoot: options.packageRoot, recordCommitEvent: true }, async (transaction) => {
       await assertTaskMutationAllowed(target, { taskId: taskContext.taskId, packageRoot: options.packageRoot });
       if (!skipWorkspaceBinding) {