@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/commands/task-recover.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { resolveTaskContext } from "../core/task-context.js";
 import { inspectTaskConflictState } from "../core/task-conflict-inspection.js";
 import { appendProtocolEvent } from "../core/events.js";
-import { withTaskTransaction } from "../core/transaction.js";
+import { getTaskTransaction, withTaskTransaction } from "../core/transaction.js";
 import { currentRepositoryFingerprint } from "../core/repository.js";
 import {
   readLockInfo,
@@ -86,6 +86,7 @@ export async function runTaskRecover({
   acknowledgeRecovery = false,
   operatorAuthorized = false,
 } = {}) {
+  const nested = Boolean(await getTaskTransaction(target));
   const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
   const effectiveTaskId = context.taskId;
 
@@ -130,7 +131,7 @@ export async function runTaskRecover({
       const inspection = await inspectTaskConflictState(target, {
         taskId: effectiveTaskId,
         packageRoot,
-        ignoredLockId: transaction.lock.lockId,
+        ignoredLockId: transaction.lock?.lockId ?? null,
       });
       assertRecoveryAllowed(effectiveTaskId, inspection);
       if (inspection.evidence.workStateRevision !== inspectionBeforeLock.evidence.workStateRevision
@@ -194,6 +195,13 @@ export async function runTaskRecover({
         message: `Task ${effectiveTaskId} recovered by caller acknowledgement; write claims released without completion claim`,
       };
     });
+  }).catch(async error => {
+    if (error.code === "E_STATE_REVISION_CONFLICT" && !nested) {
+      // The failed transaction has rolled back. Report a competing validated
+      // recovery through the existing domain error; never replay claim release.
+      await assertConsistentRecoverableOwnership(target, effectiveTaskId, packageRoot);
+    }
+    throw error;
   });
 }
 

package/src/commands/task-repair-contract-bootstrap.js

@@ -0,0 +1,263 @@
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { readContract } from "../core/contract.js";
+import { appendProtocolEvent, validateEventLedger } from "../core/events.js";
+import { readPersistedRoute } from "../core/route-artifact.js";
+import { currentRepositoryFingerprint } from "../core/repository.js";
+import { resolveTaskContext } from "../core/task-context.js";
+import { taskArtifactPath } from "../core/task-paths.js";
+import { withProjectClaimsLock, readLockInfo, classifyLockStaleness, releaseStaleTaskLockIfUnchanged } from "../core/task-lock.js";
+import { withTaskTransaction } from "../core/transaction.js";
+import { createWorkState, mutateWorkState, readWorkState } from "../core/work-state.js";
+import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import {
+  CONTRACT_BOOTSTRAP_REPAIR_AUTHORITY,
+  CONTRACT_BOOTSTRAP_REPAIR_DEFECT,
+  CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+  CONTRACT_BOOTSTRAP_REPAIR_VERSION,
+  assertContractBootstrapRepairDetails,
+  contractBootstrapRepairId,
+  isContractBootstrapRepairCandidate,
+  resolveEffectiveContractBootstrapRepairAnchor,
+} from "../core/contract-bootstrap-recovery.js";
+import {
+  E_CONTRACT_BOOTSTRAP_REPAIR_AUTHORIZATION_REQUIRED,
+  E_CONTRACT_BOOTSTRAP_REPAIR_INVALID,
+  E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE,
+  E_TASK_LOCKED,
+} from "../core/error-codes.js";
+
+function repairError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+async function readRouteIfProven(target, packageRoot, taskId, events, contractFingerprint) {
+  const routePath = taskArtifactPath(taskId, "route");
+  const hasRouteValidated = events.some((event) => event.event === "ROUTE_VALIDATED");
+  if (!hasRouteValidated) return null;
+  try {
+    const route = await readPersistedRoute(target, packageRoot, { taskId });
+    if (route.value.contractFingerprint !== contractFingerprint) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Persisted route does not bind to the canonical contract fingerprint");
+    }
+    return route;
+  } catch (error) {
+    if (error.code === "ARTIFACT_MISSING") {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "ROUTE_VALIDATED history requires a persisted route artifact", { artifacts: [routePath] });
+    }
+    if (error.code === E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE) throw error;
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, `Persisted route cannot be proven safe: ${error.message}`, { artifacts: [routePath] });
+  }
+}
+
+function stateForRepair(state, { taskId, contractFingerprint, route, repository }) {
+  const routed = Boolean(route);
+  const phase = routed ? "ROUTED" : "CONTRACT_READY";
+  const steps = routed
+    ? { completedSteps: ["contract", "route"], pendingSteps: ["planning", "implementation", "verification"] }
+    : { completedSteps: ["contract"], pendingSteps: ["route", "planning", "implementation", "verification"] };
+  const base = state ? {
+    ...state,
+    taskId,
+    contractFingerprint,
+    ...(routed ? { routeFingerprint: route.fingerprint } : { routeFingerprint: undefined }),
+    repositoryFingerprint: repository,
+    phase,
+    selectedGuides: routed ? [...route.value.guides] : [],
+    completedSteps: steps.completedSteps,
+    pendingSteps: steps.pendingSteps,
+    revision: (state.revision ?? 0) + 1,
+    lastUpdated: new Date().toISOString(),
+    ...(state.phase !== phase ? { previousPhase: state.phase } : {}),
+  } : createWorkState({
+    taskId,
+    contractFingerprint,
+    ...(routed ? { routeFingerprint: route.fingerprint } : {}),
+    repositoryFingerprint: repository,
+    phase,
+    selectedGuides: routed ? [...route.value.guides] : [],
+    requiredGates: [],
+    satisfiedGates: [],
+    completedSteps: steps.completedSteps,
+    pendingSteps: steps.pendingSteps,
+    requiredArtifacts: [],
+    checks: [],
+    failures: [],
+    blockers: [],
+    verificationEvidence: [],
+    revision: 0,
+  });
+  if (base.routeFingerprint === undefined) delete base.routeFingerprint;
+  return createWorkState(base);
+}
+
+function assertStateCompatible(state, taskId, contractFingerprint, route) {
+  if (!state) return;
+  if (state.taskId !== taskId || state.contractFingerprint !== contractFingerprint) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Existing work-state is bound to a different task or contract");
+  }
+  if (!["CONTRACT_READY", "ROUTED"].includes(state.phase)) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, `Existing work-state phase ${state.phase} is beyond the repair boundary`);
+  }
+  if (route && state.routeFingerprint !== undefined && state.routeFingerprint !== route.fingerprint) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Existing work-state route fingerprint conflicts with the proven route");
+  }
+  if (!route && state.routeFingerprint !== undefined) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Existing work-state claims a route that cannot be proven from the artifacts");
+  }
+  if (state.phase === "CONTRACT_READY") {
+    if (state.routeFingerprint !== undefined) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "CONTRACT_READY work-state must not claim a route");
+    }
+    if (Array.isArray(state.selectedGuides) && state.selectedGuides.length > 0) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "CONTRACT_READY work-state must not have selected guides");
+    }
+    if (Array.isArray(state.requiredGates) && state.requiredGates.length > 0) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "CONTRACT_READY work-state must not have required gates");
+    }
+    if (Array.isArray(state.satisfiedGates) && state.satisfiedGates.length > 0) {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "CONTRACT_READY work-state must not have satisfied gates");
+    }
+  }
+}
+
+function markerResult(taskId, marker, state, alreadyRepaired) {
+  return {
+    taskId,
+    repaired: alreadyRepaired ? false : true,
+    alreadyRepaired,
+    repairId: marker.details.repairId,
+    phase: state.phase,
+    reconstructedPhase: marker.details.reconstructedPhase,
+    markerEventSeq: marker.seq,
+  };
+}
+
+async function verifyExistingRepair(target, packageRoot, taskId, ledger) {
+  const anchor = resolveEffectiveContractBootstrapRepairAnchor(ledger.events);
+  if (!anchor || !ledger.valid) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_INVALID, "Existing contract bootstrap repair marker is invalid or the repaired ledger is no longer strict");
+  }
+  const contract = await readContract(target, packageRoot, { taskId });
+  if (contract.fingerprint !== anchor.details.contractFingerprint) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_INVALID, "Contract fingerprint no longer matches the repair marker");
+  }
+  const state = await readWorkState(target, { packageRoot, taskId });
+  const ownership = await resolveTaskClaimState(target, { taskId, packageRoot });
+  if (!ownership.ownershipValid) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_INVALID, "Current task state no longer satisfies the repaired-task invariants", {
+      errors: ownership.errors,
+    });
+  }
+  return markerResult(taskId, { ...anchor.sourceMarker, details: anchor.details }, state, true);
+}
+
+export async function runTaskRepairContractBootstrap({ target, packageRoot, taskId, acknowledgeRepair } = {}) {
+  if (!acknowledgeRepair) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_AUTHORIZATION_REQUIRED, "task-repair-contract-bootstrap requires fresh explicit --acknowledge-repair");
+  }
+  const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  const effectiveTaskId = context.taskId;
+  const initial = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+  if (initial.events.some((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT)) {
+    return verifyExistingRepair(target, packageRoot, effectiveTaskId, initial);
+  }
+  const candidate = isContractBootstrapRepairCandidate(initial.events, initial.errors, effectiveTaskId);
+  if (!candidate) {
+    throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Ledger does not match the exact contract bootstrap repair signature", { errors: initial.errors });
+  }
+
+  return withProjectClaimsLock(target, "task-repair-contract-bootstrap", async () => {
+    const lock = await readLockInfo(target, effectiveTaskId);
+    const status = classifyLockStaleness(lock);
+    if (status.status === "LIVE") throw repairError(E_TASK_LOCKED, `Task ${effectiveTaskId} has a live mutation lock`);
+    if (status.status === "UNKNOWN" || status.status === "CORRUPT") {
+      throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, `Task ${effectiveTaskId} lock state is ${status.status}`);
+    }
+    if (status.status === "STALE") {
+      const released = await releaseStaleTaskLockIfUnchanged(target, effectiveTaskId, lock);
+      if (!released.released && released.reason !== "LOCK_MISSING") {
+        throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE,
+          `Task ${effectiveTaskId} stale lock could not be safely released: ${released.reason}`);
+      }
+    }
+    return withTaskTransaction({
+      target,
+      taskId: effectiveTaskId,
+      operation: "task-repair-contract-bootstrap",
+      packageRoot,
+      recordCommitEvent: true,
+    }, async () => {
+      const locked = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId });
+      if (locked.events.some((event) => event.event === CONTRACT_BOOTSTRAP_REPAIR_EVENT)) {
+        return verifyExistingRepair(target, packageRoot, effectiveTaskId, locked);
+      }
+      const lockedCandidate = isContractBootstrapRepairCandidate(locked.events, locked.errors, effectiveTaskId);
+      if (!lockedCandidate
+        || lockedCandidate.duplicateContractEvent.hash !== candidate.duplicateContractEvent.hash
+        || lockedCandidate.duplicateContractCommit.hash !== candidate.duplicateContractCommit.hash) {
+        throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_INVALID, "Ledger changed between inspection and repair lock");
+      }
+      const contract = await readContract(target, packageRoot, { taskId: effectiveTaskId });
+      if (contract.fingerprint !== lockedCandidate.contractFingerprint) {
+        throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Current contract does not match the canonical historical contract fingerprint");
+      }
+      const route = await readRouteIfProven(target, packageRoot, effectiveTaskId, locked.events, contract.fingerprint);
+      const state = await readWorkState(target, { packageRoot, taskId: effectiveTaskId });
+      assertStateCompatible(state, effectiveTaskId, contract.fingerprint, route);
+      if (!state) {
+        throw repairError(E_CONTRACT_BOOTSTRAP_REPAIR_UNSAFE, "Existing work-state is required to repair the contract bootstrap defect");
+      }
+      const repository = await currentRepositoryFingerprint(target);
+      const reconstructed = await mutateWorkState(target, {
+        expectedRevision: state.revision ?? 0,
+        packageRoot,
+        taskId: effectiveTaskId,
+      }, (current) => {
+        assertStateCompatible(current, effectiveTaskId, contract.fingerprint, route);
+        return stateForRepair(current, {
+          taskId: effectiveTaskId,
+          contractFingerprint: contract.fingerprint,
+          route,
+          repository,
+        });
+      });
+      const repairedAt = new Date().toISOString();
+      const details = {
+        repairVersion: CONTRACT_BOOTSTRAP_REPAIR_VERSION,
+        taskId: effectiveTaskId,
+        defect: CONTRACT_BOOTSTRAP_REPAIR_DEFECT,
+        canonicalContractEventSeq: lockedCandidate.canonicalContractEvent.seq,
+        canonicalContractEventHash: lockedCandidate.canonicalContractEvent.hash,
+        duplicateContractEventSeq: lockedCandidate.duplicateContractEvent.seq,
+        duplicateContractEventHash: lockedCandidate.duplicateContractEvent.hash,
+        contractCreateCommitSeq: lockedCandidate.duplicateContractCommit.seq,
+        contractCreateCommitHash: lockedCandidate.duplicateContractCommit.hash,
+        contractCreateTransactionId: lockedCandidate.duplicateContractCommit.details.transactionId,
+        contractFingerprint: contract.fingerprint,
+        reconstructedPhase: reconstructed.phase,
+        routeFingerprint: route?.fingerprint ?? null,
+        previousStateFingerprint: canonicalFingerprint(state),
+        reconstructedStateFingerprint: canonicalFingerprint(reconstructed),
+        reconstructedStateRevision: reconstructed.revision,
+        repairedAt,
+        authorityKind: CONTRACT_BOOTSTRAP_REPAIR_AUTHORITY,
+      };
+      details.repairId = contractBootstrapRepairId(details);
+      assertContractBootstrapRepairDetails(details);
+      const marker = await appendProtocolEvent(target, {
+        taskId: effectiveTaskId,
+        event: CONTRACT_BOOTSTRAP_REPAIR_EVENT,
+        at: repairedAt,
+        details,
+      }, packageRoot, { taskId: effectiveTaskId });
+      return markerResult(effectiveTaskId, marker, reconstructed, false);
+    });
+  });
+}
+
+export function formatTaskRepairContractBootstrapResult(result) {
+  return `taskId: ${result.taskId}\nphase: ${result.phase}\nrepairId: ${result.repairId}\n${result.alreadyRepaired ? "alreadyRepaired: true" : "repaired: true"}\n`;
+}

