@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.4

package/src/core/phase.js

@@ -63,6 +63,39 @@ const LATE_PHASES = new Set([
   "COMPLETE",
 ]);
 
+/**
+ * Pure prerequisite for the `DIAGNOSING -> CORRECTING` edge.
+ *
+ * Extracted so the filesystem advance and the SQLite store advance enforce the
+ * identical rule through one owner. The store implementation must not restate
+ * this; it calls this function with its own loaded evidence.
+ *
+ * Throws `E_DIAGNOSIS_REQUIRED` when no append-only diagnosis exists for the
+ * active verification cycle, and `E_DIAGNOSIS_NO_NEW_INFORMATION` when the
+ * diagnosis carries no new information.
+ */
+export function assertDiagnosingToCorrectingTransition({ state, events, resolveDiagnosis }) {
+  const cycle = state?.verificationCycle ?? 1;
+  const diagEvent = resolveDiagnosis(events, state?.taskId, cycle);
+  if (!diagEvent) {
+    throw phaseError(
+      "E_DIAGNOSIS_REQUIRED",
+      "DIAGNOSING -> CORRECTING requires an append-only diagnosis record for the active verification cycle",
+      [],
+    );
+  }
+  const structured = diagEvent.sourceModel === "STRUCTURED_DIAGNOSTIC_CASE_V1";
+  const gainClassification = structured ? null : diagEvent.details?.informationGain;
+  if (!diagEvent.details || (structured ? false : gainClassification === "NONE")) {
+    throw phaseError(
+      "E_DIAGNOSIS_NO_NEW_INFORMATION",
+      "The proposed retry repeats the previous hypothesis with the same evidence without new information",
+      [],
+    );
+  }
+  return diagEvent;
+}
+
 async function readPhaseIdentityArtifacts(target, state, toPhase, packageRoot, options, paths) {
   const scopedTaskId = options.taskId ?? null;
   const requireContract = LATE_PHASES.has(state.phase)
@@ -75,6 +108,7 @@ async function readPhaseIdentityArtifacts(target, state, toPhase, packageRoot, o
   try {
     contract = await readContract(target, packageRoot, { taskId: scopedTaskId, contractPath: options.contractPath });
   } catch (error) {
+    if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
     if (error.code === "ARTIFACT_MISSING" && !requireContract) {
       contract = null;
     } else {
@@ -88,6 +122,7 @@ async function readPhaseIdentityArtifacts(target, state, toPhase, packageRoot, o
   try {
     route = await readPersistedRoute(target, packageRoot, { taskId: scopedTaskId, routePath: options.routePath });
   } catch (error) {
+    if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
     if (error.code === "ARTIFACT_MISSING" && !requireRoute) {
       route = null;
     } else {
@@ -185,24 +220,24 @@ function isRevisionPlanRepeat(events, eventType) {
     && isRevisionEpochPlanRepeat(events, events.length, { event: eventType });
 }
 
+async function assertRequiredPhaseArtifact(read, toPhase, relativePath) {
+  try { await read(); }
+  catch (error) {
+    if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
+    throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${relativePath}: ${error.message}`, [relativePath]);
+  }
+}
+
 async function assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext, options = {}) {
   const scopedTaskId = options.taskId ?? null;
   const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
   const routeRel = options.routePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "route") : ARTIFACT_PATHS.route);
 
   if (toPhase === "CONTRACT_READY" || toPhase === "ROUTED" || toPhase === "EXECUTING") {
-    try {
-      await readContract(target, packageRoot, { taskId: scopedTaskId, contractPath: options.contractPath });
-    } catch (error) {
-      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${contractRel}: ${error.message}`, [contractRel]);
-    }
+    await assertRequiredPhaseArtifact(() => readContract(target, packageRoot, { taskId: scopedTaskId, contractPath: options.contractPath }), toPhase, contractRel);
   }
   if (toPhase === "ROUTED" || toPhase === "EXECUTING") {
-    try {
-      await readPersistedRoute(target, packageRoot, { taskId: scopedTaskId, routePath: options.routePath });
-    } catch (error) {
-      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${routeRel}: ${error.message}`, [routeRel]);
-    }
+    await assertRequiredPhaseArtifact(() => readPersistedRoute(target, packageRoot, { taskId: scopedTaskId, routePath: options.routePath }), toPhase, routeRel);
   }
   if (toPhase === "EXECUTING" && scopedTaskId) {
     try {
@@ -215,6 +250,7 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot, aut
     try {
       await assertExecutionPrerequisites({ target, state, packageRoot, ...options, taskId: scopedTaskId, runtimeContext });
     } catch (error) {
+      if (error.code === "E_STATE_REVISION_CONFLICT") throw error;
       throw phaseError(error.code, error.message, error.artifacts);
     }
   }
@@ -247,8 +283,75 @@ async function appendRepairRouteCheckpoint({ target, packageRoot, taskId, state,
   }, packageRoot, { taskId, eventsPath: eventsRel });
 }
 
+/** Shared receipt refresh used by phase advancement on either storage source. */
+export async function preparePhaseReceipt({ target, packageRoot, taskId, state, next, receiptRel, contractPath = null, routePath = null, statePath = null, authorityContext, runtimeContext, readers = null }) {
+  let nextReceipt = null;
+  try {
+    const receipt = await (readers?.readReceipt ?? readJsonArtifact)(target, receiptRel, "execution-receipt", packageRoot);
+    const contract = await (readers?.readContract ?? readContract)(target, packageRoot, { taskId, contractPath });
+    const route = await (readers?.readRoute ?? readPersistedRoute)(target, packageRoot, { taskId, routePath });
+    const preflight = await evaluatePreflight({ target, packageRoot, taskId, contractPath, routePath, statePath, readers });
+    const requiredEvidence = await requiredEvidenceForTarget({
+      target,
+      contract,
+      route,
+      packageRoot,
+      additionalEvidence: preflight.policy?.requiredEvidence ?? [],
+    });
+    await validateReceipt(receipt.value, packageRoot, {
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
+    });
+    assertCompletionRelationships({
+      contract,
+      route,
+      state,
+      receipt: receipt.value,
+      requiredEvidence,
+      requireRequiredChecks: false,
+      requireReceiptStateFingerprint: false,
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
+    });
+    nextReceipt = await createReceipt({
+      ...receipt.value,
+      stateFingerprint: canonicalFingerprint(next),
+      verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
+    }, packageRoot, {
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
+    });
+    assertCompletionRelationships({
+      contract,
+      route,
+      state: next,
+      receipt: nextReceipt,
+      requiredEvidence,
+      requireRequiredChecks: false,
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
+    });
+  } catch (error) {
+    if (error.code !== "ARTIFACT_MISSING") throw error;
+  }
+  return nextReceipt;
+}
+
 export async function advanceWorkState(target, toPhase, options = {}) {
-  const normalizedOptions = typeof options === "string" ? { packageRoot: options } : options;
+  assertWorkPhase(toPhase);
+  let normalizedOptions = typeof options === "string" ? { packageRoot: options } : options;
+  if (!normalizedOptions.taskId) {
+    const state = await readWorkState(target, normalizedOptions);
+    normalizedOptions = { ...normalizedOptions, taskId: state?.taskId };
+  }
   if (!normalizedOptions.taskId || await getTaskTransaction(target)) {
     return advanceWorkStateInternal(target, toPhase, normalizedOptions);
   }
@@ -274,8 +377,6 @@ async function advanceWorkStateInternal(target, toPhase, normalizedOptions) {
     receiptPath = null,
     eventsPath = null,
   } = normalizedOptions;
-  assertWorkPhase(toPhase);
-
   let state = await readWorkState(target, { packageRoot, taskId, statePath });
   const stateRel = statePath ?? (taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state);
   if (!state) throw phaseError("E_PHASE_PREREQUISITE_MISSING", "Cannot advance without work state", [stateRel]);
@@ -392,35 +493,35 @@ async function advanceWorkStateInternal(target, toPhase, normalizedOptions) {
     }
   }
   if (toPhase === "CORRECTING" && state.phase === "DIAGNOSING") {
-    const cycle = state.verificationCycle ?? 1;
-    const diagEvent = resolveCurrentCycleDiagnostic(ledger.events, state.taskId, cycle);
-    if (!diagEvent) {
-      throw phaseError(
-        "E_DIAGNOSIS_REQUIRED",
-        "DIAGNOSING -> CORRECTING requires an append-only diagnosis record for the active verification cycle",
-        [eventsRel],
-      );
+    // Shared rule owner: the same pure prerequisite used by the SQLite store
+    // advance, so the two backends cannot drift on this edge.
+    let cycle = state.verificationCycle ?? 1;
+    let diagEvent;
+    try {
+      diagEvent = assertDiagnosingToCorrectingTransition({
+        state,
+        events: ledger.events,
+        resolveDiagnosis: resolveCurrentCycleDiagnostic,
+      });
+    } catch (error) {
+      throw phaseError(error.code, error.message, [eventsRel]);
     }
-    let stalledNoGain = false;
+    cycle = state.verificationCycle ?? 1;
     if (diagEvent.sourceModel === "STRUCTURED_DIAGNOSTIC_CASE_V1") {
-      // One canonical structured-stall truth, shared with progress/reflect.
+      // The shared rule intentionally omits the structured-stall evaluation,
+      // which depends on progress/reflect projections. Re-check it here so the
+      // filesystem behavior is unchanged.
       const stall = evaluateStructuredDiagnosticStall(
         buildInformationGainProjection(ledger.events, state.taskId),
         { verificationCycle: cycle },
       );
-      stalledNoGain = stall.stalled;
-    }
-    const gainClassification = diagEvent.sourceModel === "STRUCTURED_DIAGNOSTIC_CASE_V1"
-      ? null
-      : diagEvent.details?.informationGain;
-    if (!diagEvent.details
-      || stalledNoGain
-      || (diagEvent.sourceModel !== "STRUCTURED_DIAGNOSTIC_CASE_V1" && gainClassification === "NONE")) {
-      throw phaseError(
-        "E_DIAGNOSIS_NO_NEW_INFORMATION",
-        "The proposed retry repeats the previous hypothesis with the same evidence without new information",
-        [eventsRel],
-      );
+      if (stall.stalled) {
+        throw phaseError(
+          "E_DIAGNOSIS_NO_NEW_INFORMATION",
+          "The proposed retry repeats the previous hypothesis with the same evidence without new information",
+          [eventsRel],
+        );
+      }
     }
   }
   if (toPhase === "VERIFYING" && state.phase === "CORRECTING") {
@@ -479,63 +580,7 @@ async function advanceWorkStateInternal(target, toPhase, normalizedOptions) {
     stateRel,
     eventsRel,
   });
-  let nextReceipt = null;
-  try {
-    const receipt = await readJsonArtifact(target, receiptRel, "execution-receipt", packageRoot);
-    const contract = await readContract(target, packageRoot, { taskId, contractPath });
-    const route = await readPersistedRoute(target, packageRoot, { taskId, routePath });
-    const preflight = await evaluatePreflight({ target, packageRoot, taskId, contractPath, routePath, statePath });
-    const requiredEvidence = await requiredEvidenceForTarget({
-      target,
-      contract,
-      route,
-      packageRoot,
-      additionalEvidence: preflight.policy?.requiredEvidence ?? [],
-    });
-    await validateReceipt(receipt.value, packageRoot, {
-      target,
-      taskId: contract?.value?.taskId,
-      authorityContext,
-      runtimeContext,
-    });
-    assertCompletionRelationships({
-      contract,
-      route,
-      state,
-      receipt: receipt.value,
-      requiredEvidence,
-      requireRequiredChecks: false,
-      requireReceiptStateFingerprint: false,
-      target,
-      taskId: contract?.value?.taskId,
-      authorityContext,
-      runtimeContext,
-    });
-    nextReceipt = await createReceipt({
-      ...receipt.value,
-      stateFingerprint: canonicalFingerprint(next),
-      verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
-    }, packageRoot, {
-      target,
-      taskId: contract?.value?.taskId,
-      authorityContext,
-      runtimeContext,
-    });
-    assertCompletionRelationships({
-      contract,
-      route,
-      state: next,
-      receipt: nextReceipt,
-      requiredEvidence,
-      requireRequiredChecks: false,
-      target,
-      taskId: contract?.value?.taskId,
-      authorityContext,
-      runtimeContext,
-    });
-  } catch (error) {
-    if (error.code !== "ARTIFACT_MISSING") throw error;
-  }
+  const nextReceipt = await preparePhaseReceipt({ target, packageRoot, taskId, state, next, receiptRel, contractPath, routePath, statePath, authorityContext, runtimeContext });
   await mutateWorkState(target, {
     expectedRevision: state.revision ?? 0,
     packageRoot,

package/src/core/policy-engine.js

@@ -1,10 +1,11 @@
+import { withNativeReadScope } from "./native-storage.js";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileExists } from "./filesystem.js";
 import { PROJECT_ARTIFACT_PATHS, taskArtifactPath } from "./task-paths.js";
 import { assertJsonLimits } from "./json-safety.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
-import { canonicalFingerprint, writeJsonArtifact } from "./artifacts.js";
+import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { sha256 } from "./manifest.js";
 import { BUILTIN_POLICY_RULES, discoverPolicy } from "./policy-discovery.js";
 import { getPolicyAdapter } from "./policy-adapters.js";
@@ -82,24 +83,22 @@ export async function writePolicyLock(target, lock, packageRoot) {
 }
 
 export async function readTaskPolicySnapshot(target, taskId, packageRoot) {
-  const relPath = taskArtifactPath(taskId, "policySnapshot");
-  const fullPath = path.join(target, relPath);
-  if (!(await fileExists(fullPath))) {
-    return null;
-  }
-  const raw = await readFile(fullPath, "utf8");
-  assertJsonLimits(raw, relPath);
-  const parsed = JSON.parse(raw);
-  const schema = await readSchema("policy-snapshot", packageRoot);
-  assertSchema(parsed, schema, "policy-snapshot");
-  return parsed;
+  return withNativeReadScope(target, async () => {
+    const relPath = taskArtifactPath(taskId, "policySnapshot");
+    try {
+      return (await readJsonArtifact(target, relPath, "policy-snapshot", packageRoot)).value;
+    } catch (error) {
+      if (error.code === "ARTIFACT_MISSING") return null;
+      throw error;
+    }
+  });
 }
 
 export async function writeTaskPolicySnapshot(target, taskId, snapshot, packageRoot) {
   const relPath = taskArtifactPath(taskId, "policySnapshot");
   const schema = await readSchema("policy-snapshot", packageRoot);
   assertSchema(snapshot, schema, "policy-snapshot");
-  await writeJsonArtifact(target, relPath, snapshot, "policy-snapshot", packageRoot);
+  await writeJsonArtifact(target, relPath, snapshot, "policy-snapshot", packageRoot, { taskId });
   return snapshot;
 }
 

package/src/core/preflight-consistency.js

@@ -1,7 +1,7 @@
 import { ARTIFACT_PATHS } from "./artifacts.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
-import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { appendProtocolEvent, validateEventLedger, withEventLedgerAudit } from "./events.js";
 import { readWorkState } from "./work-state.js";
 import { assertStateIdentity } from "./completion-relationships.js";
 import { ensureResumableState, synchronizePreflightState } from "./resumability.js";
@@ -14,6 +14,7 @@ import {
   validatePersistedPreflight,
 } from "./preflight-model.js";
 
+import { ledgerEventsOfTypes, ledgerTypeSummary } from "./ledger-event-collection.js";
 import { taskArtifactPath } from "./task-paths.js";
 
 async function readOptionalIdentityArtifact(readArtifact, invalidCode, artifactPath) {
@@ -81,15 +82,15 @@ function sameReadyPreflightEvent(event, result) {
 }
 
 function latestContractRevisionSeq(events) {
-  return events.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
+  return ledgerTypeSummary(events, "CONTRACT_REVISED").latest?.seq ?? 0;
 }
 
 function hasCurrentRevisionGate(events, taskId, gate) {
   const revisionSeq = latestContractRevisionSeq(events);
-  return events.some((event) => event.event === "GATE_SATISFIED"
-    && event.taskId === taskId
-    && event.details?.gate === gate
-    && event.seq > revisionSeq);
+  for (const event of ledgerEventsOfTypes(events, ["GATE_SATISFIED"])) {
+    if (event.taskId === taskId && event.details?.gate === gate && event.seq > revisionSeq) return true;
+  }
+  return false;
 }
 
 export async function validateReadyProtocolConsistency({
@@ -102,68 +103,80 @@ export async function validateReadyProtocolConsistency({
 } = {}) {
   if (persisted?.status !== "READY") return [];
   const result = current ?? await evaluateCurrentPreflight({ target, packageRoot, taskId });
-  const errors = [...validatePersistedPreflight(persisted, result)];
+  return withEventLedgerAudit(target, packageRoot, { taskId }, async ledger => {
+    const errors = [...validatePersistedPreflight(persisted, result)];
 
-  const stateRel = taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state;
-  const eventsRel = taskId ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events;
-  const preflightRel = taskId ? taskArtifactPath(taskId, "preflight") : ARTIFACT_PATHS.preflight;
-  const contractRel = taskId ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract;
-  const routeRel = taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route;
-  const gatesRel = taskId ? taskArtifactPath(taskId, "gates") : ARTIFACT_PATHS.gates;
+    const stateRel = taskId ? taskArtifactPath(taskId, "state") : ARTIFACT_PATHS.state;
+    const eventsRel = taskId ? taskArtifactPath(taskId, "events") : ARTIFACT_PATHS.events;
+    const preflightRel = taskId ? taskArtifactPath(taskId, "preflight") : ARTIFACT_PATHS.preflight;
+    const contractRel = taskId ? taskArtifactPath(taskId, "contract") : ARTIFACT_PATHS.contract;
+    const routeRel = taskId ? taskArtifactPath(taskId, "route") : ARTIFACT_PATHS.route;
+    const gatesRel = taskId ? taskArtifactPath(taskId, "gates") : ARTIFACT_PATHS.gates;
 
-  let state = null;
-  try {
-    state = await readWorkState(target, { packageRoot, taskId });
-  } catch (error) {
-    errors.push(issue("E_STATE_INVALID", error.message, [stateRel]));
-  }
-  if (!state) {
-    errors.push(issue(
-      "E_STATE_MISSING_AFTER_PREFLIGHT_READY",
-      "A persisted READY preflight must have a resumable work-state checkpoint",
-      [preflightRel, stateRel],
-    ));
-  } else {
-    if (state.taskId !== persisted.taskId) {
-      errors.push(issue("E_STATE_TASK_MISMATCH", "The resumable checkpoint does not belong to the READY preflight task", [stateRel, preflightRel]));
+    let state = null;
+    try {
+      state = await readWorkState(target, { packageRoot, taskId });
+    } catch (error) {
+      errors.push(issue("E_STATE_INVALID", error.message, [stateRel]));
     }
-    if (state.contractFingerprint !== result.fingerprints.contract) {
-      errors.push(issue("E_CONTRACT_STALE", "The resumable checkpoint does not match the READY contract fingerprint", [stateRel, contractRel]));
+    if (!state) {
+      errors.push(issue(
+        "E_STATE_MISSING_AFTER_PREFLIGHT_READY",
+        "A persisted READY preflight must have a resumable work-state checkpoint",
+        [preflightRel, stateRel],
+      ));
+    } else {
+      if (state.taskId !== persisted.taskId) {
+        errors.push(issue("E_STATE_TASK_MISMATCH", "The resumable checkpoint does not belong to the READY preflight task", [stateRel, preflightRel]));
+      }
+      if (state.contractFingerprint !== result.fingerprints.contract) {
+        errors.push(issue("E_CONTRACT_STALE", "The resumable checkpoint does not match the READY contract fingerprint", [stateRel, contractRel]));
+      }
+      if (state.routeFingerprint !== result.fingerprints.routing) {
+        errors.push(issue("E_ROUTE_STALE", "The resumable checkpoint does not match the READY routing fingerprint", [stateRel, routeRel]));
+      }
+      if (JSON.stringify(state.selectedGuides) !== JSON.stringify(result.routing.guides)) {
+        errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "The resumable checkpoint guides do not match the READY routing result", [stateRel, routeRel]));
+      }
+      if (!sameStringSet(state.requiredGates ?? [], persisted.requiredGates)
+        || !sameStringSet(state.satisfiedGates ?? [], persisted.satisfiedGates)) {
+        errors.push(issue("E_PREFLIGHT_GATES_STALE", "The resumable checkpoint gate sets do not match the READY preflight", [stateRel, preflightRel, gatesRel]));
+      }
     }
-    if (state.routeFingerprint !== result.fingerprints.routing) {
-      errors.push(issue("E_ROUTE_STALE", "The resumable checkpoint does not match the READY routing fingerprint", [stateRel, routeRel]));
+
+    if (!ledger.valid) {
+      errors.push(...ledger.errors.map((error) => issue(error.code ?? "E_EVENT_INVALID", error.message, [eventsRel])));
     }
-    if (JSON.stringify(state.selectedGuides) !== JSON.stringify(result.routing.guides)) {
-      errors.push(issue("E_ROUTE_GUIDE_MISMATCH", "The resumable checkpoint guides do not match the READY routing result", [stateRel, routeRel]));
+    const events = ledger.events ?? [];
+    const requiredEvents = ["CONTRACT_VALIDATED", "ROUTE_VALIDATED"];
+    const observedEvents = new Set();
+    for (const event of ledgerEventsOfTypes(events, requiredEvents)) {
+      if (event.taskId === persisted.taskId) observedEvents.add(event.event);
     }
-    if (!sameStringSet(state.requiredGates ?? [], persisted.requiredGates)
-      || !sameStringSet(state.satisfiedGates ?? [], persisted.satisfiedGates)) {
-      errors.push(issue("E_PREFLIGHT_GATES_STALE", "The resumable checkpoint gate sets do not match the READY preflight", [stateRel, preflightRel, gatesRel]));
+    for (const requiredEvent of requiredEvents) {
+      if (!observedEvents.has(requiredEvent)) {
+        errors.push(issue("E_PREFLIGHT_EVENT_MISSING", `READY preflight is missing lifecycle event: ${requiredEvent}`, [eventsRel, preflightRel]));
+      }
     }
-  }
-
-  const ledger = await validateEventLedger(target, packageRoot, { taskId });
-  if (!ledger.valid) {
-    errors.push(...ledger.errors.map((error) => issue(error.code ?? "E_EVENT_INVALID", error.message, [eventsRel])));
-  }
-  const events = ledger.events ?? [];
-  for (const requiredEvent of ["CONTRACT_VALIDATED", "ROUTE_VALIDATED"]) {
-    if (!events.some((event) => event.event === requiredEvent && event.taskId === persisted.taskId)) {
-      errors.push(issue("E_PREFLIGHT_EVENT_MISSING", `READY preflight is missing lifecycle event: ${requiredEvent}`, [eventsRel, preflightRel]));
+    for (const gate of persisted.satisfiedGates ?? []) {
+      if (!hasCurrentRevisionGate(events, persisted.taskId, gate)) {
+        errors.push(issue("E_PREFLIGHT_GATE_EVENT_MISSING", `READY preflight is missing lifecycle gate event: ${gate}`, [eventsRel, `${gatesRel}/${gate}.json`]));
+      }
     }
-  }
-  for (const gate of persisted.satisfiedGates ?? []) {
-    if (!hasCurrentRevisionGate(events, persisted.taskId, gate)) {
-      errors.push(issue("E_PREFLIGHT_GATE_EVENT_MISSING", `READY preflight is missing lifecycle gate event: ${gate}`, [eventsRel, `${gatesRel}/${gate}.json`]));
+    let readyCount = 0;
+    let readyMatches = false;
+    for (const event of ledgerEventsOfTypes(events, ["PREFLIGHT_READY"])) {
+      if (event.taskId !== persisted.taskId) continue;
+      readyCount++;
+      if (sameReadyPreflightEvent(event, result)) readyMatches = true;
     }
-  }
-  const readyEvents = events.filter((event) => event.event === "PREFLIGHT_READY" && event.taskId === persisted.taskId);
-  if (readyEvents.length === 0) {
-    errors.push(issue("E_PREFLIGHT_READY_EVENT_MISSING", "Persisted READY preflight is missing the matching PREFLIGHT_READY lifecycle event", [preflightRel, eventsRel]));
-  } else if (!readyEvents.some((event) => sameReadyPreflightEvent(event, result))) {
-    errors.push(issue("E_PREFLIGHT_READY_EVENT_MISMATCH", "PREFLIGHT_READY lifecycle details do not match the persisted READY preflight", [preflightRel, eventsRel]));
-  }
-  return sortIssues(errors);
+    if (readyCount === 0) {
+      errors.push(issue("E_PREFLIGHT_READY_EVENT_MISSING", "Persisted READY preflight is missing the matching PREFLIGHT_READY lifecycle event", [preflightRel, eventsRel]));
+    } else if (!readyMatches) {
+      errors.push(issue("E_PREFLIGHT_READY_EVENT_MISMATCH", "PREFLIGHT_READY lifecycle details do not match the persisted READY preflight", [preflightRel, eventsRel]));
+    }
+    return sortIssues(errors);
+  });
 }
 
 function sameBlockedPreflightEvent(event, result) {

package/src/core/preflight-loaders.js

@@ -41,7 +41,7 @@ export async function optionalConfig(target, packageRoot, errors) {
 
 export async function loadContract(target, packageRoot, errors, options = {}) {
   try {
-    return await readContract(target, packageRoot, options);
+    return await (options.readers?.readContract ?? readContract)(target, packageRoot, options);
   } catch (error) {
     const path = options.contractPath ?? (options.taskId ? taskArtifactPath(options.taskId, "contract") : ARTIFACT_PATHS.contract);
     errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_CONTRACT_MISSING" : "E_CONTRACT_INVALID", error.message, [path]));
@@ -51,7 +51,7 @@ export async function loadContract(target, packageRoot, errors, options = {}) {
 
 export async function loadRoute(target, packageRoot, errors, options = {}) {
   try {
-    return await readPersistedRoute(target, packageRoot, options);
+    return await (options.readers?.readRoute ?? readPersistedRoute)(target, packageRoot, options);
   } catch (error) {
     const path = options.routePath ?? (options.taskId ? taskArtifactPath(options.taskId, "route") : ARTIFACT_PATHS.route);
     const code = error.code === "ARTIFACT_MISSING"
@@ -89,29 +89,36 @@ export async function loadSources(target, contract, packageRoot, errors) {
   return registry;
 }
 
-export async function inspectGates(target, contract, route, packageRoot, errors, config = {}, options = {}) {
-  if (!route) return { required: [], satisfied: [], records: {} };
-  const guideGates = await requiredGatesForGuides(route.value.guides, packageRoot);
-  const required = [...new Set([...guideGates, ...(config.requiredGates ?? [])])].sort();
-  const satisfied = [];
-  const records = {};
-  const taskId = options.taskId ?? null;
+async function readGateEvents(target, packageRoot, taskId, options) {
   let events = [];
   if (taskId) {
     try {
-      events = await readEvents(target, packageRoot, { taskId });
+      events = await (options.readers?.readEvents ?? readEvents)(target, packageRoot, { taskId });
     } catch {
       events = [];
     }
   }
+  return events;
+}
+
+export async function inspectGates(target, contract, route, packageRoot, errors, config = {}, options = {}) {
+  if (!route) return { required: [], satisfied: [], records: {} };
+  const guideGates = await requiredGatesForGuides(route.value.guides, packageRoot);
+  const required = [...new Set([...guideGates, ...(config.requiredGates ?? [])])].sort();
+  const satisfied = [];
+  const records = {};
+  const taskId = options.taskId ?? null;
+  const events = await readGateEvents(target, packageRoot, taskId, options);
   const latestContractRevisionSeq = events.findLast((event) => event.event === "CONTRACT_REVISED")?.seq ?? 0;
   for (const gate of required) {
     let artifact;
     const defaultGateRel = taskId ? taskGatePath(taskId, gate) : `${ARTIFACT_PATHS.gates}/${gate}.json`;
     try {
-      artifact = await readGateIfPresent(target, gate, packageRoot, { ...options, taskId });
+      artifact = await (options.readers?.readGate ?? readGateIfPresent)(target, gate, packageRoot, { ...options, taskId });
     } catch (error) {
-      errors.push(issue(error.code === "ARTIFACT_MISSING" ? "E_GATE_UNVERIFIED" : "E_GATE_INVALID", error.message, [defaultGateRel], { gate }));
+      const code = error.code === "E_STORAGE_PAYLOAD_MISMATCH" && error.taskIdentityMismatch ? "E_GATE_TASK_MISMATCH"
+        : error.code === "ARTIFACT_MISSING" ? "E_GATE_UNVERIFIED" : "E_GATE_INVALID";
+      errors.push(issue(code, error.message, [defaultGateRel], { gate }));
       continue;
     }
     if (!artifact) {

package/src/core/preflight-model.js

@@ -31,7 +31,12 @@ export function sameStringSet(left, right) {
     && [...leftSet].every((value) => rightSet.has(value));
 }
 
-export function validatePersistedPreflight(persisted, current) {
+export function validatePersistedPreflight(persisted, current, readError = null) {
+  if (readError?.taskIdentityMismatch) return [issue("E_PREFLIGHT_TASK_MISMATCH", "Persisted preflight does not belong to the current task", [ARTIFACT_PATHS.preflight, ARTIFACT_PATHS.contract])];
+  return validatePersistedPreflightPayload(persisted, current);
+}
+
+function validatePersistedPreflightPayload(persisted, current) {
   const errors = [];
   if (persisted?.status !== "READY") {
     if (Array.isArray(persisted?.errors) && persisted.errors.length > 0) {