@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/storage/migration-source.js

@@ -0,0 +1,255 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { lstat, mkdir, open, opendir, readdir, rename } from "node:fs/promises";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { digestFile, syncDirectory } from "./file-durability.js";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { findIncompleteTransactions } from "../core/transaction.js";
+import { assertOwnedStorageMaintenance, withStorageMaintenance } from "./maintenance.js";
+import { readStorageMetadataJson, STORAGE_CATALOG_LIMITS } from "./metadata-json.js";
+import { readStorageVersionMarker } from "./storage-marker.js";
+import { LEGACY_TASK_ARTIFACT_PATHS } from "../core/task-paths.js";
+import { assertNoLegacyOperationLocks } from "./legacy-maintenance-boundary.js";
+
+export const LEGACY_SOURCE_ROOTS = Object.freeze([...new Set([
+  ...Object.values(LEGACY_TASK_ARTIFACT_PATHS),
+  ".forgeloop/task-state", ".forgeloop/events.ndjson.index.json",
+  ".forgeloop/sessions", ".forgeloop/.txn", ".forgeloop/attachments",
+  "export-index.json",
+])]);
+const SOURCE_ROOTS = LEGACY_SOURCE_ROOTS;
+
+function failure(code, message) { return Object.assign(new Error(message), { code }); }
+
+async function infoIfPresent(filename) {
+  try { return await lstat(filename); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+async function syncDirectories(directory) {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) await syncDirectories(path.join(directory, entry.name));
+  }
+  await syncDirectory(directory);
+}
+
+function recordInventoryEntry(entries, value, budget) {
+  const encoded = JSON.stringify(value);
+  // Reserve pretty-print overhead and manifest status/error metadata as well
+  // as encoded entry bytes. Refuse before retaining an oversized entry.
+  const size = Buffer.byteLength(encoded) + 128;
+  if (entries.length >= STORAGE_CATALOG_LIMITS.maxArrayLength || budget.bytes + size > STORAGE_CATALOG_LIMITS.maxBytes) {
+    throw failure("E_STORAGE_MIGRATION_SOURCE_INVALID", "Source inventory exceeds the retained manifest limits");
+  }
+  budget.bytes += size;
+  entries.push(value);
+}
+
+async function inventoryPath(target, relativePath, files, directories, budget) {
+  const filename = await assertSafePath(target, relativePath);
+  const info = await infoIfPresent(filename);
+  if (!info) return;
+  if (info.isDirectory()) {
+    recordInventoryEntry(directories, relativePath, budget);
+    for await (const entry of await opendir(filename)) {
+      await inventoryPath(target, `${relativePath}/${entry.name}`, files, directories, budget);
+    }
+  } else if (info.isFile()) {
+    recordInventoryEntry(files, { path: relativePath, ...await digestFile(filename, { includeSize: true }) }, budget);
+  } else {
+    throw failure("E_STORAGE_MIGRATION_SOURCE_INVALID", `Unsupported source entry: ${relativePath}`);
+  }
+}
+
+/** Shared bounded inventory for fixed roots selected by storage maintenance. */
+export async function inventoryStorageRoots(target, roots) {
+  const files = [];
+  const directories = [];
+  const budget = { bytes: 4096 };
+  for (const root of roots) await inventoryPath(target, root, files, directories, budget);
+  return { files: files.sort((a, b) => a.path.localeCompare(b.path)), directories: directories.sort() };
+}
+
+export async function inventoryLegacySourceLayout(target) {
+  return inventoryStorageRoots(target, SOURCE_ROOTS);
+}
+
+/** An archive is owned source storage: unexpected entries cannot be ignored. */
+export async function inventoryLegacyArchiveLayout(target) {
+  if (!(await infoIfPresent(target))) return { files: [], directories: [] };
+  const root = await assertSafePath(target, ".");
+  const files = [];
+  const directories = [];
+  const budget = { bytes: 4096 };
+  for await (const entry of await opendir(root)) await inventoryPath(target, entry.name, files, directories, budget);
+  const belongs = (name, directory) => SOURCE_ROOTS.some(source => name === source || name.startsWith(`${source}/`) || (directory && source.startsWith(`${name}/`)));
+  if (files.some(file => !belongs(file.path, false)) || directories.some(directory => !belongs(directory, true))) {
+    throw failure("E_STORAGE_MIGRATION_ARCHIVE_INVALID", "Archive contains entries outside the captured source roots");
+  }
+  return { files: files.sort((a, b) => a.path.localeCompare(b.path)), directories: directories.sort() };
+}
+
+export async function inventoryLegacySource(target) {
+  return (await inventoryLegacySourceLayout(target)).files;
+}
+
+export async function verifyLegacySourceCapture(target, destination) {
+  const retained = await assertSafePath(target, destination);
+  const filename = await assertSafePath(retained, "source-manifest.json");
+  const manifest = await readCaptureManifest(filename);
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)
+    || manifest.schemaVersion !== 2 || manifest.kind !== "LEGACY_SOURCE_CAPTURE"
+    || manifest.status !== "CAPTURED" || manifest.writersQuiesced !== true || !Array.isArray(manifest.files) || !Array.isArray(manifest.directories)) {
+    throw failure("E_STORAGE_MIGRATION_CAPTURE_INVALID", "Capture manifest is incomplete or unsupported");
+  }
+  const source = await assertSafePath(retained, "source");
+  if (JSON.stringify(await inventoryRetainedSource(source)) !== JSON.stringify({ files: manifest.files, directories: manifest.directories })) {
+    throw failure("E_STORAGE_MIGRATION_CAPTURE_INVALID", "Retained source membership or digests disagree with capture manifest");
+  }
+  return { path: retained, source, manifest };
+}
+
+async function assertLegacyIdle(target) {
+  if (await infoIfPresent(await assertSafePath(target, ".forgeloop/state.sqlite"))) {
+    throw failure("E_STORAGE_MIGRATION_SOURCE_INVALID", "Legacy capture cannot replace SQLite snapshot backup");
+  }
+  await assertNoLegacyOperationLocks(target, { code: "E_STORAGE_MIGRATION_BUSY" });
+  await assertSafePath(target, ".forgeloop/.txn");
+  if ((await findIncompleteTransactions(target)).length) {
+    throw failure("E_STORAGE_MIGRATION_SOURCE_INVALID", "Incomplete transactions require supported recovery before capture");
+  }
+}
+
+/** Retained source capture only. Operator quiescence is necessary, not inferred. */
+export async function captureLegacySource(target, destination, { writersQuiesced = false } = {}) {
+  if (writersQuiesced !== true) throw failure("E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED", "Stop and exclude all legacy writers before capture");
+  return withStorageMaintenance(target, () => captureExcludedLegacySource(target, destination));
+}
+
+async function captureExcludedLegacySource(target, destination) {
+  await assertLegacyIdle(target);
+  const retained = await assertSafePath(target, destination);
+  // Destination must not overlap any source root in either direction.
+  const normalized = path.relative(path.resolve(target), path.resolve(retained)).split(path.sep).join("/");
+  if (!normalized || SOURCE_ROOTS.some(root => normalized === root || normalized.startsWith(`${root}/`) || root.startsWith(`${normalized}/`))) {
+    throw failure("E_STORAGE_MIGRATION_DESTINATION_INVALID", "Capture destination overlaps retained operational sources");
+  }
+  const inventory = await inventoryLegacySourceLayout(target);
+  const { files, directories } = inventory;
+  await mkdir(path.dirname(retained), { recursive: true });
+  await mkdir(retained); // Exclusive: never replace or reuse an earlier capture.
+  const source = path.join(retained, "source");
+  await mkdir(source);
+  const manifestPath = path.join(retained, "source-manifest.json");
+  const manifest = { schemaVersion: 2, kind: "LEGACY_SOURCE_CAPTURE", status: "CAPTURING", writersQuiesced: true, files, directories };
+  const persist = () => writeFileAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  await persist();
+  try {
+    for (const directory of directories) await mkdir(await assertSafePath(source, directory), { recursive: true });
+    for (const file of files) {
+      await copyCapturedFile(target, source, file);
+    }
+    await assertLegacyIdle(target);
+    if (JSON.stringify(await inventoryLegacySourceLayout(target)) !== JSON.stringify(inventory)) {
+      throw failure("E_STORAGE_MIGRATION_SOURCE_CHANGED", "Source membership or bytes changed during capture");
+    }
+    await syncDirectories(source);
+    manifest.status = "CAPTURED";
+    await persist();
+    return { path: retained, source, manifest };
+  } catch (error) {
+    manifest.status = "FAILED";
+    manifest.error = { code: error.code ?? "E_STORAGE_MIGRATION_SOURCE_INVALID", message: error.message };
+    try { await persist(); } catch { /* Retain CAPTURING if failure metadata cannot be persisted. */ }
+    throw error;
+  }
+}
+
+async function readCaptureManifest(filename) {
+  try { return await readStorageMetadataJson(path.dirname(filename), path.basename(filename)); }
+  catch (error) {
+    if (["JSON_LIMIT_EXCEEDED", "E_STORAGE_METADATA_INVALID"].includes(error.code)) throw failure("E_STORAGE_MIGRATION_CAPTURE_INVALID", error.message);
+    throw error;
+  }
+}
+
+async function inventoryRetainedSource(source) {
+  let inventory;
+  try { inventory = await inventoryLegacyArchiveLayout(source); }
+  catch (error) {
+    if (error.code === "E_STORAGE_MIGRATION_ARCHIVE_INVALID") throw failure("E_STORAGE_MIGRATION_CAPTURE_INVALID", error.message);
+    throw error;
+  }
+  return { files: inventory.files, directories: inventory.directories.filter(name => SOURCE_ROOTS.some(root => name === root || name.startsWith(`${root}/`))) };
+}
+
+async function copyCapturedFile(target, source, file) {
+  const copied = await assertSafePath(source, file.path);
+  await mkdir(path.dirname(copied), { recursive: true });
+  await pipeline(createReadStream(await assertSafePath(target, file.path)), createWriteStream(copied, { flags: "wx", mode: 0o600 }));
+  const handle = await open(copied, "r+");
+  try { await handle.sync(); } finally { await handle.close(); }
+  const copiedDigest = await digestFile(copied, { includeSize: true });
+  if (copiedDigest.size !== file.size || copiedDigest.sha256 !== file.sha256) throw failure("E_STORAGE_MIGRATION_SOURCE_CHANGED", `Source bytes changed during recovery: ${file.path}`);
+}
+
+/** Complete recorded capture only while the original source inventory is unchanged. */
+export async function resumeLegacySourceCapture(target, destination, { writersQuiesced = false } = {}) {
+  if (writersQuiesced !== true) throw failure("E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED", "Capture recovery requires excluded writers");
+  await assertOwnedStorageMaintenance(target);
+  const retained = await assertSafePath(target, destination);
+  const manifestPath = await assertSafePath(retained, "source-manifest.json");
+  const manifest = await readCaptureManifest(manifestPath);
+  if (manifest?.status === "CAPTURED") return verifyLegacySourceCapture(target, destination);
+  if (manifest?.schemaVersion !== 2 || manifest.kind !== "LEGACY_SOURCE_CAPTURE" || !["CAPTURING", "FAILED"].includes(manifest.status)
+    || manifest.writersQuiesced !== true || !Array.isArray(manifest.files) || !Array.isArray(manifest.directories)) throw failure("E_STORAGE_MIGRATION_CAPTURE_INVALID", "Capture recovery requires a recorded source inventory");
+  await assertLegacyIdle(target);
+  if (await readStorageVersionMarker(target)) throw failure("E_STORAGE_MIGRATION_CAPTURE_INVALID", "Capture cannot resume after cutover begins");
+  for (const name of ["candidate-manifest.json", "candidate.sqlite", "publication"]) {
+    if (await infoIfPresent(await assertSafePath(retained, name))) throw failure("E_STORAGE_MIGRATION_CAPTURE_INVALID", "Capture cannot resume after candidate preparation begins");
+  }
+  const expected = { files: manifest.files, directories: manifest.directories };
+  if (JSON.stringify(await inventoryLegacySourceLayout(target)) !== JSON.stringify(expected)) throw failure("E_STORAGE_MIGRATION_SOURCE_CHANGED", "Original source inventory changed after capture began");
+  const source = await assertSafePath(retained, "source");
+  const partial = await inventoryRetainedSource(source);
+  const expectedPaths = new Set(manifest.files.map(file => file.path));
+  const expectedDirectories = new Set(manifest.directories);
+  if (partial.files.some(file => !expectedPaths.has(file.path)) || partial.directories.some(name => !expectedDirectories.has(name))) throw failure("E_STORAGE_MIGRATION_CAPTURE_INVALID", "Partial capture contains unrecorded entries");
+  const history = await assertSafePath(retained, "source-history");
+  await mkdir(history, { recursive: true });
+  const attempt = await assertSafePath(history, randomUUID());
+  await mkdir(attempt);
+  await writeFileAtomic(await assertSafePath(attempt, "source-manifest.json"), `${JSON.stringify(manifest)}\n`);
+  await syncDirectory(retained); await syncDirectory(history); await syncDirectory(attempt);
+  await mkdir(source, { recursive: true });
+  for (const name of manifest.directories) await mkdir(await assertSafePath(source, name), { recursive: true });
+  await completeCaptureFiles(target, source, attempt, manifest.files, partial.files);
+  await assertLegacyIdle(target);
+  if (JSON.stringify(await inventoryLegacySourceLayout(target)) !== JSON.stringify(expected)
+    || JSON.stringify(await inventoryRetainedSource(source)) !== JSON.stringify(expected)) throw failure("E_STORAGE_MIGRATION_SOURCE_CHANGED", "Source or capture changed during recovery");
+  await syncDirectories(source);
+  await assertOwnedStorageMaintenance(target);
+  delete manifest.error;
+  manifest.status = "CAPTURED";
+  await writeFileAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return verifyLegacySourceCapture(target, destination);
+}
+
+async function completeCaptureFiles(target, source, attempt, files, partialFiles) {
+  const current = new Map(partialFiles.map(file => [file.path, file]));
+  for (const file of files) {
+    const previous = current.get(file.path);
+    if (previous?.size === file.size && previous.sha256 === file.sha256) continue;
+    if (previous) {
+      await assertOwnedStorageMaintenance(target);
+      const forensic = await assertSafePath(attempt, `partial/${file.path}`);
+      await mkdir(path.dirname(forensic), { recursive: true });
+      await syncDirectories(attempt);
+      await rename(await assertSafePath(source, file.path), forensic);
+      await syncDirectory(path.dirname(forensic));
+      await syncDirectory(path.dirname(await assertSafePath(source, file.path)));
+    }
+    await copyCapturedFile(target, source, file);
+  }
+}

