@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/phase.js

@@ -5,6 +5,7 @@ import {
   LIFECYCLE_MILESTONES,
   validateEventLedger,
   validateStateLedgerCoherence,
+  isRevisionEpochPlanRepeat,
 } from "./events.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { assertWorkPhase, isValidTransition } from "./protocol.js";
@@ -13,7 +14,7 @@ import { authorizeCompletionRecoveryOrRebind } from "./completion-recovery-rebin
 import { evaluateCompletion, runComplete as persistCompletion } from "./completion.js";
 import { evaluatePreflight } from "./preflight.js";
 import { requiredEvidenceForTarget } from "./completion-artifacts.js";
-import { assertCompletionRelationships, assertStateIdentity } from "./completion-relationships.js";
+import { assertCompletionRelationships, assertStateIdentity, stateIdentityErrors } from "./completion-relationships.js";
 import { createReceipt, validateReceipt } from "./receipt.js";
 import { assertExecutionPrerequisites, hasExecutionStarted } from "./execution-prerequisites.js";
 import { taskArtifactPath } from "./task-paths.js";
@@ -27,6 +28,13 @@ import {
   evaluateStructuredDiagnosticStall,
 } from "./information-gain-projection.js";
 import { assertStructuralQualityExecutionReady } from "./structural-quality/service.js";
+import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+  ROUTE_CHECKPOINT_BOUND_EVENT,
+  resolveCanonicalPostRepairCheckpointBinding,
+  sameCanonicalGuideList,
+} from "./contract-bootstrap-recovery.js";
 
 function phaseError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -55,44 +63,135 @@ const LATE_PHASES = new Set([
   "COMPLETE",
 ]);
 
