@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/src/storage/project-boundary.js

@@ -0,0 +1,79 @@
+import { getStorageConnectionOwner } from "../core/storage-runtime-registry.js";
+import { lstat, realpath } from "node:fs/promises";
+import { assertSafePath } from "../core/filesystem.js";
+import { getOperationalStore } from "./operational-context.js";
+import { assertStorageMaintenanceInactive } from "./maintenance.js";
+import { readStorageVersionMarker } from "./storage-marker.js";
+import { assertNoLegacyOperationLocks } from "./legacy-maintenance-boundary.js";
+
+async function exists(filename) {
+  try { await lstat(filename); return true; }
+  catch (error) { if (error.code === "ENOENT") return false; throw error; }
+}
+
+async function bootstrapFreshProject(target) {
+  const { assertStorageTopology } = await import("./topology.js");
+  assertStorageTopology(await assertSafePath(target, ".forgeloop/state.sqlite"));
+  const { LEGACY_SOURCE_ROOTS } = await import("./migration-source.js");
+  for (const relative of [...LEGACY_SOURCE_ROOTS, ".forgeloop/state.sqlite-wal", ".forgeloop/state.sqlite-shm"]) {
+    if (await exists(await assertSafePath(target, relative))) {
+      throw Object.assign(new Error("Legacy operational state requires explicit storage migration before mutation"), { code: "E_STORAGE_MIGRATION_REQUIRED" });
+    }
+  }
+  const { bootstrapProjectStorage } = await import("./project-bootstrap.js");
+  // Fresh state has no legacy authority to convert. Restore publication owns
+  // exclusive admission and rechecks freshness after acquiring it.
+  await bootstrapProjectStorage(target, { writersQuiesced: true });
+}
+
+/** Bootstrap fresh writable projects; never convert legacy state implicitly. */
+export async function withProjectStorage(target, callback, { readOnly = false, runtimeContext = null, connectionLease = null, existingOnly = false } = {}) {
+  const owner = getStorageConnectionOwner(runtimeContext);
+  if (owner && !getOperationalStore(target)) return owner.run(target, lease => withProjectStorage(target, callback, { readOnly, connectionLease: lease, existingOnly }), { readOnly });
+  await assertStorageMaintenanceInactive(target);
+  await assertNoLegacyOperationLocks(target);
+  const marker = await readStorageVersionMarker(target);
+  if (marker?.phase === "CUTOVER_PENDING") throw Object.assign(new Error("Storage cutover requires explicit recovery before ordinary dispatch"), { code: "E_STORAGE_MIGRATION_REQUIRED" });
+  if (getOperationalStore(target)) return callback();
+  const filename = await assertSafePath(target, ".forgeloop/state.sqlite");
+  if (!(await exists(filename))) {
+    connectionLease?.assertUnselected();
+    if (marker || existingOnly) throw Object.assign(new Error("Selected SQLite storage requires its active database; filesystem fallback is forbidden"), { code: "E_STORAGE_MIGRATION_REQUIRED" });
+    if (readOnly) return callback();
+    await bootstrapFreshProject(target);
+    return withProjectStorage(target, callback, { readOnly, connectionLease, existingOnly });
+  }
+  // SQLite opens these adjacent files itself; validate their containment too.
+  await assertSafePath(target, ".forgeloop/state.sqlite-wal");
+  await assertSafePath(target, ".forgeloop/state.sqlite-shm");
+  for (const relativePath of [
+    ".forgeloop/task-state",
+    ".forgeloop/work-state.json",
+    ".forgeloop/events.ndjson",
+    ".forgeloop/.txn",
+    ".forgeloop/session.json",
+    ".forgeloop/sessions",
+  ]) {
+    if (await exists(await assertSafePath(target, relativePath))) {
+      throw Object.assign(new Error("SQLite and writable legacy operational state cannot coexist; explicit migration is required"), { code: "E_STORAGE_MIGRATION_REQUIRED" });
+    }
+  }
+  const [{ openStorageDatabase, readStorageMeta }, { withOperationalStore }] = await Promise.all([
+    import("./connection.js"), import("./unit-of-work.js"),
+  ]);
+  const root = await realpath(target);
+  const identity = await lstat(filename, { bigint: true });
+  const rootIdentity = await lstat(target, { bigint: true });
+  const options = { readOnly, allowSchemaUpgrade: !marker, allowOptionalIndexCreation: !readOnly,
+    projectAdmission: { root, target, dev: identity.dev, ino: identity.ino, rootIdentity } };
+  const db = connectionLease ? await connectionLease.open(filename, options) : openStorageDatabase(filename, options);
+  try {
+    if (marker) {
+      const metadata = readStorageMeta(db);
+      if (metadata.schema_version !== marker.databaseSchemaVersion || metadata.storage_version !== marker.storageVersion
+        || metadata.storage_format !== marker.storageFormat) throw Object.assign(new Error("Active database metadata disagrees with its storage marker"), { code: "E_STORAGE_VERSION_MARKER_INVALID" });
+    }
+    return await withOperationalStore({ db, target, readOnly }, callback);
+  }
+  finally { if (!connectionLease) db.close(); }
+}

