@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.4

package/src/core/transaction.js

@@ -1,50 +1,29 @@
-import { randomUUID } from "node:crypto";
-import { AsyncLocalStorage } from "node:async_hooks";
-import { mkdir, open, readdir, readFile, realpath, rename, stat, truncate, unlink } from "node:fs/promises";
-import { setTimeout as delay } from "node:timers/promises";
-import path from "node:path";
+import { readdir } from "node:fs/promises";
 
-import { assertSafePath, ensureWithin, fileExists, writeFileAtomic } from "./filesystem.js";
-import { withTaskLock } from "./task-lock.js";
-import { E_TASK_LOCKED } from "./error-codes.js";
+import { assertSafePath, fileExists } from "./filesystem.js";
+import { getOperationalStore } from "../storage/operational-context.js";
 
 const TRANSACTION_ROOT = ".forgeloop/.txn";
-const LOCK_WAIT_TIMEOUT_MS = 5_000;
-const transactionContext = new AsyncLocalStorage();
-
-export function getActiveTaskTransaction() {
-  return transactionContext.getStore() ?? null;
-}
 
 export async function getTaskTransaction(target) {
-  const transaction = getActiveTaskTransaction();
-  if (transaction && transaction.target !== await realpath(target)) {
-    const error = new Error("Cannot reuse a task transaction for a different project");
-    error.code = "E_TASK_CONTEXT_MISMATCH";
-    throw error;
-  }
-  return transaction;
+  return getOperationalStore(target)?.transaction ?? null;
 }
 
 const TERMINAL_STATUSES = new Set(["COMMITTED", "ROLLED_BACK", "ABORTED"]);
 