package/src/storage/migration-terminal.js

@@ -0,0 +1,39 @@
+import { assertSafePath } from "../core/filesystem.js";
+import { getPackageRoot } from "../core/templates.js";
+import { assertOwnedStorageMaintenance } from "./maintenance.js";
+import { verifyMigrationPublicationStage } from "./migration-publication.js";
+import { readStorageVersionMarker } from "./storage-marker.js";
+import { checkStorageIntegrity, openStorageDatabase, readStorageMeta } from "./connection.js";
+import { withStorageSnapshot } from "./snapshot.js";
+import { validateMigrationDatabase } from "./migration-validation.js";
+import { iterateAttachmentReferences } from "./attachment-references.js";
+import { verifyAttachmentFile } from "./attachment-files.js";
+import { assertSnapshotContinuity } from "./snapshot-continuity.js";
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_MIGRATION_TERMINAL_INVALID" }); }
+
+/** Verify current state after publication; never write or restore an old snapshot. */
+export async function verifyPublishedMigration(target, destination, { writersQuiesced = false, packageRoot = getPackageRoot() } = {}) {
+  if (writersQuiesced !== true) throw invalid("Terminal verification requires excluded writers");
+  await assertOwnedStorageMaintenance(target);
+  const staged = await verifyMigrationPublicationStage(target, destination, { packageRoot, sourcePartition: true, allowPublished: true });
+  if (staged.journal.phase !== "PUBLISHED") throw invalid("Publication journal is not terminal");
+  const marker = await readStorageVersionMarker(target);
+  if (!marker || marker.phase !== "ACTIVE" || marker.operationId !== staged.journal.operationId
+    || marker.sourceInventoryFingerprint !== staged.journal.sourceInventoryFingerprint) throw invalid("Active marker does not match terminal publication");
+  for (const suffix of ["", "-wal", "-shm"]) await assertSafePath(target, `.forgeloop/state.sqlite${suffix}`);
+  const db = openStorageDatabase(await assertSafePath(target, ".forgeloop/state.sqlite"), { readOnly: true });
+  let original;
+  try {
+    original = openStorageDatabase(await assertSafePath(staged.bundle, "state.sqlite"), { readOnly: true });
+    return await withStorageSnapshot(db, async current => {
+      if (!checkStorageIntegrity(current).ok || readStorageMeta(current).schema_version !== marker.databaseSchemaVersion) throw invalid("Current storage integrity or version differs");
+      assertSnapshotContinuity(original, current, invalid);
+      const validation = await validateMigrationDatabase(current, { target, packageRoot });
+      let attachments = 0;
+      for (const reference of iterateAttachmentReferences(current)) { await verifyAttachmentFile(target, reference); attachments += 1; }
+      await assertOwnedStorageMaintenance(target);
+      return { phase: "PUBLISHED", operationId: marker.operationId, taskCount: validation.tasks.length, attachments, currentStateVerified: true, restored: false };
+    });
+  } finally { try { original?.close(); } finally { db.close(); } }
+}

