@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.4

package/src/storage/restore-preparation.js

@@ -0,0 +1,84 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, open, rename, unlink } from "node:fs/promises";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { JSON_LIMITS } from "../core/json-safety.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { backupProjectStorage, withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { assertOwnedStorageMaintenance } from "./maintenance.js";
+import { restorePathExists } from "./restore-layout.js";
+
+const invalid = message => Object.assign(new Error(message), { code: "E_STORAGE_RESTORE_INVALID" });
+
+async function retainCompletedIntent(root, journal) {
+  const directory = await assertSafePath(root, "snapshot-intents");
+  await mkdir(directory, { recursive: true });
+  const relative = `snapshot-intents/${journal.rebuild.historyId}.json`;
+  const filename = await assertSafePath(root, relative);
+  const record = { schemaVersion: 1, kind: "RESTORE_REBUILD_INTENT", operationId: journal.operationId,
+    sourceFingerprint: journal.sourceFingerprint, intent: journal.rebuild };
+  const temporary = await assertSafePath(root, `snapshot-intents/.publishing-${randomUUID()}.json`);
+  await writeFileAtomic(temporary, `${JSON.stringify(record, null, 2)}\n`);
+  try {
+    try { await link(temporary, filename); }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const existing = await readStorageMetadataJson(root, relative, { limits: JSON_LIMITS });
+      if (canonicalFingerprint(existing) !== canonicalFingerprint(record)) throw invalid("Retained restore intent differs from the completed cycle");
+    }
+  } finally { await unlink(temporary); }
+  try {
+    const handle = await open(directory, "r");
+    try { await handle.sync(); } finally { await handle.close(); }
+  } catch (error) { if (!["EINVAL", "EPERM", "EISDIR", "ENOTSUP", "UNKNOWN"].includes(error.code)) throw error; }
+}
+
+/** Retain an interrupted initial snapshot before rebuilding from bound source. */
+export async function ensurePreparedRestoreSnapshot(target, root, journal, { journalFilename = "restore-journal.json" } = {}) {
+  if (!["restore-journal.json", "replacement-intent.json"].includes(journalFilename)) throw invalid("Unsupported snapshot preparation journal");
+  return withVerifiedProjectStorageBackup(journal.source, async source => {
+    if (canonicalFingerprint(source.manifest) !== journal.sourceFingerprint) throw invalid("Restore source differs from its recorded preparation");
+    const snapshot = await assertSafePath(root, "snapshot");
+    const journalPath = await assertSafePath(root, journalFilename);
+    const persist = async () => {
+      await assertOwnedStorageMaintenance(target);
+      return writeFileAtomic(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
+    };
+    const manifest = await restorePathExists(root, "snapshot")
+      ? await readStorageMetadataJson(snapshot, "backup-manifest.json", { limits: JSON_LIMITS, optional: true }) : null;
+    if (manifest?.status === "READY" && !journal.rebuild) return;
+    if (!journal.rebuild) {
+      if (manifest && !["PREPARING", "FAILED"].includes(manifest.status)) throw invalid("Unrecognized incomplete restore snapshot");
+      journal.rebuild = { historyId: randomUUID(), retainSnapshot: await restorePathExists(root, "snapshot"), phase: "RETAINING" };
+      await persist();
+    }
+    const intent = journal.rebuild;
+    const history = await assertSafePath(root, `snapshot-history/${intent.historyId}`);
+    if (intent.phase === "RETAINING") {
+      await assertOwnedStorageMaintenance(target);
+      const present = await restorePathExists(root, "snapshot");
+      const retained = await restorePathExists(root, `snapshot-history/${intent.historyId}`);
+      if (intent.retainSnapshot) {
+        if (present === retained) throw invalid("Restore snapshot retention has ambiguous membership");
+        if (present) { await mkdir(await assertSafePath(root, "snapshot-history"), { recursive: true }); await rename(snapshot, history); }
+      } else if (present || retained) throw invalid("Restore snapshot allocation intent disagrees with retained state");
+      intent.phase = "RETAINED";
+      await persist();
+    }
+    if (intent.retainSnapshot && !await restorePathExists(root, `snapshot-history/${intent.historyId}`)) throw invalid("Restore snapshot history is missing");
+    if (await restorePathExists(root, "snapshot")) {
+      const rebuilt = await readStorageMetadataJson(snapshot, "backup-manifest.json", { limits: JSON_LIMITS, optional: true });
+      if (rebuilt?.status !== "READY") {
+        if (rebuilt && !["PREPARING", "FAILED"].includes(rebuilt.status)) throw invalid("Unrecognized interrupted replacement snapshot");
+        await assertOwnedStorageMaintenance(target);
+        await retainCompletedIntent(root, journal);
+        journal.rebuild = { historyId: randomUUID(), retainSnapshot: true, phase: "RETAINING" };
+        await persist();
+        return ensurePreparedRestoreSnapshot(target, root, journal, { journalFilename });
+      }
+      return;
+    }
+    await assertOwnedStorageMaintenance(target);
+    await backupProjectStorage(source.db, source.root, snapshot);
+  });
+}

package/src/storage/restore-replacement-archive.js

@@ -0,0 +1,162 @@
+import { mkdir, opendir, rename } from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./file-durability.js";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { getPackageRoot } from "../core/templates.js";
+import { MAINTENANCE_OWNER_ID, readMaintenanceOwner } from "./maintenance-owner.js";
+import { assertOwnedStorageMaintenance, retainStorageMaintenance, assertStorageMaintenanceOwnerContinuity } from "./maintenance.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { LEGACY_SOURCE_ROOTS, inventoryStorageRoots } from "./migration-source.js";
+import { withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { validateMigrationDatabase } from "./migration-validation.js";
+import { restorePathExists } from "./restore-layout.js";
+import { REPLACEMENT_ACTIVE_ROOTS, assertReplacementConnectionsClosed, assertActiveStorageReplacementUnchanged, verifyPreparedActiveStorageReplacement } from "./restore-replacement.js";
+import { adoptPreparedReplacementOwner } from "./restore-replacement-owner.js";
+import { inventoryPresent, subsetInventory } from "./migration-source-partition.js";
+
+const invalid = message => Object.assign(new Error(message), { code: "E_STORAGE_RESTORE_INVALID" });
+const hash = value => typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+const belongs = (name, root) => name === root || name.startsWith(`${root}/`);
+
+async function incomingSnapshot(target, operationId, packageRoot) {
+  const root = await assertSafePath(target, `.forgeloop/storage-restores/${operationId}/snapshot`);
+  return withVerifiedProjectStorageBackup(root, async ({ db, manifest }) => {
+    await validateMigrationDatabase(db, { target: root, packageRoot, archivedExecutions: true });
+    return { root, fingerprint: canonicalFingerprint(manifest) };
+  });
+}
+
+async function inventoryArchive(archive) {
+  if (!await restorePathExists(path.dirname(archive), path.basename(archive))) return { files: [], directories: [] };
+  for await (const entry of await opendir(archive)) {
+    if (entry.name !== ".forgeloop" || !entry.isDirectory()) throw invalid("Replacement archive contains unexpected root membership");
+  }
+  const inventory = await inventoryStorageRoots(archive, [".forgeloop"]);
+  if (inventory.files.some(file => !REPLACEMENT_ACTIVE_ROOTS.some(root => belongs(file.path, root)))
+    || inventory.directories.some(name => name !== ".forgeloop" && !belongs(name, ".forgeloop/attachments"))) throw invalid("Replacement archive contains unexpected retained membership");
+  return inventory;
+}
+
+/** Reconcile location from actual membership/digests, not progress annotations. */
+export async function inspectActiveStorageReplacementPartition(target, operationId) {
+  const retained = await verifyPreparedActiveStorageReplacement(target, operationId);
+  await assertReplacementConnectionsClosed(target);
+  for (const relative of LEGACY_SOURCE_ROOTS) {
+    if (relative !== ".forgeloop/attachments" && await restorePathExists(target, relative)) throw invalid(`Replacement archival refuses mixed legacy state: ${relative}`);
+  }
+  const active = await inventoryStorageRoots(target, REPLACEMENT_ACTIVE_ROOTS);
+  const archive = await assertSafePath(retained.root, "archive");
+  const archived = await inventoryArchive(archive);
+  const roots = [];
+  for (const root of REPLACEMENT_ACTIVE_ROOTS) {
+    const original = subsetInventory(retained.manifest.inventory, root);
+    const current = subsetInventory(active, root);
+    const historical = subsetInventory(archived, root);
+    if (inventoryPresent(current) && inventoryPresent(historical)) throw invalid(`Outgoing root exists in both active and archived locations: ${root}`);
+    if (canonicalFingerprint(inventoryPresent(current) ? current : historical) !== canonicalFingerprint(original)) throw invalid(`Outgoing replacement membership or bytes differ: ${root}`);
+    roots.push({ path: root, location: inventoryPresent(current) ? "ACTIVE" : inventoryPresent(historical) ? "ARCHIVED" : "ABSENT" });
+  }
+  if (!retained.manifest.inventory.files.some(file => file.path === ".forgeloop/state.sqlite")
+    || !retained.manifest.inventory.files.some(file => file.path === ".forgeloop/storage-version.json")) throw invalid("Outgoing replacement inventory omits database or marker authority");
+  return { ...retained, archive, roots };
+}
+
+async function readArchiveJournal(retained, operationId) {
+  const journal = await readStorageMetadataJson(retained.root, "archive-journal.json");
+  if (!journal || journal.schemaVersion !== 1 || journal.kind !== "ACTIVE_PROJECT_REPLACEMENT_ARCHIVE" || journal.operationId !== operationId
+    || !MAINTENANCE_OWNER_ID.test(journal.ownerId ?? "") || (journal.resumedFrom !== undefined && !MAINTENANCE_OWNER_ID.test(journal.resumedFrom))
+    || !["ARCHIVING", "ARCHIVED"].includes(journal.phase)
+    || !hash(journal.outgoingFingerprint) || !hash(journal.incomingFingerprint)
+    || journal.outgoingFingerprint !== canonicalFingerprint(retained.manifest)) throw invalid("Replacement archive journal is incomplete or differs from outgoing evidence");
+  return journal;
+}
+
+/** Verify immutable outgoing evidence after incoming roots occupy the active namespace.
+ * Callers must supply the fingerprints persisted in their publication intent.
+ */
+export async function verifyRetainedStorageReplacementArchive(target, operationId, { outgoingFingerprint, incomingFingerprint, packageRoot = getPackageRoot() } = {}) {
+  if (!hash(outgoingFingerprint) || !hash(incomingFingerprint)) throw invalid("Retained archival verification requires explicit publication bindings");
+  const retained = await verifyPreparedActiveStorageReplacement(target, operationId);
+  const journal = await readArchiveJournal(retained, operationId);
+  if (journal.phase !== "ARCHIVED" || journal.outgoingFingerprint !== outgoingFingerprint || journal.incomingFingerprint !== incomingFingerprint) throw invalid("Retained archive differs from publication intent");
+  const archive = await assertSafePath(retained.root, "archive");
+  const inventory = await inventoryArchive(archive);
+  for (const root of REPLACEMENT_ACTIVE_ROOTS) {
+    if (canonicalFingerprint(subsetInventory(inventory, root)) !== canonicalFingerprint(subsetInventory(retained.manifest.inventory, root))) throw invalid(`Retained outgoing membership or bytes differ: ${root}`);
+  }
+  const incoming = await incomingSnapshot(target, operationId, packageRoot);
+  if (incoming.fingerprint !== incomingFingerprint) throw invalid("Incoming replacement snapshot differs from publication intent");
+  return { ...retained, archive, journal, incomingSnapshot: incoming.root, archived: true, replaced: false };
+}
+
+export async function verifyActiveStorageReplacementArchive(target, operationId, { packageRoot = getPackageRoot() } = {}) {
+  const partition = await inspectActiveStorageReplacementPartition(target, operationId);
+  const journal = await readArchiveJournal(partition, operationId);
+  const incoming = await incomingSnapshot(target, operationId, packageRoot);
+  if (incoming.fingerprint !== journal.incomingFingerprint) throw invalid("Incoming replacement snapshot changed after archival intent");
+  if (journal.phase === "ARCHIVED" && partition.roots.some(root => root.location === "ACTIVE")) throw invalid("Replacement journal claims archival before active roots were retained");
+  return { ...partition, journal, incomingSnapshot: incoming.root, archived: journal.phase === "ARCHIVED", replaced: false };
+}
+
+async function ownerAdoption(target, currentOwnerId, recordedOwnerId, expectedOwnerId) {
+  if (currentOwnerId === recordedOwnerId) return {};
+  const owner = (await readMaintenanceOwner(target)).value;
+  if (owner.resumedFrom !== expectedOwnerId) throw invalid("Replacement archival requires exact recorded owner adoption");
+  await assertStorageMaintenanceOwnerContinuity(target, { expectedOwnerId: currentOwnerId, recordedOwnerId });
+  return { resumedFrom: recordedOwnerId };
+}
+
+/** Archive only after both outgoing authority and incoming snapshot are verified. */
+export async function archiveActiveStorageReplacement(target, operationId, { packageRoot = getPackageRoot(), expectedOwnerId = null } = {}) {
+  const ownerId = await assertOwnedStorageMaintenance(target);
+  await retainStorageMaintenance(target);
+  const retained = await verifyPreparedActiveStorageReplacement(target, operationId);
+  const filename = await assertSafePath(retained.root, "archive-journal.json");
+  let journal = await readStorageMetadataJson(retained.root, "archive-journal.json", { optional: true });
+  if (!journal) {
+    await adoptPreparedReplacementOwner(target, operationId, { expectedOwnerId });
+    await assertActiveStorageReplacementUnchanged(target, operationId);
+    const incoming = await incomingSnapshot(target, operationId, packageRoot);
+    if (await restorePathExists(retained.root, "archive")) throw invalid("Unrecorded replacement archive requires reconciliation");
+    journal = { schemaVersion: 1, kind: "ACTIVE_PROJECT_REPLACEMENT_ARCHIVE", operationId, ownerId, phase: "ARCHIVING",
+      outgoingFingerprint: canonicalFingerprint(retained.manifest), incomingFingerprint: incoming.fingerprint };
+    await assertOwnedStorageMaintenance(target);
+    await writeFileAtomic(filename, `${JSON.stringify(journal, null, 2)}\n`);
+  } else {
+    journal = await readArchiveJournal(retained, operationId);
+    if (journal.ownerId !== ownerId) {
+      const adoption = await ownerAdoption(target, ownerId, journal.ownerId, expectedOwnerId);
+      journal = { ...journal, ownerId, ...adoption };
+      await assertOwnedStorageMaintenance(target);
+      await writeFileAtomic(filename, `${JSON.stringify(journal, null, 2)}\n`);
+    }
+    await verifyActiveStorageReplacementArchive(target, operationId, { packageRoot });
+    if (journal.phase === "ARCHIVED") {
+      return verifyActiveStorageReplacementArchive(target, operationId, { packageRoot });
+    }
+  }
+  let partition = await inspectActiveStorageReplacementPartition(target, operationId);
+  await mkdir(partition.archive, { recursive: true });
+  await syncDirectory(partition.root);
+  for (const root of partition.roots) {
+    if (root.location !== "ACTIVE") continue;
+    await assertOwnedStorageMaintenance(target);
+    partition = await inspectActiveStorageReplacementPartition(target, operationId);
+    if (partition.roots.find(current => current.path === root.path).location !== "ACTIVE") throw invalid("Outgoing source location changed during replacement archival");
+    const source = await assertSafePath(target, root.path);
+    const destination = await assertSafePath(partition.archive, root.path);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await rename(source, destination);
+    await syncDirectory(path.dirname(source));
+    await syncDirectory(path.dirname(destination));
+    await syncDirectory(partition.archive);
+    await inspectActiveStorageReplacementPartition(target, operationId);
+  }
+  const final = await verifyActiveStorageReplacementArchive(target, operationId, { packageRoot });
+  if (final.roots.some(root => root.location === "ACTIVE")) throw invalid("Replacement archival is incomplete");
+  journal.phase = "ARCHIVED";
+  await assertOwnedStorageMaintenance(target);
+  await writeFileAtomic(filename, `${JSON.stringify(journal, null, 2)}\n`);
+  return verifyActiveStorageReplacementArchive(target, operationId, { packageRoot });
+}

package/src/storage/restore-replacement-owner.js

@@ -0,0 +1,31 @@
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { MAINTENANCE_OWNER_ID, readMaintenanceOwner } from "./maintenance-owner.js";
+import { assertOwnedStorageMaintenance, assertStorageMaintenanceOwnerContinuity } from "./maintenance.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { verifyPreparedActiveStorageReplacement } from "./restore-replacement.js";
+
+const invalid = message => Object.assign(new Error(message), { code: "E_STORAGE_RESTORE_INVALID" });
+
+/** Advance mutable ownership without changing independently retained outgoing evidence. */
+export async function adoptPreparedReplacementOwner(target, operationId, { expectedOwnerId = null } = {}) {
+  const ownerId = await assertOwnedStorageMaintenance(target);
+  const retained = await verifyPreparedActiveStorageReplacement(target, operationId);
+  const fingerprint = canonicalFingerprint(retained.manifest);
+  const existing = await readStorageMetadataJson(retained.root, "owner-journal.json", { optional: true });
+  if (existing && (existing.schemaVersion !== 1 || existing.kind !== "REPLACEMENT_OUTGOING_OWNER" || existing.operationId !== operationId
+    || existing.outgoingFingerprint !== fingerprint || !MAINTENANCE_OWNER_ID.test(existing.ownerId ?? "")
+    || (existing.resumedFrom !== undefined && !MAINTENANCE_OWNER_ID.test(existing.resumedFrom)))) throw invalid("Replacement outgoing ownership journal differs from retained evidence");
+  const recorded = existing?.ownerId ?? retained.manifest.ownerId;
+  if (recorded !== ownerId) {
+    const owner = (await readMaintenanceOwner(target)).value;
+    if (owner.resumedFrom !== expectedOwnerId) throw invalid("Replacement outgoing ownership requires exact recorded owner adoption");
+    await assertStorageMaintenanceOwnerContinuity(target, { expectedOwnerId: ownerId, recordedOwnerId: recorded });
+  }
+  if (existing?.ownerId === ownerId) return existing;
+  const journal = { schemaVersion: 1, kind: "REPLACEMENT_OUTGOING_OWNER", operationId, ownerId, outgoingFingerprint: fingerprint,
+    ...(recorded !== ownerId ? { resumedFrom: recorded } : {}) };
+  await assertOwnedStorageMaintenance(target);
+  await writeFileAtomic(await assertSafePath(retained.root, "owner-journal.json"), `${JSON.stringify(journal, null, 2)}\n`);
+  return journal;
+}

package/src/storage/restore-replacement-preparation.js

@@ -0,0 +1,128 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, rename } from "node:fs/promises";
+import { syncDirectory } from "./file-durability.js";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { MAINTENANCE_OWNER_ID } from "./maintenance-owner.js";
+import { assertOwnedStorageMaintenance, assertStorageMaintenanceOwnerContinuity } from "./maintenance.js";
+import { readStorageVersionMarker } from "./storage-marker.js";
+import { openStorageDatabase, checkStorageIntegrity } from "./connection.js";
+import { validateMigrationDatabase } from "./migration-validation.js";
+import { logicalSnapshot } from "./migration-candidate.js";
+import { inventoryStorageRoots } from "./migration-source.js";
+import { restorePathExists } from "./restore-layout.js";
+import { prepareActiveStorageReplacement, verifyPreparedActiveStorageReplacement, REPLACEMENT_ACTIVE_ROOTS, assertReplacementConnectionsClosed } from "./restore-replacement.js";
+
+const invalid = message => Object.assign(new Error(message), { code: "E_STORAGE_RESTORE_INVALID" });
+const hash = value => typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+const independentInventory = inventory => ({ files: inventory.files.filter(file => file.path !== ".forgeloop/state.sqlite"), directories: inventory.directories });
+
+export function assertOutgoingRebuildIntent(intent) {
+  const rebuild = intent.outgoingRebuild;
+  if (!rebuild) return;
+  const previous = rebuild.previous ?? [];
+  if (!MAINTENANCE_OWNER_ID.test(rebuild.historyId ?? "") || !hash(rebuild.manifestFingerprint)
+    || !["RETAINING", "RETAINED"].includes(rebuild.phase) || !Array.isArray(previous) || previous.length > 63
+    || previous.some(record => !MAINTENANCE_OWNER_ID.test(record?.historyId ?? "") || !hash(record.manifestFingerprint))
+    || new Set([rebuild.historyId, ...previous.map(record => record.historyId)]).size !== previous.length + 1) throw invalid("Outgoing preparation retention intent is invalid");
+}
+
+async function verifyRetainedHistory(root, rebuild, operationId) {
+  for (const record of [...(rebuild.previous ?? []), rebuild]) {
+    const manifest = await readStorageMetadataJson(await assertSafePath(root, `outgoing-history/${record.historyId}`), "replacement-manifest.json");
+    if (manifest.operationId !== operationId || canonicalFingerprint(manifest) !== record.manifestFingerprint) throw invalid("Retained outgoing preparation manifest changed");
+  }
+}
+
+async function verifyPreparationBaseline(target, manifest, packageRoot) {
+  const baseline = manifest?.preparationBaseline;
+  if (manifest?.schemaVersion !== 2 || manifest.kind !== "ACTIVE_PROJECT_REPLACEMENT_OUTGOING" || manifest.status !== "PREPARING"
+    || !MAINTENANCE_OWNER_ID.test(manifest.ownerId ?? "") || !hash(baseline?.logicalFingerprint) || !hash(baseline?.inventoryFingerprint)
+    || canonicalFingerprint(baseline.inventory ?? null) !== baseline.inventoryFingerprint
+    || canonicalFingerprint(await readStorageVersionMarker(target)) !== canonicalFingerprint(manifest.marker)) throw invalid("Interrupted outgoing preparation has no matching active baseline");
+  await assertOwnedStorageMaintenance(target);
+  await assertStorageMaintenanceOwnerContinuity(target, { expectedOwnerId: await assertOwnedStorageMaintenance(target), recordedOwnerId: manifest.ownerId });
+  const db = openStorageDatabase(await assertSafePath(target, ".forgeloop/state.sqlite"), { allowSchemaUpgrade: false });
+  try {
+    if (!checkStorageIntegrity(db).ok || canonicalFingerprint(logicalSnapshot(db)) !== baseline.logicalFingerprint
+      || db.prepare("SELECT 1 FROM task_artifacts WHERE kind = 'operationLease' LIMIT 1").get()) throw invalid("Outgoing authority changed during interrupted preparation");
+    await validateMigrationDatabase(db, { target, packageRoot });
+    const checkpoint = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+    if (checkpoint.busy !== 0 || checkpoint.log !== 0) throw invalid("Outgoing preparation recovery still has active readers");
+  } finally { db.close(); }
+  await assertReplacementConnectionsClosed(target);
+  const current = await inventoryStorageRoots(target, REPLACEMENT_ACTIVE_ROOTS);
+  if (canonicalFingerprint(independentInventory(current)) !== canonicalFingerprint(independentInventory(baseline.inventory))) throw invalid("Outgoing attachments or marker changed during preparation recovery");
+}
+
+async function reconcileOutgoingAllocation(target, root, outgoing, intent, packageRoot) {
+  const present = await restorePathExists(root, "outgoing");
+  if (present && await readStorageMetadataJson(outgoing, "replacement-manifest.json", { optional: true })) return;
+  const allocated = await readStorageMetadataJson(root, "replacement-manifest.json", { optional: true });
+  if (!allocated) {
+    if (present) throw invalid("Outgoing allocation has no recorded preparation baseline");
+    return;
+  }
+  if (allocated.operationId !== intent.operationId) throw invalid("Outgoing allocation belongs to a different operation");
+  if (!present && intent.outgoingRebuild?.manifestFingerprint === canonicalFingerprint(allocated)) return;
+  await verifyPreparationBaseline(target, allocated, packageRoot);
+  await assertOwnedStorageMaintenance(target);
+  if (!present) { await mkdir(outgoing); await syncDirectory(root); }
+  // Reconstruct only missing metadata from its preallocation record; retained
+  // partial files remain in place and are moved to history by the caller.
+  await writeFileAtomic(await assertSafePath(outgoing, "replacement-manifest.json"), `${JSON.stringify(allocated, null, 2)}\n`);
+}
+
+/** Retain incomplete outgoing evidence before any new backup attempt. */
+export async function ensurePreparedOutgoingReplacement(target, root, intent, { writersQuiesced, packageRoot } = {}) {
+  await assertOwnedStorageMaintenance(target);
+  assertOutgoingRebuildIntent(intent);
+  const outgoing = await assertSafePath(root, "outgoing");
+  if (!intent.outgoingRebuild || intent.outgoingRebuild.phase === "RETAINED") {
+    await reconcileOutgoingAllocation(target, root, outgoing, intent, packageRoot);
+  }
+  const persist = async () => { await assertOwnedStorageMaintenance(target); await writeFileAtomic(await assertSafePath(root, "replacement-intent.json"), `${JSON.stringify(intent, null, 2)}\n`); };
+  if (!intent.outgoingRebuild) {
+    if (!await restorePathExists(root, "outgoing")) return prepareActiveStorageReplacement(target, intent.operationId, { writersQuiesced, packageRoot });
+    const manifest = await readStorageMetadataJson(outgoing, "replacement-manifest.json");
+    if (manifest?.status === "READY") return verifyPreparedActiveStorageReplacement(target, intent.operationId);
+    if (manifest?.operationId !== intent.operationId) throw invalid("Interrupted outgoing preparation belongs to another operation");
+    await verifyPreparationBaseline(target, manifest, packageRoot);
+    intent.outgoingRebuild = { historyId: randomUUID(), phase: "RETAINING", manifestFingerprint: canonicalFingerprint(manifest) };
+    await persist();
+  }
+  const rebuild = intent.outgoingRebuild;
+  const history = await assertSafePath(root, `outgoing-history/${rebuild.historyId}`);
+  if (rebuild.phase === "RETAINING") {
+    const current = await restorePathExists(root, "outgoing");
+    const retained = await restorePathExists(root, `outgoing-history/${rebuild.historyId}`);
+    if (current === retained) throw invalid("Outgoing preparation retention has ambiguous membership");
+    const manifest = await readStorageMetadataJson(current ? outgoing : history, "replacement-manifest.json");
+    if (manifest.operationId !== intent.operationId || canonicalFingerprint(manifest) !== rebuild.manifestFingerprint) throw invalid("Retained outgoing preparation operation or manifest differs");
+    await verifyPreparationBaseline(target, manifest, packageRoot);
+    if (current) {
+      await mkdir(await assertSafePath(root, "outgoing-history"), { recursive: true });
+      await rename(outgoing, history);
+      await syncDirectory(root);
+      await syncDirectory(await assertSafePath(root, "outgoing-history"));
+    }
+    rebuild.phase = "RETAINED";
+    await persist();
+  }
+  if (!await restorePathExists(root, `outgoing-history/${rebuild.historyId}`)) throw invalid("Outgoing preparation history is missing");
+  await verifyRetainedHistory(root, rebuild, intent.operationId);
+  if (await restorePathExists(root, "outgoing")) {
+    const manifest = await readStorageMetadataJson(outgoing, "replacement-manifest.json");
+    if (manifest?.status === "READY") return verifyPreparedActiveStorageReplacement(target, intent.operationId);
+    if (manifest?.operationId !== intent.operationId) throw invalid("Interrupted rebuilt outgoing operation differs");
+    await verifyPreparationBaseline(target, manifest, packageRoot);
+    const previous = [...(rebuild.previous ?? []), { historyId: rebuild.historyId, manifestFingerprint: rebuild.manifestFingerprint }];
+    intent.outgoingRebuild = { historyId: randomUUID(), phase: "RETAINING", manifestFingerprint: canonicalFingerprint(manifest), previous };
+    assertOutgoingRebuildIntent(intent);
+    await persist();
+    return ensurePreparedOutgoingReplacement(target, root, intent, { writersQuiesced, packageRoot });
+  }
+  await verifyPreparationBaseline(target, await readStorageMetadataJson(history, "replacement-manifest.json"), packageRoot);
+  return prepareActiveStorageReplacement(target, intent.operationId, { writersQuiesced, packageRoot });
+}

package/src/storage/restore-replacement.js

@@ -0,0 +1,142 @@
+import { lstat, mkdir } from "node:fs/promises";
+import { digestFile } from "./file-durability.js";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { assertJsonBytes, assertJsonLimits } from "../core/json-safety.js";
+import { getPackageRoot } from "../core/templates.js";
+import { getOperationalStore } from "./operational-context.js";
+import { MAINTENANCE_OWNER_ID } from "./maintenance-owner.js";
+import { assertOwnedStorageMaintenance } from "./maintenance.js";
+import { STORAGE_CATALOG_LIMITS, readStorageMetadataJson } from "./metadata-json.js";
+import { LEGACY_SOURCE_ROOTS, inventoryStorageRoots } from "./migration-source.js";
+import { readStorageVersionMarker, validateStorageVersionMarker } from "./storage-marker.js";
+import { restorePathExists } from "./restore-layout.js";
+import { checkStorageIntegrity, openStorageDatabase, readStorageMeta } from "./connection.js";
+import { backupProjectStorage, withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { validateMigrationDatabase } from "./migration-validation.js";
+import { iterateAttachmentReferences } from "./attachment-references.js";
+import { verifyAttachmentFile } from "./attachment-files.js";
+import { logicalSnapshot } from "./migration-candidate.js";
+
+const invalid = message => Object.assign(new Error(message), { code: "E_STORAGE_RESTORE_INVALID" });
+const hash = value => typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+const DATABASE = ".forgeloop/state.sqlite";
+export const REPLACEMENT_ACTIVE_ROOTS = Object.freeze([".forgeloop/storage-version.json", ".forgeloop/attachments", DATABASE]);
+
+async function replacementRoot(target, operationId) {
+  if (!MAINTENANCE_OWNER_ID.test(operationId ?? "")) throw invalid("Replacement preparation requires an exact restore operation identity");
+  return assertSafePath(target, `.forgeloop/storage-restores/${operationId}/outgoing`);
+}
+
+export async function assertReplacementConnectionsClosed(target) {
+  for (const suffix of ["-wal", "-shm"]) {
+    if (await restorePathExists(target, `${DATABASE}${suffix}`)) throw invalid("Close all SQLite connections before replacement publication; retained sidecars require reconciliation");
+  }
+}
+
+async function assertActiveLayout(target) {
+  const marker = await readStorageVersionMarker(target);
+  if (marker?.phase !== "ACTIVE") throw invalid("Active replacement requires an ACTIVE SQLite storage marker");
+  if (!(await lstat(await assertSafePath(target, DATABASE))).isFile()) throw invalid("Active replacement requires a regular canonical database");
+  for (const relative of LEGACY_SOURCE_ROOTS) {
+    if (relative !== ".forgeloop/attachments" && await restorePathExists(target, relative)) throw invalid(`Active replacement refuses mixed legacy operational state: ${relative}`);
+  }
+  return marker;
+}
+
+async function persistManifest(target, root, manifest) {
+  await assertOwnedStorageMaintenance(target);
+  assertJsonLimits(manifest, "Replacement outgoing manifest", STORAGE_CATALOG_LIMITS);
+  const text = `${JSON.stringify(manifest, null, 2)}\n`;
+  assertJsonBytes(text, "Replacement outgoing manifest", STORAGE_CATALOG_LIMITS);
+  await writeFileAtomic(await assertSafePath(root, "replacement-manifest.json"), text);
+}
+
+/** Retain outgoing authority before any active-project archival or overwrite. */
+export async function prepareActiveStorageReplacement(target, operationId, { writersQuiesced = false, packageRoot = getPackageRoot() } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Stop all writers and close their database connections before active replacement"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  const ownerId = await assertOwnedStorageMaintenance(target);
+  if (getOperationalStore(target)) throw invalid("Replacement cannot run inside an active operational command scope");
+  const root = await replacementRoot(target, operationId);
+  const marker = await assertActiveLayout(target);
+  const db = openStorageDatabase(await assertSafePath(target, DATABASE), { allowSchemaUpgrade: false });
+  let manifest;
+  try {
+    const metadata = readStorageMeta(db);
+    if (metadata.schema_version !== marker.databaseSchemaVersion || metadata.storage_version !== marker.storageVersion
+      || metadata.storage_format !== marker.storageFormat || !checkStorageIntegrity(db).ok) throw invalid("Outgoing database integrity or storage marker disagrees");
+    if (db.prepare("SELECT 1 FROM task_artifacts WHERE kind = 'operationLease' LIMIT 1").get()) throw invalid("Reconcile every retained task operation reservation before active replacement");
+    await validateMigrationDatabase(db, { target, packageRoot });
+    await mkdir(await assertSafePath(target, `.forgeloop/storage-restores/${operationId}`), { recursive: true });
+    if (await restorePathExists(target, `.forgeloop/storage-restores/${operationId}/outgoing`)) throw Object.assign(invalid("An earlier outgoing preparation must not be overwritten"), { code: "EEXIST" });
+    const initialCheckpoint = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+    if (initialCheckpoint.busy !== 0 || initialCheckpoint.log !== 0) throw invalid("Outgoing preparation requires checkpointed authority");
+    const baselineInventory = await inventoryStorageRoots(target, REPLACEMENT_ACTIVE_ROOTS);
+    manifest = { schemaVersion: 2, kind: "ACTIVE_PROJECT_REPLACEMENT_OUTGOING", operationId, ownerId, status: "PREPARING", marker,
+      preparationBaseline: { logicalFingerprint: canonicalFingerprint(logicalSnapshot(db)), inventory: baselineInventory, inventoryFingerprint: canonicalFingerprint(baselineInventory) } };
+    await persistManifest(target, await assertSafePath(target, `.forgeloop/storage-restores/${operationId}`), manifest);
+    await mkdir(root); // Never overwrite an earlier preparation or its evidence.
+    await persistManifest(target, root, manifest);
+    const backup = await assertSafePath(root, "backup");
+    await backupProjectStorage(db, target, backup);
+    await withVerifiedProjectStorageBackup(backup, async retained => {
+      await validateMigrationDatabase(retained.db, { target: retained.root, packageRoot, archivedExecutions: true });
+      const logicalFingerprint = canonicalFingerprint(logicalSnapshot(retained.db));
+      if (logicalFingerprint !== canonicalFingerprint(logicalSnapshot(db))) throw invalid("Outgoing state changed while its retained backup was prepared");
+      Object.assign(manifest, { backupFingerprint: canonicalFingerprint(retained.manifest), logicalFingerprint });
+    });
+    await assertOwnedStorageMaintenance(target);
+    const checkpoint = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+    if (checkpoint.busy !== 0 || checkpoint.log !== 0) throw invalid("Outgoing database still has active readers or required WAL contents");
+    const inventory = await inventoryStorageRoots(target, REPLACEMENT_ACTIVE_ROOTS);
+    Object.assign(manifest, { databaseSha256: await digestFile(await assertSafePath(target, DATABASE)), inventory, inventoryFingerprint: canonicalFingerprint(inventory) });
+    if (canonicalFingerprint(logicalSnapshot(db)) !== manifest.logicalFingerprint) throw invalid("Outgoing state changed before its closed database binding was recorded");
+  } catch (error) {
+    if (manifest) { manifest.status = "FAILED"; manifest.error = { code: error.code ?? "E_STORAGE_RESTORE_INVALID", message: error.message }; try { await persistManifest(target, root, manifest); } catch { /* PREPARING is also refused. */ } }
+    throw error;
+  } finally { db.close(); }
+  try {
+    await assertReplacementConnectionsClosed(target);
+    if (canonicalFingerprint(await assertActiveLayout(target)) !== canonicalFingerprint(marker)) throw invalid("Outgoing storage marker changed during preparation");
+    manifest.status = "READY";
+    await assertOwnedStorageMaintenance(target);
+    await persistManifest(target, root, manifest);
+    return assertActiveStorageReplacementUnchanged(target, operationId);
+  } catch (error) {
+    manifest.status = "FAILED"; manifest.error = { code: error.code ?? "E_STORAGE_RESTORE_INVALID", message: error.message };
+    try { await persistManifest(target, root, manifest); } catch { /* PREPARING is also refused. */ }
+    throw error;
+  }
+}
+
+/** Read-only verification of retained outgoing authority, independent of publication. */
+export async function verifyPreparedActiveStorageReplacement(target, operationId) {
+  const root = await replacementRoot(target, operationId);
+  const manifest = await readStorageMetadataJson(root, "replacement-manifest.json");
+  if (!manifest || manifest.schemaVersion !== 2 || manifest.kind !== "ACTIVE_PROJECT_REPLACEMENT_OUTGOING" || manifest.operationId !== operationId
+    || !MAINTENANCE_OWNER_ID.test(manifest.ownerId ?? "") || manifest.status !== "READY" || manifest.marker?.phase !== "ACTIVE"
+    || !hash(manifest.databaseSha256) || !hash(manifest.backupFingerprint) || !hash(manifest.logicalFingerprint)
+    || !hash(manifest.inventoryFingerprint) || canonicalFingerprint(manifest.inventory ?? null) !== manifest.inventoryFingerprint) throw invalid("Outgoing replacement evidence is incomplete or inconsistent");
+  validateStorageVersionMarker(manifest.marker);
+  await withVerifiedProjectStorageBackup(await assertSafePath(root, "backup"), retained => {
+    const metadata = readStorageMeta(retained.db);
+    if (canonicalFingerprint(retained.manifest) !== manifest.backupFingerprint || canonicalFingerprint(logicalSnapshot(retained.db)) !== manifest.logicalFingerprint
+      || metadata.schema_version !== manifest.marker.databaseSchemaVersion || metadata.storage_version !== manifest.marker.storageVersion
+      || metadata.storage_format !== manifest.marker.storageFormat) throw invalid("Outgoing backup differs from its replacement binding");
+  });
+  return { root, manifest, backup: await assertSafePath(root, "backup"), outgoingVerified: true, replaced: false };
+}
+
+/** Must pass immediately before archiving the closed outgoing active layout. */
+export async function assertActiveStorageReplacementUnchanged(target, operationId) {
+  await assertOwnedStorageMaintenance(target);
+  const retained = await verifyPreparedActiveStorageReplacement(target, operationId);
+  await assertReplacementConnectionsClosed(target);
+  if (canonicalFingerprint(await assertActiveLayout(target)) !== canonicalFingerprint(retained.manifest.marker)
+    || await digestFile(await assertSafePath(target, DATABASE)) !== retained.manifest.databaseSha256
+    || canonicalFingerprint(await inventoryStorageRoots(target, REPLACEMENT_ACTIVE_ROOTS)) !== retained.manifest.inventoryFingerprint) throw invalid("Active state changed after outgoing replacement preparation; archival is forbidden");
+  await withVerifiedProjectStorageBackup(retained.backup, async ({ db }) => {
+    for (const reference of iterateAttachmentReferences(db)) await verifyAttachmentFile(target, reference);
+  });
+  return retained;
+}

package/src/storage/restore-terminal.js

@@ -0,0 +1,32 @@
+import { assertSafePath } from "../core/filesystem.js";
+import { getPackageRoot } from "../core/templates.js";
+import { verifyProjectRestoreJournal } from "./restore-journal.js";
+import { withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { checkStorageIntegrity, openStorageDatabase, readStorageMeta } from "./connection.js";
+import { withStorageSnapshot } from "./snapshot.js";
+import { assertSnapshotContinuity } from "./snapshot-continuity.js";
+import { validateMigrationDatabase } from "./migration-validation.js";
+import { iterateAttachmentReferences } from "./attachment-references.js";
+import { verifyAttachmentFile } from "./attachment-files.js";
+
+const invalid = message => Object.assign(new Error(message), { code: "E_STORAGE_RESTORE_INVALID" });
+
+/** Verify accepted current state; never restore the earlier retained snapshot. */
+export async function verifyActiveProjectRestore(target, operationId, { expectedOwnerId = null, packageRoot = getPackageRoot() } = {}) {
+  const retained = await verifyProjectRestoreJournal(target, operationId, { expectedOwnerId });
+  if (retained.journal.phase !== "ACTIVE" || retained.marker?.phase !== "ACTIVE") throw invalid("Restore verification requires terminal ACTIVE 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 });
+  try {
+    return await withVerifiedProjectStorageBackup(retained.snapshot, ({ db: original }) => withStorageSnapshot(db, async current => {
+      const meta = readStorageMeta(current);
+      if (!checkStorageIntegrity(current).ok || meta.schema_version !== retained.marker.databaseSchemaVersion
+        || meta.storage_format !== retained.marker.storageFormat || meta.storage_version !== retained.marker.storageVersion) throw invalid("Current restore storage integrity or version differs");
+      assertSnapshotContinuity(original, current, invalid);
+      const validation = await validateMigrationDatabase(current, { target, packageRoot });
+      let references = 0;
+      for (const reference of iterateAttachmentReferences(current)) { await verifyAttachmentFile(target, reference); references += 1; }
+      return { active: true, phase: "ACTIVE", operationId, taskCount: validation.tasks.length, references, currentStateVerified: true, restored: false };
+    }));
+  } finally { db.close(); }
+}

package/src/storage/runtime.js

@@ -0,0 +1,31 @@
+import { createRequire } from "node:module";
+
+export const STORAGE_MINIMUM_NODE = "24.19.0";
+export const STORAGE_TESTED_SQLITE = "3.53.3";
+const require = createRequire(import.meta.url);
+let driver;
+
+function unsupported(message, cause) {
+  return Object.assign(new Error(message, cause ? { cause } : undefined), { code: "E_STORAGE_UNSUPPORTED_RUNTIME" });
+}
+
+/** Reject older runtimes before loading SQLite or creating any storage files. */
+export function assertStorageNodeVersion(version = process.versions.node) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version ?? "");
+  if (!match || Number(match[1]) < 24 || (Number(match[1]) === 24 && Number(match[2]) < 19)) {
+    throw unsupported(`ForgeLoop SQLite storage requires Node >=${STORAGE_MINIMUM_NODE}; detected ${version ?? "unknown"}`);
+  }
+}
+
+/** One built-in driver path, loaded only when storage work is requested. */
+export function loadStorageDriver() {
+  assertStorageNodeVersion();
+  if (!driver) {
+    let loaded;
+    try { loaded = require("node:sqlite"); }
+    catch (error) { throw unsupported("This Node build does not provide the required built-in node:sqlite module", error); }
+    if (typeof loaded.DatabaseSync !== "function" || typeof loaded.backup !== "function") throw unsupported("This Node build lacks the required SQLite database and native backup APIs");
+    driver = loaded;
+  }
+  return driver;
+}