-function transactionPath(transactionId) {
-  return `${TRANSACTION_ROOT}/${transactionId}`;
-}
-
-async function writeManifest(target, relativePath, manifest) {
-  await writeFileAtomic(ensureWithin(target, relativePath), `${JSON.stringify(manifest, null, 2)}\n`);
-}
-
 export async function findIncompleteTransactions(target) {
-  const root = ensureWithin(target, TRANSACTION_ROOT);
+  const root = await assertSafePath(target, TRANSACTION_ROOT);
   if (!(await fileExists(root))) return [];
   const entries = await readdir(root, { withFileTypes: true });
   const found = [];
   for (const entry of entries) {
+    await assertSafePath(target, `${TRANSACTION_ROOT}/${entry.name}`);
     if (!entry.isDirectory()) continue;
+    const relative = `${TRANSACTION_ROOT}/${entry.name}/manifest.json`;
+    await assertSafePath(target, relative);
     try {
-      const manifest = JSON.parse(await readFile(path.join(root, entry.name, "manifest.json"), "utf8"));
+      const { readStorageMetadataJson } = await import("../storage/metadata-json.js");
+      const manifest = await readStorageMetadataJson(target, relative);
       if (!TERMINAL_STATUSES.has(manifest.status)) found.push(manifest);
     } catch {
       found.push({ transactionId: entry.name, status: "ABANDONED", malformed: true });
@@ -53,263 +32,12 @@ export async function findIncompleteTransactions(target) {
   return found;
 }
 
-function writePath(entry) {
-  return typeof entry === "string" ? entry : entry.path;
-}
-
-async function rollbackPublishedWrites(target, root, manifest) {
-  const writes = [...manifest.writes].reverse();
-  for (const entry of writes) {
-    if (!entry || typeof entry !== "object") continue;
-    const relativePath = writePath(entry);
-    await assertSafePath(target, relativePath);
-    if (entry.kind === "APPEND") {
-      if (!entry.appendStarted) continue;
-      const destination = ensureWithin(target, relativePath);
-      const originalSize = Number.isInteger(entry.originalSize) && entry.originalSize >= 0 ? entry.originalSize : 0;
-      if (await fileExists(destination)) {
-        if (originalSize === 0) await unlink(destination);
-        else await truncate(destination, originalSize);
-      }
-      continue;
-    }
-    if (!entry.published && !entry.backupPending && !entry.backupCreated) continue;
-    const destination = ensureWithin(target, relativePath);
-    const backup = ensureWithin(target, `${root}/backup/${relativePath}`);
-    if (entry.published && await fileExists(destination)) await unlink(destination);
-    if (entry.hadPrevious && await fileExists(backup)) {
-      await mkdir(path.dirname(destination), { recursive: true });
-      await rename(backup, destination);
-    }
-  }
-}
-
-export async function recoverIncompleteTransactions(target) {
-  const rootPath = ensureWithin(target, TRANSACTION_ROOT);
-  if (!(await fileExists(rootPath))) return [];
-  const recovered = [];
-  for (const entry of await readdir(rootPath, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const root = transactionPath(entry.name);
-    const manifestPath = `${root}/manifest.json`;
-    try {
-      const manifest = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
-      if (manifest.status !== "COMMITTING") continue;
-      await withTaskLock(target, manifest.lockTaskId ?? manifest.taskId ?? "transaction-recovery", "recover-transaction", async () => {
-        const current = JSON.parse(await readFile(ensureWithin(target, manifestPath), "utf8"));
-        if (current.status !== "COMMITTING") return;
-        await rollbackPublishedWrites(target, root, current);
-        current.status = "ROLLED_BACK";
-        current.recoveredAt = new Date().toISOString();
-        await writeManifest(target, manifestPath, current);
-        recovered.push({ transactionId: current.transactionId, status: current.status });
-      });
-    } catch (error) {
-      recovered.push({ transactionId: entry.name, status: "RECOVERY_FAILED", error: error.message });
-    }
-  }
-  return recovered;
-}
-
-export async function withTaskTransaction({
-  target,
-  taskId,
-  lockTaskId = taskId,
-  operation = "mutation",
-  packageRoot,
-  recordCommitEvent = false,
-} = {}, callback) {
+export async function withTaskTransaction({ target, taskId, operation = "mutation", packageRoot, recordCommitEvent = false } = {}, callback) {
   if (!target || !taskId) throw new Error("target and taskId are required for a task transaction");
-  target = await realpath(target);
-  const activeTransaction = await getTaskTransaction(target);
-  if (activeTransaction) {
-    if (activeTransaction.taskId !== taskId) {
-      throw new Error(`cannot nest task transaction for ${taskId} inside ${activeTransaction.taskId}`);
-    }
-    return callback(activeTransaction);
-  }
-  const started = Date.now();
-  const runWithLock = async () => withTaskLock(target, lockTaskId, operation, async (lock) => {
-    const transactionId = `txn-${randomUUID()}`;
-    const root = transactionPath(transactionId);
-    const stageRoot = `${root}/stage`;
-    const manifestPath = `${root}/manifest.json`;
-    await assertSafePath(target, manifestPath);
-    await mkdir(ensureWithin(target, stageRoot), { recursive: true });
-    const manifest = { schemaVersion: 1, transactionId, taskId, lockTaskId, operation, lockId: lock.lockId, startedAt: new Date().toISOString(), status: "STAGING", writes: [] };
-    await writeManifest(target, manifestPath, manifest);
-    const tx = {
-      target,
-      transactionId,
-      taskId,
-      operation,
-      lock,
-      async readText(relativePath) {
-        await assertSafePath(target, relativePath);
-        if (manifest.writes.some((entry) => writePath(entry) === relativePath && entry.kind === "DELETE")) {
-          return null;
-        }
-        const staged = ensureWithin(target, `${stageRoot}/${relativePath}`);
-        if (await fileExists(staged)) return readFile(staged, "utf8");
-        const appendStaged = ensureWithin(target, `${stageRoot}/${relativePath}.append`);
-        const appendText = await fileExists(appendStaged) ? await readFile(appendStaged, "utf8") : "";
-        const destination = ensureWithin(target, relativePath);
-        if (!(await fileExists(destination))) return appendText || null;
-        return `${await readFile(destination, "utf8")}${appendText}`;
-      },
-      async stageText(relativePath, text) {
-        await assertSafePath(target, relativePath);
-        const conflicting = manifest.writes.find((entry) => writePath(entry) === relativePath);
-        if (conflicting?.kind === "APPEND" || conflicting?.kind === "DELETE") {
-          throw new Error(`cannot replace ${conflicting.kind.toLowerCase()}-staged path: ${relativePath}`);
-        }
-        const staged = `${stageRoot}/${relativePath}`;
-        await assertSafePath(target, staged);
-        await writeFileAtomic(ensureWithin(target, staged), text);
-        if (!manifest.writes.some((entry) => writePath(entry) === relativePath)) {
-          manifest.writes.push({ path: relativePath, hadPrevious: false, published: false });
-        }
-        await writeManifest(target, manifestPath, manifest);
-      },
-      async appendText(relativePath, text) {
-        await assertSafePath(target, relativePath);
-        if (typeof text !== "string" || text.length === 0) throw new Error("transaction append text must be a non-empty string");
-        if (manifest.writes.some((entry) => writePath(entry) === relativePath && entry.kind !== "APPEND")) {
-          throw new Error(`cannot append to replace-staged path: ${relativePath}`);
-        }
-        const destination = ensureWithin(target, relativePath);
-        const staged = ensureWithin(target, `${stageRoot}/${relativePath}.append`);
-        const existing = await fileExists(staged) ? await readFile(staged, "utf8") : "";
-        await writeFileAtomic(staged, `${existing}${text}`);
-        let entry = manifest.writes.find((candidate) => writePath(candidate) === relativePath);
-        if (!entry) {
-          entry = {
-            path: relativePath,
-            kind: "APPEND",
-            originalSize: (await fileExists(destination)) ? (await stat(destination)).size : 0,
-            appendStarted: false,
-            published: false,
-          };
-          manifest.writes.push(entry);
-        }
-        await writeManifest(target, manifestPath, manifest);
-      },
-      async stageDelete(relativePath) {
-        await assertSafePath(target, relativePath);
-        if (manifest.writes.some((entry) => writePath(entry) === relativePath)) {
-          throw new Error(`cannot delete write-staged path: ${relativePath}`);
-        }
-        const destination = ensureWithin(target, relativePath);
-        if (!(await fileExists(destination))) {
-          throw new Error(`transaction delete target is missing: ${relativePath}`);
-        }
-        manifest.writes.push({
-          path: relativePath,
-          kind: "DELETE",
-          hadPrevious: false,
-          published: false,
-        });
-        await writeManifest(target, manifestPath, manifest);
-      },
-    };
-    try {
-      const result = await transactionContext.run(tx, async () => {
-        const callbackResult = await callback(tx);
-        if (recordCommitEvent) {
-          // Import lazily to keep the transaction/event dependency directional
-          // at module initialization. The event is staged while this task's
-          // transaction context is still active and is published last below.
-          const { appendProtocolEvent } = await import("./events.js");
-          await appendProtocolEvent(target, {
-            taskId,
-            event: "TRANSACTION_COMMITTED",
-            details: { transactionId, operation },
-          }, packageRoot, { taskId });
-        }
-        return callbackResult;
-      });
-      manifest.status = "COMMITTING";
-      await writeManifest(target, manifestPath, manifest);
-      // The ledger is the commit witness. Publishing it last means that a
-      // visible TRANSACTION_COMMITTED event cannot precede a required staged
-      // artifact in the same transaction.
-      const writes = [...manifest.writes].sort((left, right) => {
-        const leftIsLedger = writePath(left).endsWith("events.ndjson");
-        const rightIsLedger = writePath(right).endsWith("events.ndjson");
-        return Number(leftIsLedger) - Number(rightIsLedger);
-      });
-      for (const entry of writes) {
-        const relativePath = writePath(entry);
-        const staged = ensureWithin(target, `${stageRoot}/${relativePath}`);
-        const destination = ensureWithin(target, relativePath);
-        if (entry.kind === "APPEND") {
-          const appendStaged = ensureWithin(target, `${stageRoot}/${relativePath}.append`);
-          const appendText = await readFile(appendStaged, "utf8");
-          await mkdir(path.dirname(destination), { recursive: true });
-          entry.appendStarted = true;
-          await writeManifest(target, manifestPath, manifest);
-          const handle = await open(destination, "a", 0o644);
-          try {
-            await handle.writeFile(appendText);
-            await handle.sync();
-          } finally {
-            await handle.close();
-          }
-          entry.published = true;
-          await writeManifest(target, manifestPath, manifest);
-          continue;
-        }
-        const backup = ensureWithin(target, `${root}/backup/${relativePath}`);
-        await mkdir(path.dirname(destination), { recursive: true });
-        entry.hadPrevious = await fileExists(destination);
-        if (entry.hadPrevious) {
-          entry.backupPending = true;
-          await writeManifest(target, manifestPath, manifest);
-          await mkdir(path.dirname(backup), { recursive: true });
-          await rename(destination, backup);
-          entry.backupCreated = true;
-        }
-        await writeManifest(target, manifestPath, manifest);
-        if (entry.kind === "DELETE") {
-          entry.published = true;
-          await writeManifest(target, manifestPath, manifest);
-          continue;
-        }
-        await rename(staged, destination);
-        entry.published = true;
-        await writeManifest(target, manifestPath, manifest);
-      }
-      manifest.status = "COMMITTED";
-      manifest.committedAt = new Date().toISOString();
-      await writeManifest(target, manifestPath, manifest);
-      return result;
-    } catch (error) {
-      if (manifest.status === "COMMITTING") {
-        try {
-          await rollbackPublishedWrites(target, root, manifest);
-          manifest.status = "ROLLED_BACK";
-          manifest.recoveredAt = new Date().toISOString();
-        } catch (rollbackError) {
-          manifest.status = "ABANDONED";
-          manifest.rollbackError = { message: rollbackError.message };
-        }
-      } else {
-        // Staging has not published any writes; retain the diagnostic record
-        // without requiring recovery of a project that was never modified.
-        manifest.status = "ABORTED";
-      }
-      manifest.failedAt = new Date().toISOString();
-      manifest.error = { message: error.message };
-      await writeManifest(target, manifestPath, manifest);
-      throw error;
-    }
-  });
-  while (true) {
-    try {
-      return await runWithLock();
-    } catch (error) {
-      if (error.code !== E_TASK_LOCKED || Date.now() - started >= LOCK_WAIT_TIMEOUT_MS) throw error;
-      await delay(20);
-    }
+  if (!getOperationalStore(target)) {
+    const { withProjectStorage } = await import("../storage/project-boundary.js");
+    return withProjectStorage(target, () => withTaskTransaction({ target, taskId, operation, packageRoot, recordCommitEvent }, callback));
   }
+  const { withOperationalTransaction } = await import("../storage/unit-of-work.js");
+  return withOperationalTransaction({ target, taskId, operation, packageRoot, recordCommitEvent }, callback);
 }

package/src/core/verification-scope.js

@@ -1,3 +1,4 @@
+import { operationalArtifactExists } from "../storage/operational-context.js";
 import { canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { getPackageRoot } from "./templates.js";
@@ -5,6 +6,7 @@ import { currentRepositoryFingerprint } from "./repository.js";
 import { resolveRevisionProvider } from "./revision/provider.js";
 import { REVISION_PROVIDERS } from "./revision/registry.js";
 import { readScopedCheckerCapabilities } from "./verification-scope-capability.js";
+import { withNativeReadScope } from "./native-storage.js";
 import { readContract } from "./contract.js";
 import { readPersistedRoute } from "./route-artifact.js";
 import { readWorkState } from "./work-state.js";
@@ -123,17 +125,19 @@ export async function validateVerificationScope(scope, packageRoot = getPackageR
 }
 
 export async function readVerificationScope(target, { taskId, packageRoot = getPackageRoot(), scopePath = null } = {}) {
-  const relativePath = scopePath ?? taskVerificationScopePath(taskId);
-  if (!(await fileExists(ensureWithin(target, relativePath)))) {
-    throw scopeError("E_VERIFICATION_SCOPE_INVALID", `Verification scope is missing: ${relativePath}`, [relativePath]);
-  }
-  try {
-    const artifact = await readJsonArtifact(target, relativePath, "verification-scope", packageRoot);
-    return { ...artifact, value: await validateVerificationScope(artifact.value, packageRoot) };
-  } catch (error) {
-    if (error.code === "E_VERIFICATION_SCOPE_INVALID") throw error;
-    throw scopeError("E_VERIFICATION_SCOPE_INVALID", error.message, [relativePath]);
-  }
+  return withNativeReadScope(target, async () => {
+    const relativePath = scopePath ?? taskVerificationScopePath(taskId);
+    if (!(operationalArtifactExists(target, relativePath) ?? await fileExists(ensureWithin(target, relativePath)))) {
+      throw scopeError("E_VERIFICATION_SCOPE_INVALID", `Verification scope is missing: ${relativePath}`, [relativePath]);
+    }
+    try {
+      const artifact = await readJsonArtifact(target, relativePath, "verification-scope", packageRoot);
+      return { ...artifact, value: await validateVerificationScope(artifact.value, packageRoot) };
+    } catch (error) {
+      if (error.code === "E_VERIFICATION_SCOPE_INVALID") throw error;
+      throw scopeError("E_VERIFICATION_SCOPE_INVALID", error.message, [relativePath]);
+    }
+  });
 }
 
 export async function validateVerificationScopeFreshness(target, {
@@ -249,7 +253,11 @@ export async function resolveVerificationScope(target, {
   return { scope, inputs };
 }
 
-export async function persistVerificationScope(target, scope, { taskId, packageRoot = getPackageRoot() } = {}) {
+export async function persistVerificationScope(target, scope, options = {}) {
+  return withTaskTransaction({ target, taskId: options.taskId, packageRoot: options.packageRoot, operation: "verify-scope" }, () => persistVerificationScopeInTransaction(target, scope, options));
+}
+
+async function persistVerificationScopeInTransaction(target, scope, { taskId, packageRoot = getPackageRoot() } = {}) {
   const relativePath = taskVerificationScopePath(taskId);
   const artifact = await writeJsonArtifact(target, relativePath, scope, "verification-scope", packageRoot, { taskId, operation: "verify-scope" });
   await appendProtocolEvent(target, {

package/src/core/work-state.js

@@ -1,5 +1,6 @@
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
+import { withExistingProjectScope } from "../storage/existing-project-scope.js";
 import { createHash } from "node:crypto";
-import { unlink } from "node:fs/promises";
 import path from "node:path";
 
 import {
@@ -7,7 +8,6 @@ import {
   ensureWithin,
   fileExists,
   readBytes,
-  writeFileAtomic,
 } from "./filesystem.js";
 import { GUIDE_IDS, PROTOCOL_VERSION, assertFailureClass, assertWorkPhase, isValidTransition } from "./protocol.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
@@ -20,6 +20,8 @@ import { assertCoverageList } from "./coverage.js";
 import { canonicalFingerprint } from "./artifacts.js";
 import { taskArtifactPath } from "./task-paths.js";
 import { getTaskTransaction, withTaskTransaction } from "./transaction.js";
+import { readOperationalText, getOperationalStore } from "../storage/operational-context.js";
+import { withNativeReadScope } from "./native-storage.js";
 
 export const WORK_STATE_PATH = ".forgeloop/work-state.json";
 
@@ -236,67 +238,83 @@ async function validateStoredState(state, packageRoot = getPackageRoot()) {
 }
 
 export async function readWorkState(target, options = {}) {
-  const packageRoot = typeof options === "string" ? options : (options?.packageRoot ?? getPackageRoot());
-  const relPath = typeof options === "object" && options !== null
-    ? (options.statePath ?? options.relativePath ?? (options.taskId ? taskArtifactPath(options.taskId, "state") : (options.taskContext ? options.taskContext.paths.state : WORK_STATE_PATH)))
-    : WORK_STATE_PATH;
-
-  await assertSafePath(target, relPath);
-  const statePath = ensureWithin(target, relPath);
-  let state;
-  try {
-    const transaction = (await getTaskTransaction(target));
-    const staged = transaction ? await transaction.readText(relPath) : null;
-    if (staged === null) {
-      if (!(await fileExists(statePath))) return null;
-      const bytes = await readBytes(statePath);
-      assertJsonBytes(bytes, relPath);
-      state = JSON.parse(bytes.toString("utf8"));
-    } else {
-      const bytes = Buffer.from(staged, "utf8");
-      assertJsonBytes(bytes, relPath);
-      state = JSON.parse(staged);
+  return withNativeReadScope(target, async () => {
+    const packageRoot = typeof options === "string" ? options : (options?.packageRoot ?? getPackageRoot());
+    const relPath = typeof options === "object" && options !== null
+      ? (options.statePath ?? options.relativePath ?? (options.taskId ? taskArtifactPath(options.taskId, "state") : (options.taskContext ? options.taskContext.paths.state : WORK_STATE_PATH)))
+      : WORK_STATE_PATH;
+
+    const operational = readOperationalText(target, relPath);
+    if (operational.selected) {
+      if (operational.text === null) return null;
+      assertJsonBytes(operational.text, relPath);
+      return validateStoredState(JSON.parse(operational.text), packageRoot);
     }
-  } catch (error) {
-    throw new WorkStateError(`Unable to parse ${relPath}: ${error.message}`);
-  }
-  try {
-    return await validateStoredState(state, packageRoot);
-  } catch (error) {
-    if (error instanceof WorkStateError) throw error;
-    throw new WorkStateError(error.message);
-  }
+    await assertSafePath(target, relPath);
+    const statePath = ensureWithin(target, relPath);
+    let state;
+    try {
+      const transaction = (await getTaskTransaction(target));
+      const staged = transaction ? await transaction.readText(relPath) : null;
+      if (staged === null) {
+        if (!(await fileExists(statePath))) return null;
+        const bytes = await readBytes(statePath);
+        assertJsonBytes(bytes, relPath);
+        state = JSON.parse(bytes.toString("utf8"));
+      } else {
+        const bytes = Buffer.from(staged, "utf8");
+        assertJsonBytes(bytes, relPath);
+        state = JSON.parse(staged);
+      }
+    } catch (error) {
+      throw new WorkStateError(`Unable to parse ${relPath}: ${error.message}`);
+    }
+    try {
+      return await validateStoredState(state, packageRoot);
+    } catch (error) {
+      if (error instanceof WorkStateError) throw error;
+      throw new WorkStateError(error.message);
+    }
+  });
 }
 
 export async function readContractFingerprint(target, contractFile) {
-  await assertSafePath(target, contractFile);
-  const contractPath = ensureWithin(target, contractFile);
-  let contract;
-  try {
-    const bytes = await readBytes(contractPath);
-    assertJsonBytes(bytes, contractFile);
-    contract = JSON.parse(bytes.toString("utf8"));
-  } catch (error) {
-    throw new WorkStateError(`Unable to parse contract ${contractFile}: ${error.message}`);
-  }
-  return { path: contractFile, fingerprint: contractFingerprint(contract) };
+  return withNativeReadScope(target, async () => {
+    const operational = readOperationalText(target, contractFile);
+    if (operational.selected) {
+      if (operational.text === null) throw new WorkStateError(`Unable to parse contract ${contractFile}: artifact missing`);
+      assertJsonBytes(operational.text, contractFile);
+      return { path: contractFile, fingerprint: contractFingerprint(JSON.parse(operational.text)) };
+    }
+    await assertSafePath(target, contractFile);
+    const contractPath = ensureWithin(target, contractFile);
+    let contract;
+    try {
+      const bytes = await readBytes(contractPath);
+      assertJsonBytes(bytes, contractFile);
+      contract = JSON.parse(bytes.toString("utf8"));
+    } catch (error) {
+      throw new WorkStateError(`Unable to parse contract ${contractFile}: ${error.message}`);
+    }
+    return { path: contractFile, fingerprint: contractFingerprint(contract) };
+  });
 }
 
 export async function writeWorkState(target, state, options = {}) {
   const packageRoot = options?.packageRoot ?? getPackageRoot();
   const dryRun = options?.dryRun ?? false;
-  const relPath = options?.statePath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "state") : WORK_STATE_PATH);
-
   await validateStoredState(state, packageRoot);
-  await assertSafePath(target, relPath);
-  const serialized = `${JSON.stringify(state, null, 2)}\n`;
-  const transaction = (await getTaskTransaction(target));
-  if (!dryRun && transaction) {
-    await transaction.stageText(relPath, serialized);
-  } else {
-    const statePath = ensureWithin(target, relPath);
-    await writeFileAtomic(statePath, serialized, { dryRun });
+  const canonicalPath = taskArtifactPath(state.taskId, "state");
+  const relativePath = options?.statePath ?? options?.relativePath ?? canonicalPath;
+  if ((options?.taskId && options.taskId !== state.taskId) || relativePath !== canonicalPath) {
+    throw Object.assign(new Error("Work-state writes require their canonical task-scoped SQLite identity; use explicit export for portable files"), { code: "E_STORAGE_OPERATION_UNSUPPORTED", artifacts: [relativePath] });
+  }
+  if (dryRun) return state;
+  if (!getOperationalStore(target)) {
+    const { withProjectStorage } = await import("../storage/project-boundary.js");
+    return withProjectStorage(target, () => writeWorkState(target, state, options));
   }
+  await withTaskTransaction({ target, taskId: state.taskId, operation: "write-state", packageRoot }, tx => tx.stageText(canonicalPath, `${JSON.stringify(state, null, 2)}\n`));
   return state;
 }
 
@@ -355,18 +373,34 @@ export async function initializeWorkState(target, state, { packageRoot = getPack
 }
 
 export async function clearWorkState(target, options = {}) {
-  const relPath = options?.statePath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "state") : WORK_STATE_PATH);
-  await assertSafePath(target, relPath);
-  const statePath = ensureWithin(target, relPath);
-  if (!(await fileExists(statePath))) return { removed: false, path: relPath };
-  await unlink(statePath);
-  return { removed: true, path: relPath };
+  if (!options.taskId) throw Object.assign(new Error("Canonical artifact clearing requires a task identity"), { code: "E_STORAGE_OPERATION_UNSUPPORTED" });
+  const relPath = taskArtifactPath(options.taskId, "state");
+  const requested = options.statePath ?? options.relativePath ?? relPath;
+  if (requested !== relPath) throw Object.assign(new Error("Artifact clearing requires the canonical task path; portable exports are independent files"), { code: "E_STORAGE_OPERATION_UNSUPPORTED", artifacts: [requested] });
+  if (!getOperationalStore(target)) {
+    return withExistingProjectScope(target, () => clearWorkState(target, options));
+  }
+  const operational = readOperationalText(target, relPath);
+  if (operational.text === null) return { removed: false, path: relPath };
+  return withTaskTransaction({ target, taskId: options.taskId, operation: "clear-work-state", packageRoot: options.packageRoot }, async transaction => {
+    transaction.stageDelete(relPath);
+    return { removed: true, path: relPath };
+  });
 }
 
 export async function readRequiredArtifactFingerprints(target, artifacts) {
+  return withProjectReadSnapshot(target, () => readSelectedRequiredArtifactFingerprints(target, artifacts));
+}
+
+async function readSelectedRequiredArtifactFingerprints(target, artifacts) {
   const normalized = normalizeRequiredArtifacts(artifacts);
   const current = [];
   for (const artifact of normalized) {
+    const operational = readOperationalText(target, artifact.path);
+    if (operational.selected) {
+      current.push({ path: artifact.path, sha256: operational.text === null ? null : createHash("sha256").update(operational.text).digest("hex"), status: operational.text === null ? "missing" : "present" });
+      continue;
+    }
     await assertSafePath(target, artifact.path);
     const artifactPath = ensureWithin(target, artifact.path);
     if (!(await fileExists(artifactPath))) {
@@ -485,6 +519,7 @@ export async function classifyLoadedWorkState({ target, state, contractFile = nu
     try {
       contract = await readContractFingerprint(target, contractFile);
     } catch (error) {
+      if (error?.code === "E_STATE_REVISION_CONFLICT") throw error;
       contractError = error.message;
     }
   }
@@ -495,6 +530,7 @@ export async function classifyLoadedWorkState({ target, state, contractFile = nu
     try {
       currentArtifacts = await readRequiredArtifactFingerprints(target, state.requiredArtifacts);
     } catch (error) {
+      if (error?.code === "E_STATE_REVISION_CONFLICT") throw error;
       artifactError = error.message;
     }
   } else {
@@ -547,7 +583,11 @@ export async function classifyLoadedWorkState({ target, state, contractFile = nu
   };
 }
 
-export async function readAndClassifyWorkState({ target, packageRoot = getPackageRoot(), contractFile = null, maxAgeMs, taskId = null, stateFile = null, statePath = null } = {}) {
+export async function readAndClassifyWorkState(options = {}) {
+  return withProjectReadSnapshot(options.target, () => readAndClassifySelectedWorkState(options));
+}
+
+async function readAndClassifySelectedWorkState({ target, packageRoot = getPackageRoot(), contractFile = null, maxAgeMs, taskId = null, stateFile = null, statePath = null } = {}) {
   const effectiveStateRel = stateFile ?? statePath ?? (taskId ? taskArtifactPath(taskId, "state") : WORK_STATE_PATH);
   let state = null;
   try {
@@ -557,6 +597,7 @@ export async function readAndClassifyWorkState({ target, packageRoot = getPackag
       ...(stateFile || statePath ? { statePath: effectiveStateRel } : {}),
     });
   } catch (error) {
+    if (error?.code === "E_STATE_REVISION_CONFLICT") throw error;
     return {
       path: effectiveStateRel,
       present: true,