package/src/storage/migration-validation.js

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { assertSchema, readSchema } from "../core/schema-validation.js";
+import { assertJsonBytes, assertJsonLimits } from "../core/json-safety.js";
+import { validateTaskDescriptor } from "../core/task-descriptor.js";
+import { validateContract } from "../core/contract.js";
+import { validateCodeManifest } from "../core/code-manifest.js";
+import { validateActionArtifact, validateApprovalArtifact } from "../core/action-model.js";
+import { validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
+import { readWorkState } from "../core/work-state.js";
+import { validateCheckExecutionProvenance } from "../core/completion-artifacts.js";
+import { withOperationalStore } from "./unit-of-work.js";
+
+const ARTIFACT_SCHEMAS = Object.freeze({
+  contract: "current-contract", route: "routing-result", preflight: "preflight",
+  continuity: "continuity", receipt: "execution-receipt", policySnapshot: "policy-snapshot",
+  recovery: "task-recovery", workspaceBinding: "workspace-binding", responsibility: "responsibility",
+  verificationScope: "verification-scope", usage: "usage", testUtility: "test-utility",
+  gate: "gate", handoff: "handoff-envelope", decision: "semantic-decision",
+  evaluation: "trajectory-evaluation", structuralQuality: "structural-quality",
+});
+
+function artifactSchema(row) {
+  if (row.kind !== "attestation") return ARTIFACT_SCHEMAS[row.kind];
+  const name = path.posix.basename(row.artifact_id);
+  return name === "code-manifest" ? "code-manifest" : name === "statement" ? "in-toto-statement" : null;
+}
+
+/** Validate imported payloads with their existing protocol schemas and rules. */
+export async function validateMigrationDatabase(db, { target, packageRoot }) {
+  const schemas = new Map();
+  const validate = async (text, name, label, taskId = null) => {
+    if (!name) throw Object.assign(new Error(`Unmapped operational artifact: ${label}`), { code: "E_STORAGE_MIGRATION_UNMAPPED_SOURCE" });
+    assertJsonBytes(text, label);
+    const value = JSON.parse(text);
+    assertJsonLimits(value, label);
+    if (!schemas.has(name)) schemas.set(name, await readSchema(name, packageRoot));
+    assertSchema(value, schemas.get(name), label);
+    if (taskId && value.taskId !== undefined && value.taskId !== taskId) {
+      throw Object.assign(new Error(`Artifact identity differs from its task: ${label}`), { code: "E_STORAGE_PAYLOAD_MISMATCH" });
+    }
+    return value;
+  };
+  for (const row of db.prepare("SELECT task_id, descriptor_json FROM tasks ORDER BY task_id").iterate()) {
+    await validateTaskDescriptor(await validate(row.descriptor_json, "task-descriptor", row.task_id, row.task_id), packageRoot);
+  }
+  for (const row of db.prepare("SELECT task_id, kind, artifact_id, payload_json FROM task_artifacts ORDER BY task_id, kind, artifact_id").iterate()) {
+    const name = artifactSchema(row);
+    const value = await validate(row.payload_json, name, `${row.task_id}/${row.kind}/${row.artifact_id}`, row.task_id);
+    if (row.kind === "contract") await validateContract(value, packageRoot);
+    if (name === "code-manifest") await validateCodeManifest(value, packageRoot);
+  }
+  for (const [table, name, validator] of [["actions", "action", validateActionArtifact], ["approvals", "approval", validateApprovalArtifact], ["executions", "execution", null]]) {
+    for (const row of db.prepare(`SELECT task_id, payload_json FROM ${table} ORDER BY task_id, payload_json`).iterate()) {
+      const value = await validate(row.payload_json, name, table, row.task_id);
+      validator?.(value);
+    }
+  }
+  return withOperationalStore({ db, target }, async () => {
+    const tasks = [];
+    for (const row of db.prepare("SELECT task_id FROM tasks ORDER BY task_id").iterate()) {
+      const state = await readWorkState(target, { taskId: row.task_id, packageRoot });
+      for (const check of state?.checks ?? []) {
+        if (check.provenance === "FORGELOOP_EXECUTED") {
+          await validateCheckExecutionProvenance(check, { target, packageRoot, taskId: row.task_id });
+        }
+      }
+      const ledger = await validateEventLedger(target, packageRoot, { taskId: row.task_id });
+      const errors = [...ledger.errors, ...(state ? validateStateLedgerCoherence(state, ledger.events) : [])];
+      if (errors.length) throw Object.assign(new Error(`Imported task failed domain validation: ${row.task_id}`), { code: "E_STORAGE_MIGRATION_VALIDATION_FAILED", errors });
+      const head = ledger.events.at(-1);
+      tasks.push({ taskId: row.task_id, phase: state?.phase ?? null, revision: state?.revision ?? null, events: ledger.events.length, head: head ? { seq: head.seq, hash: head.hash } : null });
+    }
+    return { tasks, schemas: [...schemas.keys()].sort() };
+  });
+}

package/src/storage/migration.js

@@ -0,0 +1,43 @@
+import { resumeStorageMaintenance, withStorageMaintenance } from "./maintenance.js";
+import { resumeLegacySourceCapture } from "./migration-source.js";
+import { prepareMigrationCandidate, resumeMigrationCandidate } from "./migration-candidate.js";
+import { stageMigrationPublication } from "./migration-publication.js";
+import { archiveMigrationSources } from "./migration-archive.js";
+import { activateArchivedMigration } from "./migration-activate.js";
+import { verifyPublishedMigration } from "./migration-terminal.js";
+
+/** Initial cutover only. Failed attempts retain exclusion and evidence for recovery. */
+export async function migrateProjectStorage(target, { destination, writersQuiesced = false, packageRoot } = {}) {
+  if (typeof destination !== "string" || !destination || writersQuiesced !== true) {
+    throw Object.assign(new Error("storage-migrate requires --destination and explicit --writers-quiesced"), { code: "E_CLI_INVOCATION_INVALID" });
+  }
+  return withStorageMaintenance(target, async () => {
+    const options = { writersQuiesced, packageRoot };
+    await prepareMigrationCandidate(target, { destination, ...options });
+    await stageMigrationPublication(target, destination, options);
+    await archiveMigrationSources(target, destination, options);
+    const activated = await activateArchivedMigration(target, destination, options);
+    const verified = await verifyPublishedMigration(target, destination, options);
+    return { ...verified, path: activated.path, destination };
+  }, { retainOnError: true });
+}
+
+
+/** Resume retained publication, rebuilding only verified unpublished staging. */
+export async function resumeProjectStorageMigration(target, { destination, expectedOwnerId, writersQuiesced = false, acknowledgeUnboundHandoff = false, packageRoot } = {}) {
+  if (typeof destination !== "string" || !destination) {
+    throw Object.assign(new Error("Migration resume requires the retained destination"), { code: "E_CLI_INVOCATION_INVALID" });
+  }
+  return resumeStorageMaintenance(target, { expectedOwnerId, writersQuiesced, acknowledgeUnboundHandoff }, async () => {
+    const options = { writersQuiesced, packageRoot };
+    await resumeLegacySourceCapture(target, destination, options);
+    await resumeMigrationCandidate(target, destination, options);
+    const { resumeMigrationPublicationStage } = await import("./migration-publication.js");
+    const staged = await resumeMigrationPublicationStage(target, destination, options);
+    if (staged.journal.phase !== "PUBLISHED") {
+      if (["STAGED", "ARCHIVING"].includes(staged.journal.phase)) await archiveMigrationSources(target, destination, options);
+      await activateArchivedMigration(target, destination, options);
+    }
+    return { ...await verifyPublishedMigration(target, destination, options), destination };
+  });
+}

package/src/storage/operational-attachments.js

@@ -0,0 +1,49 @@
+import { needsExistingProjectScope, withExistingProjectScope } from "./existing-project-scope.js";
+import { getOperationalStore } from "./operational-context.js";
+import { validateAttachmentReference } from "./attachment-binding.js";
+import { withVerifiedAttachmentFile } from "./attachment-files.js";
+import { ensureWithin } from "../core/filesystem.js";
+import path from "node:path";
+
+function isObjectAddress(target, relativePath) {
+  const portable = relativePath.replaceAll("\\", "/");
+  const normalizeNames = value => value.replaceAll("\\", "/").split("/")
+    .map(segment => segment.replace(/[. ]+$/, "").split(":")[0].toLowerCase()).join("/");
+  const prefix = ".forgeloop/attachments/objects/";
+  // Keep lexical object traversal protected, and detect absolute/dot aliases.
+  // Classification never rewrites the immutable SQL path binding.
+  return normalizeNames(portable).startsWith(prefix)
+    || normalizeNames(path.relative(target, path.resolve(target, portable))).startsWith(prefix);
+}
+
+/** Explicit non-object paths retain legacy handling until their migration. */
+export async function withOperationalAttachmentFile(target, relativePath, taskId, callback) {
+  if (await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => withOperationalAttachmentFile(target, relativePath, taskId, callback), { readOnly: true });
+  }
+  const store = getOperationalStore(target);
+  if (!store || !isObjectAddress(target, relativePath)) return callback(ensureWithin(target, relativePath));
+  const invalid = message => Object.assign(new Error(message), { code: "E_STORAGE_ATTACHMENT_INVALID" });
+  if (store.db.isTransaction) throw invalid("External attachment consumption cannot run inside the native writer");
+  const row = store.observe(`attachment-path:${JSON.stringify([taskId, relativePath])}`, () => store.db.prepare(
+    "SELECT * FROM attachment_references WHERE task_id = ? AND path = ? ORDER BY reference_id LIMIT 1",
+  ).get(taskId, relativePath) ?? null);
+  let reference = row ? validateAttachmentReference({ taskId: row.task_id, referenceId: row.reference_id, path: row.path, size: row.size, sha256: row.sha256 }) : null;
+  if (!reference) {
+    for (const value of store.attachments.values()) {
+      if (value.taskId === taskId && value.path === relativePath) { reference = value; break; }
+    }
+  }
+  if (!reference) throw invalid("Attachment path has no binding for this task");
+  let consumerStarted = false;
+  try {
+    return await withVerifiedAttachmentFile(target, validateAttachmentReference(reference), filename => {
+      consumerStarted = true;
+      return callback(filename);
+    });
+  }
+  catch (error) {
+    if (!consumerStarted && ["ENOENT", "ENOTDIR", "ELOOP"].includes(error.code)) throw invalid("Referenced attachment bytes are missing or unsafe");
+    throw error;
+  }
+}