-async function assertPersistedStateIdentity(target, state, toPhase, packageRoot, options = {}) {
+/**
+ * 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)
     || ["CONTRACT_READY", "ROUTED", "EXECUTING"].includes(toPhase);
-  const requireRoute = LATE_PHASES.has(state.phase)
+  const requireRoute = state.phase === "ROUTED"
+    || LATE_PHASES.has(state.phase)
     || ["ROUTED", "EXECUTING"].includes(toPhase);
-  const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
-  const routeRel = options.routePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "route") : ARTIFACT_PATHS.route);
-
   let contract = null;
   let route = null;
   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 {
       throw phaseError(
         requireContract ? "E_PHASE_PREREQUISITE_MISSING" : error.code ?? "E_CONTRACT_INVALID",
         `${requireContract ? `Phase ${toPhase} requires current contract` : "Unable to validate current contract"}: ${error.message}`,
-        [contractRel],
+        [paths.contractRel],
       );
     }
   }
   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 {
       throw phaseError(
         requireRoute ? "E_PHASE_PREREQUISITE_MISSING" : error.code ?? "E_ROUTE_INVALID",
         `${requireRoute ? `Phase ${toPhase} requires persisted route` : "Unable to validate persisted route"}: ${error.message}`,
-        [routeRel],
+        [paths.routeRel],
       );
     }
   }
+  return { contract, route };
+}
+
+function assertRepairedCheckpointIdentity({ contract, route, state, events, contractRel, routeRel, stateRel }) {
+  const repairMarker = events.find((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  if (!repairMarker || state.phase === "ROUTED") return false;
+  const checkpoint = resolveCanonicalPostRepairCheckpointBinding(events, repairMarker);
+  if (!checkpoint) {
+    throw phaseError(
+      "E_PHASE_CHRONOLOGY_INVALID",
+      "Repaired late-phase state requires a canonical route checkpoint binding",
+      [contractRel, routeRel],
+    );
+  }
+  const identityErrors = [
+    ...stateIdentityErrors({ contract, state }),
+    ...stateIdentityErrors({ contract, route }),
+  ];
+  if (state.routeFingerprint !== checkpoint.routeFingerprint
+    || !sameCanonicalGuideList(state.selectedGuides, checkpoint.selectedGuides)) {
+    identityErrors.push({
+      code: "E_ROUTE_GUIDE_MISMATCH",
+      message: "Work state does not match the immutable route checkpoint identity",
+      artifacts: [routeRel, stateRel],
+    });
+  }
+  if (identityErrors.length > 0) {
+    const first = identityErrors[0];
+    throw phaseError(first.code, first.message, first.artifacts);
+  }
+  return true;
+}
+
+async function assertPersistedStateIdentity(target, state, toPhase, packageRoot, options = {}) {
+  const scopedTaskId = options.taskId ?? null;
+  const events = options.events ?? [];
+  const contractRel = options.contractPath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "contract") : ARTIFACT_PATHS.contract);
+  const routeRel = options.routePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "route") : ARTIFACT_PATHS.route);
+  const stateRel = options.statePath ?? (scopedTaskId ? taskArtifactPath(scopedTaskId, "state") : ARTIFACT_PATHS.state);
+  const { contract, route } = await readPhaseIdentityArtifacts(
+    target,
+    state,
+    toPhase,
+    packageRoot,
+    options,
+    { contractRel, routeRel },
+  );
   if (!contract && !route) return;
+  if (toPhase !== "ROUTED" && assertRepairedCheckpointIdentity({
+    contract,
+    route,
+    state,
+    events,
+    contractRel,
+    routeRel,
+    stateRel,
+  })) {
+    return;
+  }
   try {
     assertStateIdentity({ contract, route, state });
   } catch (error) {
@@ -116,24 +215,29 @@ function reconcileImplementationStep(state, toPhase) {
   };
 }
 
+function isRevisionPlanRepeat(events, eventType) {
+  return eventType === "PLAN_RECORDED"
+    && 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 {
@@ -146,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);
     }
   }
@@ -160,8 +265,106 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot, aut
   }
 }
 
+async function appendRepairRouteCheckpoint({ target, packageRoot, taskId, state, events, stateRel, eventsRel }) {
+  const repairMarker = events.find((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT);
+  const checkpointAlreadyBound = events.some((event) => event.event === ROUTE_CHECKPOINT_BOUND_EVENT);
+  if (!repairMarker || state.phase !== "ROUTED" || checkpointAlreadyBound) return;
+  if (typeof state.routeFingerprint !== "string") {
+    throw phaseError("E_ROUTE_GUIDE_MISMATCH", "ROUTED state requires a route fingerprint before checkpoint binding", [stateRel, eventsRel]);
+  }
+  await appendProtocolEvent(target, {
+    taskId: state.taskId,
+    event: ROUTE_CHECKPOINT_BOUND_EVENT,
+    details: {
+      routeFingerprint: state.routeFingerprint,
+      contractFingerprint: state.contractFingerprint,
+      selectedGuides: [...state.selectedGuides].sort(),
+    },
+  }, 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);
+  }
+  return withTaskTransaction({
+    target,
+    taskId: normalizedOptions.taskId,
+    operation: "advance",
+    packageRoot: normalizedOptions.packageRoot,
+    recordCommitEvent: true,
+  }, async () => advanceWorkStateInternal(target, toPhase, normalizedOptions));
+}
+
+async function advanceWorkStateInternal(target, toPhase, normalizedOptions) {
   const {
     packageRoot,
     now = new Date().toISOString(),
@@ -174,8 +377,6 @@ export async function advanceWorkState(target, toPhase, options = {}) {
     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]);
@@ -211,7 +412,6 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   }
 
   await assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext, { taskId, statePath, contractPath, routePath, receiptPath, eventsPath });
-  await assertPersistedStateIdentity(target, state, toPhase, packageRoot, { taskId, contractPath, routePath });
 
   if (toPhase === "EXECUTING" && taskId) {
     // Multi-task checkout scope checks
@@ -259,6 +459,12 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   if (coherenceErrors.length > 0) {
     throw phaseError(coherenceErrors[0].code, coherenceErrors[0].message, [stateRel, eventsRel]);
   }
+  await assertPersistedStateIdentity(target, state, toPhase, packageRoot, {
+    taskId,
+    contractPath,
+    routePath,
+    events: ledger.events,
+  });
   const eventType = PHASE_EVENTS[toPhase];
   const reenteringVerification = toPhase === "VERIFYING" && ["CORRECTING", "REVIEWING"].includes(state.phase);
   if (toPhase === "VERIFYING" && state.phase === "REVIEWING") {
@@ -287,35 +493,35 @@ export async function advanceWorkState(target, toPhase, options = {}) {
     }
   }
   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") {
@@ -338,11 +544,15 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   }
   const repeatedReview = state.phase === "VERIFYING" && toPhase === "REVIEWING"
     && ledger.events.some((event) => event.taskId === state.taskId && event.event === "REVIEW_STARTED");
+  const revisionPlanRepeat = isRevisionPlanRepeat(ledger.events, eventType);
   if (eventType && !reenteringVerification && !repeatedReview
+    && !revisionPlanRepeat
     && ledger.events.some((event) => event.taskId === state.taskId && event.event === eventType)) {
     throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `Lifecycle milestone already exists: ${eventType}`, [eventsRel]);
   }
-  const milestoneIndex = reenteringVerification || repeatedReview ? -1 : LIFECYCLE_MILESTONES.indexOf(eventType);
+  const milestoneIndex = reenteringVerification || repeatedReview || revisionPlanRepeat
+    ? -1
+    : LIFECYCLE_MILESTONES.indexOf(eventType);
   if (milestoneIndex >= 0) {
     const lastMilestone = ledger.events.reduce((last, event) => Math.max(last, LIFECYCLE_MILESTONES.indexOf(event.event)), -1);
     if (lastMilestone !== milestoneIndex - 1) {
@@ -361,63 +571,16 @@ export async function advanceWorkState(target, toPhase, options = {}) {
   }
   if (reenteringVerification) delete next.lastCompletionAttempt;
   next.revision = (state.revision ?? 0) + 1;
-  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;
-  }
+  await appendRepairRouteCheckpoint({
+    target,
+    packageRoot,
+    taskId,
+    state,
+    events: ledger.events,
+    stateRel,
+    eventsRel,
+  });
+  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;
 }