package/src/storage/project-read-snapshot.js

@@ -0,0 +1,18 @@
+import { getOperationalStore } from "./operational-context.js";
+import { needsExistingProjectScope, withExistingProjectScope } from "./existing-project-scope.js";
+
+/** Keep committed native projections consistent without holding live locks across I/O. */
+export async function withProjectReadSnapshot(target, read) {
+  if (await needsExistingProjectScope(target)) {
+    return withExistingProjectScope(target, () => withProjectReadSnapshot(target, read), { readOnly: true });
+  }
+  const store = getOperationalStore(target);
+  // Prepared operations must retain their staged records and transaction observations.
+  if (!store || store.hasPreparedMutations()) return read();
+  const { withStorageSnapshot, isOwnedStorageSnapshot } = await import("./snapshot.js");
+  // Reuse only a pure reader on an owned immutable copy. Writable ancestors
+  // still need detached observation scopes for later conflict checks.
+  if (store.captureObservations === false && isOwnedStorageSnapshot(store.db)) return read();
+  const { withOperationalReadSnapshot } = await import("./unit-of-work.js");
+  return withStorageSnapshot(store.db, db => withOperationalReadSnapshot({ db, target }, read));
+}

package/src/storage/project-replacement.js

@@ -0,0 +1,137 @@
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { getPackageRoot } from "../core/templates.js";
+import { withStorageMaintenance, resumeStorageMaintenance, assertOwnedStorageMaintenance, retainStorageMaintenance, assertStorageMaintenanceOwnerContinuity } from "./maintenance.js";
+import { backupProjectStorage, withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { validateMigrationDatabase } from "./migration-validation.js";
+import { logicalSnapshot } from "./migration-candidate.js";
+import { prepareActiveStorageReplacement, REPLACEMENT_ACTIVE_ROOTS } from "./restore-replacement.js";
+import { archiveActiveStorageReplacement } from "./restore-replacement-archive.js";
+import { publishArchivedStorageReplacement, resumeProjectStorageRestore } from "./project-restore.js";
+import { verifyProjectRestoreJournal } from "./restore-journal.js";
+import { MAINTENANCE_OWNER_ID } from "./maintenance-owner.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { restorePathExists } from "./restore-layout.js";
+import { ensurePreparedRestoreSnapshot } from "./restore-preparation.js";
+import { adoptPreparedReplacementOwner } from "./restore-replacement-owner.js";
+import { ensurePreparedOutgoingReplacement, assertOutgoingRebuildIntent } from "./restore-replacement-preparation.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);
+
+function assertRebuildIntent(intent) {
+  if (intent.rebuild && (!MAINTENANCE_OWNER_ID.test(intent.rebuild.historyId ?? "") || typeof intent.rebuild.retainSnapshot !== "boolean"
+    || !["RETAINING", "RETAINED"].includes(intent.rebuild.phase) || (intent.phase === "READY" && intent.rebuild.phase !== "RETAINED"))) throw invalid("Replacement snapshot retention intent is invalid");
+  assertOutgoingRebuildIntent(intent);
+}
+
+export async function verifyProjectReplacementIntent(target, operationId, { expectedOwnerId = null } = {}) {
+  if (!MAINTENANCE_OWNER_ID.test(operationId ?? "")) throw invalid("Replacement inspection requires an exact operation identity");
+  const root = await assertSafePath(target, `.forgeloop/storage-restores/${operationId}`);
+  const intent = await readStorageMetadataJson(root, "replacement-intent.json");
+  if (!intent || intent.schemaVersion !== 1 || intent.kind !== "ACTIVE_PROJECT_REPLACEMENT" || intent.operationId !== operationId
+    || !MAINTENANCE_OWNER_ID.test(intent.ownerId ?? "") || (expectedOwnerId !== null && intent.ownerId !== expectedOwnerId)
+    || typeof intent.source !== "string" || !path.isAbsolute(intent.source) || !hash(intent.sourceFingerprint)
+    || !["PREPARING", "READY"].includes(intent.phase)
+    || (intent.phase === "READY" && !hash(intent.snapshotFingerprint))
+    || (intent.phase === "PREPARING" && intent.snapshotFingerprint !== undefined)) throw invalid("Replacement preparation identity or phase is invalid");
+  assertRebuildIntent(intent);
+  return { root, intent };
+}
+
+/** Select only the stage recorded for the explicitly requested replacement. */
+export async function resumeActiveProjectReplacement(target, options = {}) {
+  if (options.writersQuiesced !== true) throw Object.assign(new Error("Exclude writers before replacement recovery"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  const selected = await verifyProjectReplacementIntent(target, options.operationId);
+  if (!await restorePathExists(selected.root, "restore-journal.json")) return resumeProjectReplacementPreparation(target, options);
+  const publication = await verifyProjectRestoreJournal(target, options.operationId);
+  if (selected.intent.phase !== "READY" || !publication.journal.replacement
+    || selected.intent.snapshotFingerprint !== publication.journal.snapshotFingerprint
+    || selected.intent.snapshotFingerprint !== publication.journal.replacement.incomingFingerprint) throw invalid("Replacement preparation and publication checkpoints disagree");
+  return resumeProjectStorageRestore(target, options);
+}
+
+/** Resume preparation/archival before a publication journal has been created. */
+export async function resumeProjectReplacementPreparation(target, { operationId, expectedOwnerId, writersQuiesced = false, packageRoot = getPackageRoot() } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Exclude writers before replacement recovery"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  const before = await verifyProjectReplacementIntent(target, operationId);
+  await assertStorageMaintenanceOwnerContinuity(target, { expectedOwnerId, recordedOwnerId: before.intent.ownerId });
+  if (await restorePathExists(before.root, "restore-journal.json")) throw invalid("Replacement publication intent already exists; use publication resume");
+  return resumeStorageMaintenance(target, { expectedOwnerId, writersQuiesced }, async () => {
+    await retainStorageMaintenance(target);
+    const current = await verifyProjectReplacementIntent(target, operationId);
+    if (canonicalFingerprint(current.intent) !== canonicalFingerprint(before.intent)) throw invalid("Replacement intent changed during owner adoption");
+    await assertStorageMaintenanceOwnerContinuity(target, { expectedOwnerId: await assertOwnedStorageMaintenance(target), recordedOwnerId: current.intent.ownerId });
+    const intent = current.intent;
+    intent.ownerId = await assertOwnedStorageMaintenance(target);
+    const persist = async () => {
+      await assertOwnedStorageMaintenance(target);
+      await writeFileAtomic(await assertSafePath(current.root, "replacement-intent.json"), `${JSON.stringify(intent, null, 2)}\n`);
+    };
+    await persist();
+    await ensurePreparedOutgoingReplacement(target, current.root, intent, { writersQuiesced, packageRoot });
+    await adoptPreparedReplacementOwner(target, operationId, { expectedOwnerId });
+    if (intent.phase === "PREPARING") {
+      await ensurePreparedRestoreSnapshot(target, current.root, intent, { journalFilename: "replacement-intent.json" });
+      await withVerifiedProjectStorageBackup(await assertSafePath(current.root, "snapshot"), async retained => {
+        await validateMigrationDatabase(retained.db, { target: retained.root, packageRoot });
+        await withVerifiedProjectStorageBackup(intent.source, source => {
+          if (canonicalFingerprint(source.manifest) !== intent.sourceFingerprint
+            || canonicalFingerprint(logicalSnapshot(source.db)) !== canonicalFingerprint(logicalSnapshot(retained.db))) throw invalid("Replacement recovery snapshot differs from recorded source");
+        });
+        intent.snapshotFingerprint = canonicalFingerprint(retained.manifest);
+      });
+      intent.phase = "READY";
+      await persist();
+    }
+    await withVerifiedProjectStorageBackup(await assertSafePath(current.root, "snapshot"), retained => {
+      if (canonicalFingerprint(retained.manifest) !== intent.snapshotFingerprint) throw invalid("Replacement incoming snapshot changed after preparation");
+    });
+    await archiveActiveStorageReplacement(target, operationId, { packageRoot, expectedOwnerId });
+    return publishArchivedStorageReplacement(target, operationId, { packageRoot });
+  });
+}
+
+/** Initial replacement orchestration. Every outgoing byte remains independently retained. */
+export async function replaceActiveProjectStorage(source, target, { writersQuiesced = false, packageRoot = getPackageRoot() } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Exclude writers and close their database connections before active replacement"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  return withVerifiedProjectStorageBackup(source, async ({ db, root, manifest }) => {
+    await validateMigrationDatabase(db, { target: root, packageRoot });
+    const relative = path.relative(path.resolve(target), root).split(path.sep).join("/");
+    if (REPLACEMENT_ACTIVE_ROOTS.some(name => relative === name || relative.startsWith(`${name}/`))) throw invalid("Replacement source cannot be archived outgoing operational state");
+    return withStorageMaintenance(target, async () => {
+      await retainStorageMaintenance(target);
+      const operationId = randomUUID();
+      const operationRoot = await assertSafePath(target, `.forgeloop/storage-restores/${operationId}`);
+      await mkdir(path.dirname(operationRoot), { recursive: true });
+      await mkdir(operationRoot);
+      const intent = { schemaVersion: 1, kind: "ACTIVE_PROJECT_REPLACEMENT", operationId, ownerId: await assertOwnedStorageMaintenance(target),
+        source: root, sourceFingerprint: canonicalFingerprint(manifest), phase: "PREPARING" };
+      const persist = async () => {
+        await assertOwnedStorageMaintenance(target);
+        await writeFileAtomic(await assertSafePath(operationRoot, "replacement-intent.json"), `${JSON.stringify(intent, null, 2)}\n`);
+      };
+      await persist();
+      await prepareActiveStorageReplacement(target, operationId, { writersQuiesced, packageRoot });
+      const snapshot = await assertSafePath(operationRoot, "snapshot");
+      await backupProjectStorage(db, root, snapshot);
+      await withVerifiedProjectStorageBackup(snapshot, async retained => {
+        await validateMigrationDatabase(retained.db, { target: retained.root, packageRoot });
+        await withVerifiedProjectStorageBackup(root, current => {
+          if (canonicalFingerprint(current.manifest) !== intent.sourceFingerprint
+            || canonicalFingerprint(logicalSnapshot(current.db)) !== canonicalFingerprint(logicalSnapshot(retained.db))) throw invalid("Incoming source changed during replacement preparation");
+        });
+        intent.snapshotFingerprint = canonicalFingerprint(retained.manifest);
+      });
+      intent.phase = "READY";
+      await persist();
+      await archiveActiveStorageReplacement(target, operationId, { packageRoot });
+      // Publication owns the terminal validator and admission release decision.
+      const result = await publishArchivedStorageReplacement(target, operationId, { packageRoot });
+      return { ...result, operationId, replacementIntent: await assertSafePath(operationRoot, "replacement-intent.json") };
+    }, { retainOnError: true });
+  });
+}

package/src/storage/project-restore.js

@@ -0,0 +1,203 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { getPackageRoot } from "../core/templates.js";
+import { LEGACY_SOURCE_ROOTS } from "./migration-source.js";
+import { assertNoLegacyOperationLocks } from "./legacy-maintenance-boundary.js";
+import { withStorageMaintenance, resumeStorageMaintenance, assertOwnedStorageMaintenance, retainStorageMaintenance, allowStorageMaintenanceRelease, assertStorageMaintenanceOwnerContinuity } from "./maintenance.js";
+import { readStorageVersionMarker, writePendingStorageVersionMarker, activateStorageVersionMarker } from "./storage-marker.js";
+import { backupProjectStorage, withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { backupStorageDatabase } from "./backup.js";
+import { openStorageDatabase, readStorageMeta, checkStorageIntegrity } from "./connection.js";
+import { validateMigrationDatabase } from "./migration-validation.js";
+import { iterateAttachmentReferences } from "./attachment-references.js";
+import { publishAttachmentFile, withVerifiedAttachmentFile, verifyAttachmentFile } from "./attachment-files.js";
+import { logicalSnapshot } from "./migration-candidate.js";
+import { verifyProjectRestoreJournal } from "./restore-journal.js";
+import { assertRestorePublicationLayout, restorePathExists } from "./restore-layout.js";
+import { verifyActiveProjectRestore } from "./restore-terminal.js";
+import { ensurePreparedRestoreSnapshot } from "./restore-preparation.js";
+import { verifyActiveStorageReplacementArchive, verifyRetainedStorageReplacementArchive } from "./restore-replacement-archive.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+
+/** Publish the verified incoming snapshot only after complete outgoing archival. */
+export async function publishArchivedStorageReplacement(target, operationId, { packageRoot = getPackageRoot() } = {}) {
+  const ownerId = await assertOwnedStorageMaintenance(target);
+  await retainStorageMaintenance(target);
+  const operationRoot = await assertSafePath(target, `.forgeloop/storage-restores/${operationId}`);
+  const journalPath = await assertSafePath(operationRoot, "restore-journal.json");
+  let journal = await readStorageMetadataJson(operationRoot, "restore-journal.json", { optional: true });
+  if (!journal) {
+    const archived = await verifyActiveStorageReplacementArchive(target, operationId, { packageRoot });
+    if (!archived.archived || archived.journal.ownerId !== ownerId) throw invalid("Replacement publication requires complete archival by the current owner");
+    await assertFreshOperationalState(target);
+    await withVerifiedProjectStorageBackup(archived.incomingSnapshot, async ({ db, root, manifest }) => {
+      journal = { schemaVersion: 1, kind: "PROJECT_RESTORE", operationId, ownerId, source: root,
+        sourceFingerprint: canonicalFingerprint(manifest), phase: "READY", snapshotFingerprint: canonicalFingerprint(manifest),
+        replacement: { outgoingFingerprint: archived.journal.outgoingFingerprint, incomingFingerprint: archived.journal.incomingFingerprint },
+        binding: { operationId, databaseSchemaVersion: readStorageMeta(db).schema_version,
+          sourceInventoryFingerprint: canonicalFingerprint({ database: manifest.databaseSha256, inventory: manifest.inventorySha256, references: manifest.references }) } };
+      await assertOwnedStorageMaintenance(target);
+      await writeFileAtomic(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
+    });
+  }
+  const verified = await verifyProjectRestoreJournal(target, operationId, { expectedOwnerId: ownerId });
+  if (!verified.journal.replacement) throw invalid("Selected restore is not an archived replacement");
+  await verifyRetainedStorageReplacementArchive(target, operationId, { ...verified.journal.replacement, packageRoot });
+  const result = verified.journal.phase === "ACTIVE"
+    ? await verifyActiveProjectRestore(target, operationId, { expectedOwnerId: ownerId, packageRoot })
+    : await publishReadyRestore(target, operationRoot, verified.journal, { packageRoot });
+  await verifyActiveProjectRestore(target, operationId, { expectedOwnerId: ownerId, packageRoot });
+  await allowStorageMaintenanceRelease(target);
+  return { ...result, replaced: true };
+}
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_RESTORE_INVALID" }); }
+
+export async function assertFreshOperationalState(target) {
+  await assertNoLegacyOperationLocks(target, { code: "E_STORAGE_RESTORE_INVALID" });
+  if (await readStorageVersionMarker(target)) throw invalid("Restore activation requires a project without an existing storage marker");
+  for (const relative of [...LEGACY_SOURCE_ROOTS, ".forgeloop/state.sqlite", ".forgeloop/state.sqlite-wal", ".forgeloop/state.sqlite-shm"]) {
+    try { await lstat(await assertSafePath(target, relative)); }
+    catch (error) { if (error.code === "ENOENT") continue; throw error; }
+    throw invalid(`Restore activation refuses existing operational state: ${relative}`);
+  }
+}
+
+/** Restore a verified independent snapshot into an operationally fresh project. */
+export async function restoreProjectStorageToFreshProject(source, target, { writersQuiesced = false, packageRoot = getPackageRoot() } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Exclude all writers before restore activation"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  // Verify source before acquiring exclusion or allocating restore evidence.
+  return withVerifiedProjectStorageBackup(source, async ({ db, root, manifest: sourceManifest }) => {
+    await assertFreshOperationalState(target);
+    await mkdir(await assertSafePath(target, ".forgeloop"), { recursive: true });
+    return withStorageMaintenance(target, async () => {
+      await assertFreshOperationalState(target);
+      const operationId = randomUUID();
+      const operationRoot = await assertSafePath(target, `.forgeloop/storage-restores/${operationId}`);
+      await mkdir(path.dirname(operationRoot), { recursive: true });
+      await mkdir(operationRoot);
+      const journalPath = await assertSafePath(operationRoot, "restore-journal.json");
+      const journal = { schemaVersion: 1, kind: "PROJECT_RESTORE", operationId, ownerId: await assertOwnedStorageMaintenance(target),
+        source: root, sourceFingerprint: canonicalFingerprint(sourceManifest), phase: "PREPARING" };
+      const persist = () => writeFileAtomic(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
+      await persist();
+      const retained = await assertSafePath(operationRoot, "snapshot");
+      await backupProjectStorage(db, root, retained);
+      return withVerifiedProjectStorageBackup(retained, async ({ db: snapshot, manifest }) => {
+        await withVerifiedProjectStorageBackup(root, current => {
+          if (canonicalFingerprint(current.manifest) !== canonicalFingerprint(sourceManifest)
+            || canonicalFingerprint(logicalSnapshot(current.db)) !== canonicalFingerprint(logicalSnapshot(snapshot))) throw invalid("Source backup changed during restore preparation");
+        });
+        await validateMigrationDatabase(snapshot, { target: retained, packageRoot });
+        const binding = { operationId, databaseSchemaVersion: readStorageMeta(snapshot).schema_version,
+          sourceInventoryFingerprint: canonicalFingerprint({ database: manifest.databaseSha256, inventory: manifest.inventorySha256, references: manifest.references }) };
+        Object.assign(journal, { phase: "READY", binding, snapshotFingerprint: canonicalFingerprint(manifest) });
+        await persist();
+        return publishReadyRestore(target, operationRoot, journal, { packageRoot });
+      });
+    }, { retainOnError: true });
+  });
+}
+
+async function publishReadyRestore(target, operationRoot, journal, { packageRoot }) {
+  if (!["READY", "PUBLISHING"].includes(journal.phase)) throw invalid("Restore publication requires a validated READY or PUBLISHING checkpoint");
+  if (journal.phase === "READY") await assertFreshOperationalState(target);
+  const retained = await assertSafePath(operationRoot, "snapshot");
+  const journalPath = await assertSafePath(operationRoot, "restore-journal.json");
+  const persist = () => writeFileAtomic(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
+  const { operationId, binding } = journal;
+  return withVerifiedProjectStorageBackup(retained, async ({ db: snapshot, manifest }) => {
+    await validateMigrationDatabase(snapshot, { target: retained, packageRoot });
+    await assertOwnedStorageMaintenance(target);
+    await verifyProjectRestoreJournal(target, operationId, { expectedOwnerId: await assertOwnedStorageMaintenance(target) });
+    await assertRestorePublicationLayout(target, snapshot);
+    const existingMarker = await readStorageVersionMarker(target);
+    const alreadyActive = existingMarker?.phase === "ACTIVE";
+    const filename = await assertSafePath(target, ".forgeloop/state.sqlite");
+    const existingDatabase = await restorePathExists(target, ".forgeloop/state.sqlite");
+    if (alreadyActive && !existingDatabase) throw invalid("An active restore database cannot be automatically recreated");
+    if (existingDatabase) {
+      for (const suffix of ["-wal", "-shm"]) await assertSafePath(target, `.forgeloop/state.sqlite${suffix}`);
+      const current = openStorageDatabase(filename, { readOnly: true });
+      try {
+        if (!checkStorageIntegrity(current).ok || canonicalFingerprint(logicalSnapshot(current)) !== canonicalFingerprint(logicalSnapshot(snapshot))) throw invalid("Existing restore database differs; automatic overwrite is forbidden");
+        if (alreadyActive) for (const reference of iterateAttachmentReferences(current)) await verifyAttachmentFile(target, reference);
+      } finally { current.close(); }
+    }
+    journal.phase = "PUBLISHING";
+    await persist();
+    if (!alreadyActive) await writePendingStorageVersionMarker(target, binding);
+    const temporaryRoot = await assertSafePath(retained, "activation-attachments");
+    await mkdir(temporaryRoot, { recursive: true });
+    for (const reference of alreadyActive ? [] : iterateAttachmentReferences(snapshot)) {
+      await assertOwnedStorageMaintenance(target);
+      const copied = await withVerifiedAttachmentFile(retained, reference, filename => publishAttachmentFile(target, createReadStream(filename), { db: snapshot, temporaryRoot }));
+      if (copied.sha256 !== reference.sha256 || copied.size !== reference.size) throw invalid("Restored attachment differs from retained snapshot");
+    }
+    if (!existingDatabase) await backupStorageDatabase(snapshot, filename);
+    const restored = openStorageDatabase(filename, { readOnly: true });
+    try {
+      if (!checkStorageIntegrity(restored).ok || canonicalFingerprint(logicalSnapshot(restored)) !== canonicalFingerprint(logicalSnapshot(snapshot))) throw invalid("Restored canonical state differs from retained snapshot");
+      await validateMigrationDatabase(restored, { target, packageRoot });
+      for (const reference of iterateAttachmentReferences(restored)) await verifyAttachmentFile(target, reference);
+    } finally { restored.close(); }
+    await assertOwnedStorageMaintenance(target);
+    const marker = alreadyActive ? existingMarker : await activateStorageVersionMarker(target, binding);
+    journal.phase = "ACTIVE";
+    await persist();
+    await verifyProjectRestoreJournal(target, operationId, { expectedOwnerId: await assertOwnedStorageMaintenance(target) });
+    return { restored: true, active: true, currentStateVerified: true, path: filename, retainedSnapshot: retained, references: manifest.references, marker, journalPath };
+  });
+}
+
+/** Resume a validated prepublication snapshot after confirmed local owner death. */
+export async function resumeProjectStorageRestore(target, { operationId, expectedOwnerId, writersQuiesced = false, packageRoot = getPackageRoot() } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Exclude all writers before restore resume"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  const verified = await verifyProjectRestoreJournal(target, operationId);
+  await assertStorageMaintenanceOwnerContinuity(target, { expectedOwnerId, recordedOwnerId: verified.journal.ownerId });
+  if (!["PREPARING", "READY", "PUBLISHING", "ACTIVE"].includes(verified.journal.phase)) throw invalid("Restore checkpoint does not support resume");
+  if (["PREPARING", "READY"].includes(verified.journal.phase)) await assertFreshOperationalState(target);
+  return resumeStorageMaintenance(target, { expectedOwnerId, writersQuiesced }, async () => {
+    const current = await verifyProjectRestoreJournal(target, operationId);
+    if (canonicalFingerprint(current.journal) !== canonicalFingerprint(verified.journal)) throw invalid("Restore journal changed during owner adoption");
+    await assertStorageMaintenanceOwnerContinuity(target, { expectedOwnerId: await assertOwnedStorageMaintenance(target), recordedOwnerId: current.journal.ownerId });
+    current.journal.ownerId = await assertOwnedStorageMaintenance(target);
+    await writeFileAtomic(await assertSafePath(current.root, "restore-journal.json"), `${JSON.stringify(current.journal, null, 2)}\n`);
+    if (current.journal.replacement) return publishArchivedStorageReplacement(target, operationId, { packageRoot });
+    if (current.journal.phase === "PREPARING") await validatePreparedRestore(target, current.root, current.journal, packageRoot);
+    if (current.journal.phase === "ACTIVE") {
+      const result = await verifyActiveProjectRestore(target, operationId, { expectedOwnerId: current.journal.ownerId, packageRoot });
+      await assertOwnedStorageMaintenance(target);
+      return { ...result, path: await assertSafePath(target, ".forgeloop/state.sqlite"), retainedSnapshot: current.snapshot,
+        journalPath: await assertSafePath(current.root, "restore-journal.json"), marker: current.marker };
+    }
+    return publishReadyRestore(target, current.root, current.journal, { packageRoot });
+  });
+}
+
+async function validatePreparedRestore(target, root, journal, packageRoot) {
+  await ensurePreparedRestoreSnapshot(target, root, journal);
+  const snapshotPath = await assertSafePath(root, "snapshot");
+  await withVerifiedProjectStorageBackup(snapshotPath, async ({ db: snapshot, manifest }) => {
+    await withVerifiedProjectStorageBackup(journal.source, async source => {
+      if (canonicalFingerprint(source.manifest) !== journal.sourceFingerprint
+        || canonicalFingerprint(logicalSnapshot(source.db)) !== canonicalFingerprint(logicalSnapshot(snapshot))) throw invalid("Prepared restore differs from its recorded source backup");
+      await validateMigrationDatabase(snapshot, { target: snapshotPath, packageRoot });
+    });
+    await assertOwnedStorageMaintenance(target);
+    Object.assign(journal, { phase: "READY", snapshotFingerprint: canonicalFingerprint(manifest), binding: {
+      operationId: journal.operationId, databaseSchemaVersion: readStorageMeta(snapshot).schema_version,
+      sourceInventoryFingerprint: canonicalFingerprint({ database: manifest.databaseSha256, inventory: manifest.inventorySha256, references: manifest.references }) } });
+    await writeFileAtomic(await assertSafePath(root, "restore-journal.json"), `${JSON.stringify(journal, null, 2)}\n`);
+  });
+}
+
+export async function resumeReadyProjectStorageRestore(target, options = {}) {
+  const verified = await verifyProjectRestoreJournal(target, options.operationId);
+  if (verified.journal.phase !== "READY") throw invalid("This compatibility entry point requires READY");
+  return resumeProjectStorageRestore(target, options);
+}

package/src/storage/record-definitions.js

@@ -0,0 +1,45 @@
+import { taskActionPath, taskApprovalPath, taskExecutionPath } from "../core/task-paths.js";
+import { putAction, putApproval, putExecution } from "./repository.js";
+
+function definition({ table, idColumn, payloadId, pathBuilder, writer, conflictCode = null }) {
+  return Object.freeze({ table, idColumn, payloadId, pathBuilder, writer, conflictCode });
+}
+
+/**
+ * The indexed operational records share one namespace contract.  Keep their
+ * table columns, payload identity field, canonical path builder, and conflict
+ * classification together so reads, staging, listing, and commit dispatch do
+ * not grow separate action/approval/execution copies.
+ */
+export const RECORD_DEFINITIONS = Object.freeze({
+  action: definition({
+    table: "actions",
+    idColumn: "action_id",
+    payloadId: "actionId",
+    pathBuilder: taskActionPath,
+    writer: putAction,
+    conflictCode: "E_ACTION_STATE_MISMATCH",
+  }),
+  approval: definition({
+    table: "approvals",
+    idColumn: "approval_id",
+    payloadId: "approvalId",
+    pathBuilder: taskApprovalPath,
+    writer: putApproval,
+    conflictCode: "E_APPROVAL_ALREADY_RESOLVED",
+  }),
+  execution: definition({
+    table: "executions",
+    idColumn: "execution_id",
+    payloadId: "executionId",
+    pathBuilder: taskExecutionPath,
+    writer: putExecution,
+  }),
+});
+
+/** Native artifact schemas whose canonical path is an indexed record table. */
+export const RECORD_SCHEMA_KINDS = Object.freeze({
+  action: "action",
+  approval: "approval",
+  execution: "execution",
+});