@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/src/commands/action-show.js

@@ -1,9 +1,12 @@
 import { readAction } from "../core/actions.js";
 import { resolveTaskContext } from "../core/task-context.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
 export async function runActionShow({ target, packageRoot, taskId, actionId }) {
-  const ctx = await resolveTaskContext(target, { packageRoot, taskId });
-  return readAction(target, { packageRoot, taskId: ctx.taskId, actionId });
+  return withProjectReadSnapshot(target, async () => {
+    const ctx = await resolveTaskContext(target, { packageRoot, taskId });
+    return readAction(target, { packageRoot, taskId: ctx.taskId, actionId });
+  });
 }
 export function formatActionShowResult(result) {
   return `FORGELOOP ACTION\naction: ${result.actionId}\nstate: ${result.state}\ncapability: ${result.capability}\n`;

package/src/commands/advance.js

@@ -1,10 +1,14 @@
+import { assertCanonicalPersistence } from "../storage/operational-context.js";
 import { advanceWorkState } from "../core/phase.js";
 import { withTaskMutation } from "../core/task-command.js";
 
 export { advanceWorkState };
 
-export async function runAdvance({ target, packageRoot, to, taskId, task, authorityContext, runtimeContext }) {
+export async function runAdvance({ target, packageRoot, to, taskId, task, authorityContext, runtimeContext, persistence = null }) {
   if (!to) throw new Error("--to is required for advance");
+
+  assertCanonicalPersistence(persistence);
+
   return withTaskMutation(target, { taskId: taskId ?? task, packageRoot }, "advance", async (ctx) => {
     return advanceWorkState(target, to, {
       packageRoot,

package/src/commands/baseline.js

@@ -1,3 +1,4 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import {
   computePersistedPolicyLockData,
   evaluateTargetPolicy,
@@ -18,6 +19,17 @@ function baselineError(code, message) {
   return err;
 }
 
+async function hasActivePolicySnapshot(target, packageRoot) {
+  return withProjectReadSnapshot(target, async () => {
+    const tasks = await discoverTasks(target, packageRoot);
+    for (const task of tasks) {
+      if (task.healthy && task.phase && task.phase !== "COMPLETE" && task.phase !== "BLOCKED"
+        && await readTaskPolicySnapshot(target, task.taskId, packageRoot)) return true;
+    }
+    return false;
+  });
+}
+
 export async function runBaseline({
   target = process.cwd(),
   packageRoot,
@@ -28,17 +40,7 @@ export async function runBaseline({
   const policyEval = await evaluateTargetPolicy({ target, packageRoot });
   let baseline = await readBaseline(target, packageRoot);
 
-  const tasks = await discoverTasks(target, packageRoot);
-  let hasActivePolicyTask = false;
-  for (const t of tasks) {
-    if (t.healthy && t.phase && t.phase !== "COMPLETE" && t.phase !== "BLOCKED") {
-      const snap = await readTaskPolicySnapshot(target, t.taskId, packageRoot);
-      if (snap) {
-        hasActivePolicyTask = true;
-        break;
-      }
-    }
-  }
+  const hasActivePolicyTask = await hasActivePolicySnapshot(target, packageRoot);
 
   if (record) {
     if (hasActivePolicyTask && !policyResetAuthorized) {

package/src/commands/checkpoint-revalidate.js

@@ -1,3 +1,4 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import { canonicalFingerprint } from "../core/artifacts.js";
 import { readContract } from "../core/contract.js";
 import {
@@ -10,7 +11,7 @@ import { currentRepositoryFingerprint } from "../core/repository.js";
 import { resolveTaskContext } from "../core/task-context.js";
 import { taskArtifactPath } from "../core/task-paths.js";
 import { assertTaskMutationAllowed } from "../core/task-claim-state.js";
-import { withTaskTransaction } from "../core/transaction.js";
+import { getTaskTransaction, withTaskTransaction } from "../core/transaction.js";
 import {
   CHECKPOINT_REVALIDATED_EVENT,
   assertCheckpointRevalidatedDetails,
@@ -47,6 +48,10 @@ function assertRouteIdentity(state, contract, route) {
 }
 
 async function inspectEligibility(target, packageRoot, taskId) {
+  return withProjectReadSnapshot(target, () => inspectSelectedEligibility(target, packageRoot, taskId));
+}
+
+async function inspectSelectedEligibility(target, packageRoot, taskId) {
   const state = await readWorkState(target, { packageRoot, taskId });
   if (!state) throw revalidationError("A persisted work-state checkpoint is required");
   if (state.phase !== "ROUTED") throw revalidationError(`Checkpoint revalidation supports phase ROUTED, found ${state.phase}`);
@@ -162,13 +167,24 @@ export async function runCheckpointRevalidate({ target, packageRoot, taskId } =
   const effectiveTaskId = context.taskId;
   const initial = await inspectEligibility(target, packageRoot, effectiveTaskId);
   if (initial.alreadyFresh) return resultFor(effectiveTaskId, initial.state, initial.repository, null, null, true);
-  return withTaskTransaction({
-    target,
-    taskId: effectiveTaskId,
-    operation: "checkpoint-revalidate",
-    packageRoot,
-    recordCommitEvent: false,
-  }, async (transaction) => revalidateLocked(target, packageRoot, effectiveTaskId, transaction));
+  const nested = Boolean(await getTaskTransaction(target));
+  try {
+    return await withTaskTransaction({
+      target,
+      taskId: effectiveTaskId,
+      operation: "checkpoint-revalidate",
+      packageRoot,
+      recordCommitEvent: false,
+    }, async (transaction) => revalidateLocked(target, packageRoot, effectiveTaskId, transaction));
+  } catch (error) {
+    if (nested || error?.code !== "E_STATE_REVISION_CONFLICT") throw error;
+    // A competing writer may have completed this exact revalidation. Recheck
+    // all eligibility and history after our preparation rolled back; never
+    // replay mutation or convert an unrelated conflict into success.
+    const current = await inspectEligibility(target, packageRoot, effectiveTaskId);
+    if (!current.alreadyFresh) throw error;
+    return resultFor(effectiveTaskId, current.state, current.repository, null, null, true);
+  }
 }
 
 export function formatCheckpointRevalidateResult(result) {

package/src/commands/complete.js

@@ -1,13 +1,29 @@
 import { runComplete as evaluateAndComplete } from "../core/completion.js";
 import { withTaskMutation } from "../core/task-command.js";
+import { isRecoverableCompletionEvidenceCode } from "../core/completion-recovery.js";
 
 export async function runComplete(options = {}) {
   const target = options.target;
   const packageRoot = options.packageRoot;
   const taskId = options.taskId ?? options.task ?? null;
-  return withTaskMutation(target, { taskId, packageRoot }, "complete", async (ctx) => {
-    return evaluateAndComplete({ ...options, taskId: ctx?.taskId ?? null });
-  });
+  const rejected = new Error("Completion validation rejected");
+  let rejectedResult;
+  try {
+    return await withTaskMutation(target, { taskId, packageRoot }, "complete", async (ctx) => {
+      const result = await evaluateAndComplete({ ...options, taskId: ctx?.taskId ?? null });
+      const recordsEvidenceRecovery = options.persist !== false && result.errors.length > 0
+        && result.errors.every(error => isRecoverableCompletionEvidenceCode(error.code));
+      if (result.status === "REJECTED" && !recordsEvidenceRecovery) {
+        rejectedResult = result;
+        throw rejected;
+      }
+      return result;
+    });
+  } catch (error) {
+    // Return the domain rejection only after its transaction has rolled back.
+    if (error === rejected) return rejectedResult;
+    throw error;
+  }
 }
 
 export function formatCompleteResult(result) {

package/src/commands/contract-create.js

@@ -15,6 +15,7 @@ import {
 } from "../core/resumability.js";
 import { taskArtifactPath } from "../core/task-paths.js";
 import { ensureSemanticDecision } from "../core/decision/service.js";
+import { operationalArtifactExists } from "../storage/operational-context.js";
 
 function bootstrapInconsistent(message, candidate = false) {
   const error = new Error(message);
@@ -176,7 +177,8 @@ export async function runContractCreate({ target, packageRoot, taskId, task, con
     // fingerprint to prove idempotent equivalence; it never redefines the
     // canonical historical contract.
     const existingContractPath = taskArtifactPath(ctx.taskId, "contract");
-    if (await fileExists(ensureWithin(target, existingContractPath)).catch(() => false)) {
+    if (operationalArtifactExists(target, existingContractPath)
+      ?? await fileExists(ensureWithin(target, existingContractPath)).catch(() => false)) {
       const existingContract = await readContract(target, packageRoot, { taskId: ctx.taskId });
       const existingLedger = await validateEventLedger(target, packageRoot, { taskId: ctx.taskId });
       const validatedContractEvents = existingLedger.events.filter(

package/src/commands/doctor.js

@@ -4,13 +4,14 @@ import { readTemplateEntries } from "../core/templates.js";
 import { createEvidence } from "../core/evidence.js";
 import { LAYOUT_VERSION } from "../core/target-layout.js";
 import { inspectNativeAdapter, validateNativeAdapterTargets } from "../core/native-adapters.js";
-import { findIncompleteTransactions, recoverIncompleteTransactions } from "../core/transaction.js";
+import { findIncompleteTransactions } from "../core/transaction.js";
 import { isRepositoryCandidate } from "../repository-index/lifecycle.js";
 import { getRepositoryIndexStatus, sanitizeRepositoryIndexStatus } from "../repository-index/status.js";
 import { searchRepository } from "../repository-index/search.js";
 import { getPersistentTransportStatus } from "../persistent-transport/client.js";
 import { hasTypesafeCredentials } from "../adapters/typesafe/client.js";
 import { PINNED_JEV_MODEL } from "../core/decision/constants.js";
+import { getOperationalStore } from "../storage/operational-context.js";
 
 function semanticDecisionPlaneFinding() {
   const credentialState = hasTypesafeCredentials() ? "credentials configured" : "credentials missing";
@@ -193,20 +194,39 @@ async function inspectRepositoryIndexForDoctor({ target, packageRoot, repository
   return result;
 }
 
+async function inspectStorageForDoctor(target, findings) {
+  let storage = null;
+  const store = getOperationalStore(target);
+  if (store) {
+    const { checkStorageIntegrity, readStorageMeta } = await import("../storage/connection.js");
+    const integrity = checkStorageIntegrity(store.db);
+    const metadata = readStorageMeta(store.db);
+    storage = { backend: "sqlite", storageVersion: metadata.storage_version, schemaVersion: metadata.schema_version, integrity };
+    findings.push(finding(
+      integrity.ok ? "sqlite-storage-integrity" : "E_STORAGE_INTEGRITY_INVALID",
+      integrity.ok ? "info" : "error",
+      ".forgeloop/state.sqlite",
+      integrity.ok ? "SQLite pages, foreign keys, ledger hashes and artifact bindings passed storage integrity checks." : "SQLite storage integrity checks failed; no automatic evidence repair was attempted.",
+      integrity.ok ? "Domain chronology and authority still require their existing validators." : "Preserve the database and diagnose the reported storage inconsistencies before writing or migrating.",
+    ));
+  }
+
+  return storage ? { storage } : {};
+}
+
+async function findDoctorTransactions(target) {
+  // SQLite recovery belongs to its native open/transaction boundary. Retained
+  // legacy manifests are import evidence, not operational recovery input.
+  return getOperationalStore(target) ? [] : findIncompleteTransactions(target);
+}
+
 export async function runDoctor({ target, packageRoot, adoptPaths = [], strict = false, fix = false, repositoryIndex, repositoryIndexOptions }) {
   const findings = [];
-  let incompleteTransactions = await findIncompleteTransactions(target);
-  if (fix && incompleteTransactions.some((transaction) => transaction.status === "COMMITTING")) {
-    const recovered = await recoverIncompleteTransactions(target);
-    for (const transaction of recovered) {
-      findings.push(finding(
-        transaction.status === "ROLLED_BACK" ? "TRANSACTION_RECOVERED" : "E_TRANSACTION_RECOVERY_FAILED",
-        transaction.status === "ROLLED_BACK" ? "info" : "error",
-        `.forgeloop/.txn/${transaction.transactionId}`,
-        `Transaction recovery result: ${transaction.status}.`,
-      ));
-    }
-    incompleteTransactions = await findIncompleteTransactions(target);
+  const incompleteTransactions = await findDoctorTransactions(target);
+  if (fix && incompleteTransactions.length) {
+    findings.push(finding("E_STORAGE_OPERATION_UNSUPPORTED", "error", ".forgeloop/.txn",
+      "Filesystem transaction repair is retired; retained evidence was preserved.",
+      "Reconcile incomplete transactions with the compatible pre-migration release before importing into SQLite."));
   }
   for (const transaction of incompleteTransactions) {
     findings.push(finding(
@@ -407,11 +427,14 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
 
   findings.push(semanticDecisionPlaneFinding());
 
+  const storageFields = await inspectStorageForDoctor(target, findings);
+
   const ok = findings.every((item) => item.severity !== "error")
     && (!strict || findings.every((item) => item.severity !== "warning"));
   return {
     ok,
     findings,
+    ...storageFields,
     repositoryIndex: repositoryIndexResult,
     evidence: [createEvidence({
       kind: "OBSERVED",

package/src/commands/gate-record.js

@@ -1,13 +1,12 @@
-import { lstat, readFile as readBytesFromFile } from "node:fs/promises";
 import path from "node:path";
+import { lstat } from "node:fs/promises";
 
-import { sha256 } from "../core/manifest.js";
-import { ensureWithin, isPathWithin, realpathWithTransientWindowsRetry } from "../core/filesystem.js";
+import { assertSafePath, ensureWithin } from "../core/filesystem.js";
 import { readPersistedRoute } from "../core/route-artifact.js";
 import { readContract } from "../core/contract.js";
 import { readGuideMetadata, requiredGatesForGuides } from "../core/guide-metadata.js";
 import { optionalConfig } from "../core/preflight-loaders.js";
-import { persistGate } from "../core/gate-artifact.js";
+import { persistGate, readCanonicalGateArtifactBinding, hashGateFile, readGateFileJson } from "../core/gate-artifact.js";
 import { readWorkState } from "../core/work-state.js";
 import { taskArtifactPath, taskGatePath } from "../core/task-paths.js";
 import { withTaskMutation } from "../core/task-command.js";
@@ -61,30 +60,29 @@ async function hashArtifact(target, artifactPath) {
   if (typeof artifactPath !== "string" || !artifactPath || path.isAbsolute(artifactPath)) {
     throw gateError(`Gate artifact must be a project-relative path: ${artifactPath}`);
   }
-  let candidate;
   try {
-    candidate = ensureWithin(target, artifactPath);
+    ensureWithin(target, artifactPath);
   } catch (cause) {
     throw gateError(`Gate artifact escapes the project: ${artifactPath}`, { cause });
   }
-  let stat;
+  const canonical = readCanonicalGateArtifactBinding(target, artifactPath);
+  if (canonical) {
+    await assertSafePath(target, artifactPath);
+    if (canonical.sha256 === null) throw gateError(`Gate artifact is unavailable: ${artifactPath}`);
+    if (canonical.byteLength > MAX_GATE_ARTIFACT_BYTES) throw gateError(`Gate artifact exceeds the maximum size of ${MAX_GATE_ARTIFACT_BYTES} bytes: ${artifactPath}`);
+    return { path: artifactPath, sha256: canonical.sha256 };
+  }
+  let info;
+  try { info = await lstat(ensureWithin(target, artifactPath)); }
+  catch (cause) { throw gateError(`Gate artifact is unavailable: ${artifactPath}`, { cause }); }
+  if (!info.isFile() || info.isSymbolicLink()) throw gateError(`Gate artifact must be a regular file: ${artifactPath}`);
+  if (info.size > MAX_GATE_ARTIFACT_BYTES) throw gateError(`Gate artifact exceeds the maximum size of ${MAX_GATE_ARTIFACT_BYTES} bytes: ${artifactPath}`);
   try {
-    stat = await lstat(candidate);
+    const binding = await hashGateFile(target, artifactPath, { maxBytes: MAX_GATE_ARTIFACT_BYTES });
+    return { path: artifactPath, sha256: binding.sha256 };
   } catch (cause) {
-    throw gateError(`Gate artifact is unavailable: ${artifactPath}`, { cause });
-  }
-  if (!stat.isFile() || stat.isSymbolicLink()) {
-    throw gateError(`Gate artifact must be a regular file: ${artifactPath}`);
-  }
-  if (stat.size > MAX_GATE_ARTIFACT_BYTES) {
-    throw gateError(`Gate artifact exceeds the maximum size of ${MAX_GATE_ARTIFACT_BYTES} bytes: ${artifactPath}`);
-  }
-  const rootReal = await realpathWithTransientWindowsRetry(target);
-  const candidateReal = await realpathWithTransientWindowsRetry(candidate).catch(() => null);
-  if (!candidateReal || !isPathWithin(rootReal, candidateReal)) {
-    throw gateError(`Gate artifact escapes the project: ${artifactPath}`);
+    throw gateError(`Gate artifact is unavailable or unsafe: ${artifactPath}`, { cause });
   }
-  return { path: artifactPath, sha256: sha256(await readBytesFromFile(candidateReal)) };
 }
 
 async function readEvidenceFile(target, evidencePath) {
@@ -92,16 +90,7 @@ async function readEvidenceFile(target, evidencePath) {
     throw gateError(`Gate evidence must be a project-relative path: ${evidencePath}`);
   }
   try {
-    const candidate = ensureWithin(target, evidencePath);
-    const stat = await lstat(candidate);
-    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("not a regular file");
-    if (stat.size > MAX_GATE_EVIDENCE_BYTES) throw new Error(`file exceeds ${MAX_GATE_EVIDENCE_BYTES} bytes`);
-    const rootReal = await realpathWithTransientWindowsRetry(target);
-    const candidateReal = await realpathWithTransientWindowsRetry(candidate);
-    if (!isPathWithin(rootReal, candidateReal)) throw new Error("outside project");
-    const bytes = await readBytesFromFile(candidateReal);
-    if (bytes.length > MAX_GATE_EVIDENCE_BYTES) throw new Error(`file exceeds ${MAX_GATE_EVIDENCE_BYTES} bytes`);
-    const value = JSON.parse(bytes.toString("utf8"));
+    const value = await readGateFileJson(target, evidencePath, { maxBytes: MAX_GATE_EVIDENCE_BYTES });
     return { path: evidencePath, value };
   } catch (cause) {
     throw gateError(`Gate evidence file is invalid: ${evidencePath}`, { cause });

package/src/commands/gate-revalidate.js

@@ -1,10 +1,7 @@
-import { lstat } from "node:fs/promises";
-
 import { optionalConfig } from "../core/preflight-loaders.js";
 import { readContract } from "../core/contract.js";
 import { appendProtocolEvent, validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
-import { ensureWithin, isPathWithin, readBytes, realpathWithTransientWindowsRetry } from "../core/filesystem.js";
-import { sha256 } from "../core/manifest.js";
+import { assertSafePath, ensureWithin } from "../core/filesystem.js";
 import { requiredGatesForGuides } from "../core/guide-metadata.js";
 import { readPersistedRoute } from "../core/route-artifact.js";
 import { staleReasons } from "../core/next-action-artifacts.js";
@@ -13,7 +10,7 @@ import { taskGatePath, taskArtifactPath } from "../core/task-paths.js";
 import { withTaskMutation } from "../core/task-command.js";
 import { readWorkState } from "../core/work-state.js";
 import { stateIdentityErrors } from "../core/completion-relationships.js";
-import { persistGate, readGateIfPresent, validateGateArtifacts } from "../core/gate-artifact.js";
+import { persistGate, readCanonicalGateArtifactBinding, hashGateFile, readGateIfPresent, validateGateArtifacts } from "../core/gate-artifact.js";
 import {
   GATE_REVALIDATED_EVENT,
   assertGateRevalidatedDetails,
@@ -31,15 +28,16 @@ function revalidationError(message, code = "E_GATE_REVALIDATION_UNSAFE", artifac
 }
 
 async function hashGateArtifact(target, relativePath) {
-  let artifactPath;
   try {
-    artifactPath = ensureWithin(target, relativePath);
-    const stat = await lstat(artifactPath);
-    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("artifact must be a regular file");
-    const rootReal = await realpathWithTransientWindowsRetry(target);
-    const artifactReal = await realpathWithTransientWindowsRetry(artifactPath);
-    if (!isPathWithin(rootReal, artifactReal)) throw new Error("artifact resolves outside the project");
-    return { path: relativePath, sha256: sha256(await readBytes(artifactReal)) };
+    ensureWithin(target, relativePath);
+    const canonical = readCanonicalGateArtifactBinding(target, relativePath);
+    if (canonical) {
+      await assertSafePath(target, relativePath);
+      if (canonical.sha256 === null) throw new Error("artifact is missing from canonical storage");
+      return { path: relativePath, sha256: canonical.sha256 };
+    }
+    const binding = await hashGateFile(target, relativePath);
+    return { path: relativePath, sha256: binding.sha256 };
   } catch (cause) {
     throw revalidationError(`Cannot refresh gate artifact ${relativePath}: ${cause.message}`, "E_GATE_REVALIDATION_UNSAFE", [relativePath]);
   }

package/src/commands/handoff-list.js

@@ -1,10 +1,15 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import { listCanonicalHandoffs } from "../core/handoff.js";
 import {
   readHandoffAcceptanceLedger,
   resolveHandoffAcceptance,
 } from "../core/handoff-acceptance.js";
 
-export async function runHandoffList({ target, packageRoot, taskId } = {}) {
+export async function runHandoffList(options = {}) {
+  return withProjectReadSnapshot(options.target, () => projectHandoffList(options));
+}
+
+async function projectHandoffList({ target, packageRoot, taskId } = {}) {
   const handoffs = await listCanonicalHandoffs(target, { packageRoot, taskId });
   const ledger = await readHandoffAcceptanceLedger(target, packageRoot, { taskId });
   const handoffsWithAcceptance = handoffs.map((handoff) => {

package/src/commands/handoff-show.js

@@ -1,10 +1,15 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import { readCanonicalHandoff } from "../core/handoff.js";
 import {
   readHandoffAcceptanceLedger,
   resolveHandoffAcceptance,
 } from "../core/handoff-acceptance.js";
 
-export async function runHandoffShow({ target, packageRoot, taskId, handoffId } = {}) {
+export async function runHandoffShow(options = {}) {
+  return withProjectReadSnapshot(options.target, () => projectHandoffShow(options));
+}
+
+async function projectHandoffShow({ target, packageRoot, taskId, handoffId } = {}) {
   const artifact = await readCanonicalHandoff(target, { packageRoot, taskId, handoffId });
   const ledger = await readHandoffAcceptanceLedger(target, packageRoot, { taskId });
   const resolved = resolveHandoffAcceptance({

package/src/commands/migrate-protocol.js

@@ -1,7 +1,7 @@
 import { migrateProtocol } from "../core/protocol-migration.js";
 
-export async function runMigrateProtocol({ target, packageRoot, to, dryRun = false } = {}) {
-  return migrateProtocol(target, { to, dryRun, packageRoot });
+export async function runMigrateProtocol({ target, packageRoot, to, dryRun = false, destination, writersQuiesced = false } = {}) {
+  return migrateProtocol(target, { to, dryRun, packageRoot, destination, writersQuiesced });
 }
 
 export function formatMigrateProtocolResult(result) {

package/src/commands/model-route.js

@@ -1,10 +1,18 @@
 import { projectModelRoute } from "../core/model-router/router.js";
 import { resolveRequiredSemanticDecision } from "../core/decision/resolver.js";
 import { readCurrentDecisionBindings } from "../core/decision/task-bindings.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
-export async function runModelRoute({ target, packageRoot, taskId, decisionId, workType, surfaces, risks, platforms, behaviorChange, executableChange, generationRequired, architectureChange, ambiguity, semanticRecommendation, contract } = {}) {
+export async function runModelRoute(options = {}) {
+  if (options.target && options.taskId) return withProjectReadSnapshot(options.target, () => projectSnapshotModelRoute(options));
+  return projectSnapshotModelRoute(options);
+}
+
+async function projectSnapshotModelRoute({ target, packageRoot, taskId, decisionId, workType, surfaces, risks, platforms, behaviorChange, executableChange, generationRequired, architectureChange, ambiguity, semanticRecommendation, contract }) {
   if (target && taskId) {
     const bindings = await readCurrentDecisionBindings(target, packageRoot, taskId);
+    // Decision stateFingerprint includes semantic inputs; this reader proves the lifecycle via taskStateFingerprint.
+    delete bindings.stateFingerprint;
     const decision = await resolveRequiredSemanticDecision({
       target, packageRoot, taskId, decisionId, decisionKind: "MODEL_ROUTE", currentBindings: bindings,
     });

package/src/commands/next.js

@@ -3,8 +3,14 @@ import { withResolvedTask } from "../core/task-command.js";
 import { readPersistedRoute } from "../core/route-artifact.js";
 import { projectExecutionProfile } from "../core/execution-profile.js";
 import { explainNextAction } from "../core/next-explanation.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
-export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false, explain = false }) {
+export async function runNext(options) {
+  const read = () => projectNext(options);
+  return options.target ? withProjectReadSnapshot(options.target, read) : read();
+}
+
+async function projectNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false, explain = false }) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
     const result = await getNextAction({
       target,

package/src/commands/policy-diff.js

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { isOperationalArtifactPath, needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
+import { getOperationalStore, readOperationalText } from "../storage/operational-context.js";
 import { diffPolicies } from "../core/policy-diff.js";
 import {
   loadEffectiveRules,
@@ -7,6 +9,23 @@ import {
   readTaskPolicySnapshot,
 } from "../core/policy-engine.js";
 
+function canonicalInputPath(target, file) {
+  return path.relative(target, path.resolve(target, file)).replaceAll("\\", "/");
+}
+
+async function readPolicyInput(target, file) {
+  const relative = canonicalInputPath(target, file);
+  const native = readOperationalText(target, relative);
+  if (native.selected) {
+    if (native.text === null) throw Object.assign(new Error(`Policy input does not exist: ${relative}`), { code: "ENOENT" });
+    return JSON.parse(native.text);
+  }
+  if (getOperationalStore(target) && isOperationalArtifactPath(relative)) {
+    throw Object.assign(new Error(`Unsupported canonical policy input: ${relative}`), { code: "E_STORAGE_OPERATION_UNSUPPORTED" });
+  }
+  return JSON.parse(await readFile(path.resolve(target, file), "utf8"));
+}
+
 export async function runPolicyDiff({
   target = process.cwd(),
   packageRoot,
@@ -14,12 +33,15 @@ export async function runPolicyDiff({
   before = null,
   after = null,
 } = {}) {
+  if ([before, after].some(file => file && isOperationalArtifactPath(canonicalInputPath(target, file)))
+    && await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => runPolicyDiff({ target, packageRoot, taskId, before, after }), { readOnly: true });
+  }
   let beforePolicy;
   let afterPolicy;
 
   if (before) {
-    const rawBefore = await readFile(path.resolve(target, before), "utf8");
-    beforePolicy = JSON.parse(rawBefore);
+    beforePolicy = await readPolicyInput(target, before);
   } else if (taskId) {
     const snapshot = await readTaskPolicySnapshot(target, taskId, packageRoot);
     beforePolicy = snapshot ? { rules: snapshot.rules, baseline: { entries: [] } } : { rules: [], baseline: { entries: [] } };
@@ -28,8 +50,7 @@ export async function runPolicyDiff({
   }
 
   if (after) {
-    const rawAfter = await readFile(path.resolve(target, after), "utf8");
-    afterPolicy = JSON.parse(rawAfter);
+    afterPolicy = await readPolicyInput(target, after);
   } else {
     const rules = await loadEffectiveRules(target, packageRoot);
     const baseline = await readBaseline(target, packageRoot);

package/src/commands/progress.js

@@ -1,5 +1,5 @@
 import { evaluateProgress, PROGRESS_STATUS } from "../core/progress.js";
-import { readEvents } from "../core/events.js";
+import { withEventLedgerAudit } from "../core/events.js";
 import { readWorkState } from "../core/work-state.js";
 import { resolveTaskContext, TASK_SELECTION_MODES } from "../core/task-context.js";
 
@@ -13,16 +13,22 @@ export async function runProgress({ target, packageRoot, taskId, task }) {
   });
   const activeTaskId = resolved.taskId;
 
-  const state = await readWorkState(target, { packageRoot, taskId: activeTaskId });
-  const events = await readEvents(target, packageRoot, { taskId: activeTaskId });
-
-  const progress = evaluateProgress({ state, events });
-  return {
-    taskId: activeTaskId ?? state?.taskId ?? "unknown",
-    phase: state?.phase ?? "UNKNOWN",
-    verificationCycle: state?.verificationCycle ?? 1,
-    ...progress,
-  };
+  return withEventLedgerAudit(target, packageRoot, { taskId: activeTaskId }, async ledger => {
+    if (!ledger.valid) {
+      const first = ledger.errors[0] ?? { code: "E_LEDGER_INVALID", message: "Progress requires a valid event ledger" };
+      throw Object.assign(new Error(first.message), { code: first.code });
+    }
+    const state = await readWorkState(target, { packageRoot, taskId: activeTaskId });
+    const events = ledger.events;
+
+    const progress = evaluateProgress({ state, events });
+    return {
+      taskId: activeTaskId ?? state?.taskId ?? "unknown",
+      phase: state?.phase ?? "UNKNOWN",
+      verificationCycle: state?.verificationCycle ?? 1,
+      ...progress,
+    };
+  });
 }
 
 export function formatProgressResult(result) {

package/src/commands/record-diagnosis.js

@@ -1,3 +1,4 @@
+import { assertCanonicalPersistence } from "../storage/operational-context.js";
 import { recordDiagnosis } from "../core/diagnosis.js";
 import { recordStructuredDiagnosticCase } from "../core/diagnostic-record.js";
 import { withTaskMutation } from "../core/task-command.js";
@@ -16,7 +17,9 @@ export async function runRecordDiagnosis({
   nextSafeAction,
   taskId,
   task,
+  persistence = null,
 }) {
+  assertCanonicalPersistence(persistence);
   if (file) {
     const legacyFields = [hypothesis, failureClass, settledBy, nextSafeAction].some((value) => value !== undefined && value !== null)
       || (Array.isArray(evidenceRefs) && evidenceRefs.length > 0)

package/src/commands/semantic-plan.js

@@ -1,13 +1,37 @@
 import { runSemanticPlan as projectPlan } from "../core/semantic-planning/service.js";
 import { resolveRequiredSemanticDecision } from "../core/decision/resolver.js";
 import { readCurrentDecisionBindings } from "../core/decision/task-bindings.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 
-export async function runSemanticPlan({ target, packageRoot, taskId, decisionId, kind, input, semanticRecommendation } = {}) {
+const PROJECTION_VALUES = Object.freeze({
+  failure: Object.freeze({ implementation: "incorrect implementation", expectation: "stale expectation",
+    state: "state divergence", dependency: "dependency incompatibility", environment: "network/environment" }),
+  diagnosis: Object.freeze({ inspect_state: "inspect state transition", inspect_caller: "inspect caller",
+    inspect_dependency: "inspect dependency behavior", narrow_experiment: "run narrower experiment" }),
+});
+
+function projectionRecommendation(kind, decision) {
+  const values = PROJECTION_VALUES[kind];
+  if (!values) return decision;
+  const field = kind === "failure" ? "failureClass" : "priority";
+  const value = decision[field];
+  if (value === "unknown") return null;
+  return { ...decision, [field]: Object.hasOwn(values, value) ? values[value] : value };
+}
+
+export async function runSemanticPlan(options = {}) {
+  if (options.target && options.taskId) return withProjectReadSnapshot(options.target, () => projectSnapshotSemanticPlan(options));
+  return projectSnapshotSemanticPlan(options);
+}
+
+async function projectSnapshotSemanticPlan({ target, packageRoot, taskId, decisionId, kind, input, semanticRecommendation }) {
   if (target && taskId) {
     const decisionKind = { failure: "FAILURE_TRIAGE", diagnosis: "DIAGNOSIS_PRIORITY", review: "REVIEW_PLAN" }[kind];
     const bindings = await readCurrentDecisionBindings(target, packageRoot, taskId);
+    // Decision stateFingerprint includes semantic inputs; this reader proves the lifecycle via taskStateFingerprint.
+    delete bindings.stateFingerprint;
     const decision = await resolveRequiredSemanticDecision({ target, packageRoot, taskId, decisionId, decisionKind, currentBindings: bindings });
-    semanticRecommendation = decision.decision;
+    semanticRecommendation = projectionRecommendation(kind, decision.decision);
   }
   return projectPlan({ kind, input, semanticRecommendation });
 }