package/src/storage/operational-context.js

@@ -0,0 +1,50 @@
+import { realpathSync } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
+
+// Per-command storage scope selected at the project boundary. Actor command
+// input cannot select a different backend or connection.
+export const operationalContext = new AsyncLocalStorage();
+
+export function assertCanonicalPersistence(persistence) {
+  if (persistence !== null && persistence !== undefined) {
+    throw Object.assign(new Error("Temporary command persistence capabilities are retired; use canonical project storage"), { code: "E_STORAGE_OPERATION_UNSUPPORTED" });
+  }
+}
+
+export function getOperationalStore(target) {
+  const store = operationalContext.getStore() ?? null;
+  if (store?.active === false) {
+    const error = new Error("Operational preparation scope has already closed");
+    error.code = "E_STORAGE_TRANSACTION_EXPIRED";
+    throw error;
+  }
+  let sameProject = !store || store.target === path.resolve(target);
+  if (!sameProject) {
+    try { sameProject = realpathSync(store.target) === realpathSync(target); }
+    catch { sameProject = false; }
+  }
+  if (!sameProject) {
+    const error = new Error("Operational store belongs to a different project");
+    error.code = "E_TASK_CONTEXT_MISMATCH";
+    throw error;
+  }
+  return store;
+}
+
+export function readOperationalText(target, relativePath) {
+  const store = getOperationalStore(target);
+  if (!store || !store.recognizes(relativePath)) return { selected: false, text: null };
+  return { selected: true, text: store.readText(relativePath) };
+}
+
+export function operationalArtifactExists(target, relativePath) {
+  const store = getOperationalStore(target);
+  if (!store || !store.recognizes(relativePath)) return null;
+  return typeof store.artifactExists === "function" ? store.artifactExists(relativePath) : store.readText(relativePath) !== null;
+}
+
+export function listOperationalArtifactNames(target, taskId, collection) {
+  const store = getOperationalStore(target);
+  return store ? store.listArtifactNames(taskId, collection) : null;
+}