package/src/commands/task-scope.js

@@ -1,3 +1,6 @@
+import { withEventLedgerAudit } from "../core/events.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+import { needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
 import { resolveTaskContext } from "../core/task-context.js";
 import { readTaskDescriptor, writeTaskDescriptor } from "../core/task-descriptor.js";
 import { normalizeWriteClaims, assertScopeClean, assertScopeNotFrozen } from "../core/task-scope.js";
@@ -18,8 +21,20 @@ function taskError(code, message, artifacts = []) {
   return error;
 }
 
-export async function runTaskScope({ target, packageRoot, taskId, claims } = {}) {
+export async function runTaskScope(options = {}) {
+  const { target, packageRoot, taskId, claims } = options;
+  const readOnly = claims === undefined || claims === null;
+  if (readOnly && await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => runTaskScope(options), { readOnly: true });
+  }
   const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true });
+  if (readOnly && getOperationalStore(target)) {
+    return withEventLedgerAudit(target, packageRoot, { taskId: context.taskId }, () => runResolvedTaskScope(options, context));
+  }
+  return runResolvedTaskScope(options, context);
+}
+
+async function runResolvedTaskScope({ target, packageRoot, claims }, context) {
   const effectiveTaskId = context.taskId;
 
   let descriptorArtifact;
@@ -38,6 +53,7 @@ export async function runTaskScope({ target, packageRoot, taskId, claims } = {})
     return withProjectClaimsLock(target, async () => {
       return withTaskLock(target, effectiveTaskId, "task-scope", async () => {
         await assertTaskNotRecovered(target, { taskId: effectiveTaskId, packageRoot });
+        const lockedDescriptor = (await readTaskDescriptor(target, effectiveTaskId, packageRoot)).value;
         const state = await readWorkState(target, { packageRoot, taskId: effectiveTaskId });
         if (state?.phase) {
           assertScopeNotFrozen(state.phase);
@@ -51,7 +67,7 @@ export async function runTaskScope({ target, packageRoot, taskId, claims } = {})
         }
 
         const updatedDescriptor = {
-          ...descriptor,
+          ...lockedDescriptor,
           writeClaims: normalizedClaims,
           updatedAt: new Date().toISOString(),
         };

package/src/commands/task-show.js

@@ -9,6 +9,9 @@ import { E_TASK_NOT_FOUND } from "../core/error-codes.js";
 import { resolveTaskClaimState } from "../core/task-claim-state.js";
 import { readPersistedRoute } from "../core/route-artifact.js";
 import { projectExecutionProfile } from "../core/execution-profile.js";
+import { withEventLedgerAudit } from "../core/events.js";
+import { needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
+import { getOperationalStore, operationalArtifactExists } from "../storage/operational-context.js";
 
 function taskError(code, message, artifacts = []) {
   const error = new Error(message);
@@ -17,8 +20,19 @@ function taskError(code, message, artifacts = []) {
   return error;
 }
 
-export async function runTaskShow({ target, packageRoot, taskId, compact = false } = {}) {
+export async function runTaskShow(options = {}) {
+  const { target, packageRoot, taskId } = options;
+  if (await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => runTaskShow(options), { readOnly: true });
+  }
   const context = await resolveTaskContext(target, { taskId, packageRoot, explicitRequired: true, selectionMode: TASK_SELECTION_MODES.READ });
+  if (getOperationalStore(target)) {
+    return withEventLedgerAudit(target, packageRoot, { taskId: context.taskId }, () => projectTaskShow(options, context));
+  }
+  return projectTaskShow(options, context);
+}
+
+async function projectTaskShow({ target, packageRoot, compact = false }, context) {
   const effectiveTaskId = context.taskId;
 
   let descriptor = null;
@@ -54,7 +68,7 @@ export async function runTaskShow({ target, packageRoot, taskId, compact = false
     const rel = taskArtifactPath(effectiveTaskId, name);
     artifacts[name] = {
       path: rel,
-      exists: await fileExists(ensureWithin(target, rel)),
+      exists: operationalArtifactExists(target, rel) ?? await fileExists(ensureWithin(target, rel)),
     };
   }
 

package/src/commands/test-inventory.js

@@ -0,0 +1,5 @@
+import { runTestInventory as inventory } from "../core/test-intelligence/service.js";
+
+export async function runTestInventory({ target = process.cwd() } = {}) { return inventory({ projectRoot: target }); }
+export function formatTestInventoryResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }
+

package/src/commands/test-prune-plan.js

@@ -0,0 +1,5 @@
+import { buildPrunePlan } from "../core/test-intelligence/prune.js";
+
+export async function runTestPrunePlan({ target, packageRoot, taskId } = {}) { return buildPrunePlan({ target, packageRoot, taskId }); }
+export function formatTestPrunePlanResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }
+

package/src/commands/test-prune-probe.js

@@ -0,0 +1,5 @@
+import { runPruneProbe as probe } from "../core/test-intelligence/prune.js";
+
+export async function runTestPruneProbe({ target, packageRoot, taskId, testId } = {}) { return probe({ target, packageRoot, taskId, testId }); }
+export function formatTestPruneProbeResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }
+

package/src/commands/test-utility.js

@@ -0,0 +1,5 @@
+import { runTestUtility as analyze } from "../core/test-intelligence/service.js";
+
+export async function runTestUtility({ target, packageRoot, taskId, semanticStatus } = {}) { return analyze({ target, packageRoot, taskId, semanticStatus }); }
+export function formatTestUtilityResult(result) { return `${JSON.stringify(result, null, 2)}\n`; }
+

package/src/commands/validate-protocol.js

@@ -8,17 +8,20 @@ import { validateReceipt } from "../core/receipt.js";
 import { validateTaskBrief, validateDelegatedResult } from "../core/delegation.js";
 import { ARTIFACT_PATHS, readJsonArtifact } from "../core/artifacts.js";
 import { evaluatePreflight, validateReadyProtocolConsistency } from "../core/preflight.js";
-import { validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
+import { withEventLedgerAudit, validateStateLedgerCoherence } from "../core/events.js";
 import { validateChecksExecutionProvenance } from "../core/completion-artifacts.js";
 import { assertContinuitySemantics } from "../core/continuity.js";
 import { currentChangedPaths, currentRepositoryFingerprint } from "../core/repository.js";
 import { resolveTaskClaimState } from "../core/task-claim-state.js";
+import { getOperationalStore, readOperationalText } from "../storage/operational-context.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
 async function readArtifact(target, relativePath, label) {
   if (!relativePath) return null;
   await assertSafePath(target, relativePath);
   const artifactPath = ensureWithin(target, relativePath);
-  if (!(await fileExists(artifactPath))) {
+  const operational = readOperationalText(target, relativePath);
+  if (operational.selected ? operational.text === null : !(await fileExists(artifactPath))) {
     return {
       error: {
         code: "ARTIFACT_MISSING",
@@ -27,7 +30,7 @@ async function readArtifact(target, relativePath, label) {
       },
     };
   }
-  const bytes = await readBytes(artifactPath);
+  const bytes = operational.selected ? Buffer.from(operational.text, "utf8") : await readBytes(artifactPath);
   try {
     assertJsonBytes(bytes, label);
     const value = JSON.parse(bytes.toString("utf8"));
@@ -44,10 +47,18 @@ async function readArtifact(target, relativePath, label) {
   }
 }
 
+function isOptionalContinuityAbsence(item) {
+  return item.label === "continuity" && item.error?.code === "ARTIFACT_MISSING";
+}
+
 import { taskArtifactPath } from "../core/task-paths.js";
 import { withResolvedTask } from "../core/task-command.js";
 
-export async function runValidateProtocol({
+export async function runValidateProtocol(options) {
+  return withProjectReadSnapshot(options.target, () => validateSelectedProtocol(options));
+}
+
+async function validateSelectedProtocol({
   target,
   packageRoot,
   routeFile = null,
@@ -59,9 +70,17 @@ export async function runValidateProtocol({
   delegatedResultFiles = [],
   taskId = null,
   task = null,
-}) {
+}, ownedLedger = null) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
     const effectiveTaskId = ctx?.taskId ?? null;
+    if (effectiveTaskId && getOperationalStore(target) && !ownedLedger) {
+      // Keep the complete final proof local to this immutable projection.
+      // Nested preflight audits retain their own rules and share its source.
+      return withEventLedgerAudit(target, packageRoot, { taskId: effectiveTaskId }, ledger => validateSelectedProtocol({
+        target, packageRoot, routeFile, stateFile, receiptFile, contractFile, continuityFile,
+        taskBriefFiles, delegatedResultFiles, taskId: effectiveTaskId,
+      }, ledger));
+    }
     const effectiveRouteFile = routeFile ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "route") : ARTIFACT_PATHS.route);
     const effectiveStateFile = stateFile ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "state") : ARTIFACT_PATHS.state);
     const effectiveReceiptFile = receiptFile ?? (effectiveTaskId ? taskArtifactPath(effectiveTaskId, "receipt") : ARTIFACT_PATHS.receipt);
@@ -84,7 +103,12 @@ export async function runValidateProtocol({
     loaded.push({ label, relativePath, ...artifact });
   }
 
-  const readErrors = loaded.filter((item) => item.error).map((item) => item.error);
+  // Continuity is an optional operational-context artifact. Its absence is
+  // represented by evaluateContinuityConformance as NOT_APPLICABLE; only a
+  // present but malformed continuity artifact is a validation failure.
+  const readErrors = loaded
+    .filter((item) => item.error && !isOptionalContinuityAbsence(item))
+    .map((item) => item.error);
   const route = loaded.find((item) => item.label === "route")?.value ?? null;
   const state = loaded.find((item) => item.label === "state")?.value ?? null;
   const receipt = loaded.find((item) => item.label === "receipt")?.value ?? null;
@@ -160,19 +184,15 @@ export async function runValidateProtocol({
   } catch {
     // A missing or invalid preflight is already outside the optional protocol set.
   }
-  let ledgerEvents = [];
-  let ledgerErrors = [];
-  if (state && !stateValidationError) {
-    const ledger = await validateEventLedger(target, packageRoot, { taskId: effectiveTaskId, eventsPath: effectiveEventsFile });
-    ledgerEvents = ledger.events ?? [];
-    ledgerErrors = [
+  const finish = async (ledger) => {
+    const ledgerEvents = ledger.events ?? [];
+    const ledgerErrors = state && !stateValidationError ? [
       ...ledger.errors.map((error) => ({ ...error, artifacts: [effectiveEventsFile] })),
-      ...validateStateLedgerCoherence(state, ledger.events).map((error) => ({
+      ...validateStateLedgerCoherence(state, ledgerEvents).map((error) => ({
         ...error,
         artifacts: [effectiveStateFile, effectiveEventsFile],
       })),
-    ];
-  }
+    ] : [];
   const recoveryErrors = [];
   if (effectiveTaskId) {
     try {
@@ -216,6 +236,10 @@ export async function runValidateProtocol({
       };
     }
     return result;
+  };
+  return state && !stateValidationError
+    ? ownedLedger ? finish(ownedLedger) : withEventLedgerAudit(target, packageRoot, { taskId: effectiveTaskId, eventsPath: effectiveEventsFile }, finish)
+    : finish({ events: [], errors: [] });
   });
 }
 

package/src/commands/validate-receipt.js

@@ -4,13 +4,17 @@ import { assertJsonBytes, assertJsonLimits } from "../core/json-safety.js";
 import { ARTIFACT_PATHS } from "../core/artifacts.js";
 import { taskArtifactPath } from "../core/task-paths.js";
 import { withResolvedTask } from "../core/task-command.js";
+import { readOperationalText } from "../storage/operational-context.js";
+import { isOperationalArtifactPath, needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
 
 async function validateReceiptFile(target, packageRoot, relativeFile) {
   await assertSafePath(target, relativeFile);
   const receiptPath = ensureWithin(target, relativeFile);
   let receipt;
   try {
-    const bytes = await readBytes(receiptPath);
+    const operational = readOperationalText(target, relativeFile);
+    if (operational.selected && operational.text === null) throw new Error("Receipt is missing from canonical storage");
+    const bytes = operational.selected ? Buffer.from(operational.text, "utf8") : await readBytes(receiptPath);
     assertJsonBytes(bytes, relativeFile);
     receipt = JSON.parse(bytes.toString("utf8"));
     assertJsonLimits(receipt, relativeFile);
@@ -43,6 +47,9 @@ export async function runValidateReceipt({
   file = null,
   taskId = null,
 } = {}) {
+  if ((!file || isOperationalArtifactPath(file)) && await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => runValidateReceipt({ target, packageRoot, file, taskId }), { readOnly: true });
+  }
   if (file) {
     return validateReceiptFile(target, packageRoot, file);
   }

package/src/config/guides.json

@@ -86,5 +86,9 @@
   "swift": {
     "path": "ENG/swift-development-eng.md",
     "install": true
+  },
+  "python": {
+    "path": "ENG/python-development-eng.md",
+    "install": true
   }
 }

package/src/core/action-ledger-projection.js

@@ -1,4 +1,4 @@
-import { readEvents } from "./events.js";
+import { iterateEvents } from "./events.js";
 import { assertActionTransition, assertActionAuthorizationDetails } from "./action-model.js";
 import { E_ACTION_EVIDENCE_INVALID } from "./error-codes.js";
 
@@ -27,6 +27,14 @@ function hasCanonicalVerificationEvidence(details) {
   );
 }
 
+async function readActionChronology(target, packageRoot, taskId, actionId) {
+  const chronology = [];
+  for await (const event of iterateEvents(target, packageRoot, { taskId })) {
+    if (event.details?.actionId === actionId) chronology.push(event);
+  }
+  return chronology;
+}
+
 function issue(code, message) {
   return { code, message };
 }
@@ -49,8 +57,7 @@ export async function projectActionLedger({
   actionId,
   artifact = null,
 }) {
-  const events = await readEvents(target, packageRoot, { taskId });
-  const chronology = events.filter((event) => event.details?.actionId === actionId);
+  const chronology = await readActionChronology(target, packageRoot, taskId, actionId);
   const errors = [];
 
   const proposed = chronology.find((event) => event.event === "ACTION_PROPOSED");