package/src/storage/project-backup.js

@@ -0,0 +1,98 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { digestFile } from "./file-durability.js";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { JSON_LIMITS } from "../core/json-safety.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { backupStorageDatabase } from "./backup.js";
+import { checkStorageIntegrity, openStorageDatabase } from "./connection.js";
+import { iterateAttachmentReferences } from "./attachment-references.js";
+import { publishAttachmentFile, verifyAttachmentFile } from "./attachment-files.js";
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_BACKUP_INVALID" }); }
+
+async function copyAttachment(source, destination, reference) {
+  await verifyAttachmentFile(source, reference);
+  const copied = await publishAttachmentFile(destination, createReadStream(await assertSafePath(source, reference.path)));
+  if (copied.size !== reference.size || copied.sha256 !== reference.sha256) throw invalid("Attachment changed during backup copy");
+}
+
+/** Retained database snapshot plus all canonically referenced attachment bytes. */
+export async function backupProjectStorage(db, target, destination) {
+  if (db.isTransaction) throw invalid("Project backup requires committed storage state");
+  const directory = path.resolve(destination);
+  await assertSafePath(path.dirname(directory), path.basename(directory));
+  await mkdir(directory); // Never overwrite a retained or interrupted backup.
+  const manifestPath = await assertSafePath(directory, "backup-manifest.json");
+  const manifest = { schemaVersion: 1, kind: "SQLITE_WITH_REFERENCED_ATTACHMENTS", status: "PREPARING" };
+  const persist = () => writeFileAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  await persist();
+  let snapshot;
+  try {
+    const databasePath = await assertSafePath(directory, "state.sqlite");
+    await backupStorageDatabase(db, databasePath);
+    snapshot = openStorageDatabase(databasePath, { readOnly: true });
+    let references = 0;
+    async function* inventory() {
+      for (const reference of iterateAttachmentReferences(snapshot)) {
+        await copyAttachment(target, directory, reference);
+        references += 1;
+        yield `${JSON.stringify(reference)}\n`;
+      }
+    }
+    const inventoryPath = await assertSafePath(directory, "attachments.ndjson");
+    await writeFileAtomic(inventoryPath, inventory());
+    snapshot.close(); snapshot = null;
+    Object.assign(manifest, { status: "READY", databaseSha256: await digestFile(databasePath), inventorySha256: await digestFile(inventoryPath), references });
+    await persist();
+    return { path: directory, kind: manifest.kind, attachmentsIncluded: true, references };
+  } catch (error) {
+    manifest.status = "FAILED";
+    manifest.error = { code: error.code ?? "E_STORAGE_BACKUP_INVALID", message: error.message };
+    try { await persist(); } catch { /* PREPARING is also refused during restore. */ }
+    throw error;
+  } finally { snapshot?.close(); }
+}
+
+export async function withVerifiedProjectStorageBackup(directory, callback) {
+  const root = path.resolve(directory);
+  const manifest = await readStorageMetadataJson(root, "backup-manifest.json", { limits: JSON_LIMITS });
+  if (!manifest || manifest.schemaVersion !== 1 || manifest.kind !== "SQLITE_WITH_REFERENCED_ATTACHMENTS" || manifest.status !== "READY"
+    || !Number.isSafeInteger(manifest.references) || manifest.references < 0) throw invalid("Backup is incomplete or unsupported");
+  const filename = await assertSafePath(root, "state.sqlite");
+  for (const suffix of ["-wal", "-shm"]) {
+    const sidecar = await assertSafePath(root, `state.sqlite${suffix}`);
+    try { if (suffix === "-wal" && (await lstat(sidecar)).size !== 0) throw invalid("Backup requires unshipped WAL contents"); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  if (await digestFile(filename) !== manifest.databaseSha256) throw invalid("Backup database digest mismatch");
+  const db = openStorageDatabase(filename, { readOnly: true });
+  try {
+    if (!checkStorageIntegrity(db).ok) throw invalid("Backup database failed integrity");
+    let references = 0;
+    const inventory = createHash("sha256");
+    for (const reference of iterateAttachmentReferences(db)) {
+      await verifyAttachmentFile(root, reference);
+      references += 1;
+      inventory.update(`${JSON.stringify(reference)}\n`);
+    }
+    if (references !== manifest.references || inventory.digest("hex") !== manifest.inventorySha256
+      || await digestFile(await assertSafePath(root, "attachments.ndjson")) !== manifest.inventorySha256) throw invalid("Backup inventory disagrees with canonical references");
+    return await callback({ db, root, manifest });
+  } finally { db.close(); }
+}
+
+export async function verifyProjectStorageBackup(directory) {
+  return withVerifiedProjectStorageBackup(directory, ({ root, manifest }) => ({ path: root, references: manifest.references, valid: true }));
+}
+
+/** Restore only into a fresh directory; never replace a running project. */
+export async function restoreProjectStorageBackup(source, destination) {
+  return withVerifiedProjectStorageBackup(source, async ({ db, root }) => {
+    const restored = await backupProjectStorage(db, root, destination);
+    await verifyProjectStorageBackup(destination);
+    return { ...restored, restored: true, source: root };
+  });
+}

package/src/storage/project-bootstrap.js

@@ -0,0 +1,24 @@
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { assertSafePath } from "../core/filesystem.js";
+import { openStorageDatabase } from "./connection.js";
+import { backupProjectStorage } from "./project-backup.js";
+import { assertFreshOperationalState, restoreProjectStorageToFreshProject } from "./project-restore.js";
+import { assertStorageNodeVersion } from "./runtime.js";
+
+/** Publish an empty store through the same journaled path as a verified restore.
+ * Retain the seed: a PREPARING restore needs its independent source on recovery.
+ * This primitive requires writer exclusion from its caller, just like restore.
+ */
+export async function bootstrapProjectStorage(target, { writersQuiesced = false, packageRoot } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Exclude all writers before storage bootstrap"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  assertStorageNodeVersion();
+  await assertFreshOperationalState(target);
+  const root = await assertSafePath(target, `.forgeloop/storage-bootstrap/${randomUUID()}`);
+  await mkdir(root, { recursive: true });
+  const db = openStorageDatabase(await assertSafePath(root, "seed.sqlite"));
+  const source = await assertSafePath(root, "snapshot");
+  try { await backupProjectStorage(db, root, source); }
+  finally { db.close(); }
+  return restoreProjectStorageToFreshProject(source, target, { writersQuiesced, packageRoot });
+}