@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/src/storage/maintenance-owner.js

@@ -0,0 +1,42 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { assertSafePath, assertRegularProjectFileIdentity, isPathWithin, realpathWithTransientWindowsRetry } from "../core/filesystem.js";
+
+export const MAINTENANCE_OWNER_ID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u;
+
+async function readOwnerBytes(handle) {
+    const buffer = Buffer.alloc(65537);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      const result = await handle.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+      if (result.bytesRead === 0) break;
+      bytesRead += result.bytesRead;
+    }
+  return buffer.subarray(0, bytesRead);
+}
+
+export async function readMaintenanceOwner(target, relativePath = ".forgeloop/.storage-maintenance/owner.json") {
+  const filename = await assertSafePath(target, relativePath);
+  const invalid = () => Object.assign(new Error("Maintenance owner identity is malformed or unsupported"), { code: "E_STORAGE_MAINTENANCE_OWNER_INVALID" });
+  const root = await realpathWithTransientWindowsRetry(target);
+  const observed = await lstat(filename, { bigint: true });
+  if (!observed.isFile() || !isPathWithin(root, await realpathWithTransientWindowsRetry(filename))) throw invalid();
+  let handle;
+  try { handle = await open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)); }
+  catch (error) { if (error.code === "ELOOP") throw invalid(); throw error; }
+  try {
+    await assertRegularProjectFileIdentity(handle, filename, observed, root, invalid);
+    const bytes = await readOwnerBytes(handle);
+    if (bytes.length > 65536) throw invalid();
+    const text = bytes.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(bytes)) throw invalid();
+    let value;
+    try { value = JSON.parse(text); } catch { throw invalid(); }
+    if (!value || typeof value !== "object" || Array.isArray(value)
+      || value.schemaVersion !== 1 || typeof value.ownerId !== "string" || !MAINTENANCE_OWNER_ID.test(value.ownerId)
+      || !Number.isInteger(value.pid) || value.pid < 1
+      || typeof value.acquiredAt !== "string" || !Number.isFinite(Date.parse(value.acquiredAt))
+      || (value.hostname !== undefined && (typeof value.hostname !== "string" || !value.hostname || value.hostname.length > 255))) throw invalid();
+    return { value, text };
+  } finally { await handle.close(); }
+}

package/src/storage/maintenance.js

@@ -0,0 +1,310 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readdir, rename, rmdir, unlink } from "node:fs/promises";
+import os from "node:os";
+import { assertSafePath } from "../core/filesystem.js";
+import { MAINTENANCE_OWNER_ID, readMaintenanceOwner } from "./maintenance-owner.js";
+import { archiveMaintenanceOwner, claimMaintenanceHandoff, publishMaintenanceOwner } from "./maintenance-handoff.js";
+
+const EXCLUSION = ".forgeloop/.storage-maintenance";
+const EXCLUSION_STAGING_PREFIX = `${EXCLUSION}.staging-`;
+// Single bounded retry for the Windows kill-to-observation race. Small enough
+// to stay inside resume timeouts, long enough for the kernel to release the
+// exited process handle. The retry re-reads the owner observation; it never
+// converts an absent observation into a death proof.
+const WINDOWS_OWNER_REQUERY_DELAY_MS = 250;
+const active = new AsyncLocalStorage();
+
+function busy(message) { return Object.assign(new Error(message), { code: "E_STORAGE_MAINTENANCE_IN_PROGRESS" }); }
+
+// Readonly admission can inspect maintenance ownership without loading the
+// filesystem durability kernel. Load it only when maintenance writes run.
+async function syncDirectory(directory) {
+  const durability = await import("./file-durability.js");
+  return durability.syncDirectory(directory);
+}
+
+async function createOwner(extra = {}) {
+  const owner = { schemaVersion: 1, ownerId: randomUUID(), pid: process.pid, hostname: os.hostname(), acquiredAt: new Date().toISOString(), ...extra };
+  if (process.platform !== "win32") return owner;
+  const {
+    isWindowsProcessIncarnationToken,
+    readWindowsProcessIncarnation,
+    WINDOWS_PROCESS_INCARNATION_KIND,
+    WINDOWS_PROCESS_INCARNATION_SCHEMA_VERSION,
+  } = await import("./windows-process-incarnation.js");
+  let observation;
+  try { observation = await readWindowsProcessIncarnation(process.pid); } catch { observation = null; }
+  if (!observation || observation.status !== "ALIVE" || observation.hasExited !== false || observation.pid !== process.pid) {
+    throw busy("Windows process incarnation is unavailable; maintenance owner publication refused");
+  }
+  const processIncarnation = {
+    kind: WINDOWS_PROCESS_INCARNATION_KIND,
+    pid: observation.pid,
+    schemaVersion: WINDOWS_PROCESS_INCARNATION_SCHEMA_VERSION,
+    startTimeTicks: observation.startTimeTicks,
+  };
+  if (!isWindowsProcessIncarnationToken(processIncarnation, { pid: process.pid })) {
+    throw busy("Windows process incarnation is malformed; maintenance owner publication refused");
+  }
+  owner.processIncarnation = processIncarnation;
+  return owner;
+}
+
+async function runOwnedMaintenance(target, directory, ownerData, callback, { retainOnError = false } = {}, deadOwner = null) {
+  const context = { directory, ownerId: ownerData.ownerId, active: true, releaseBlocked: false, deadOwner };
+  let completed = false;
+  try {
+    const result = await active.run(context, callback);
+    completed = true;
+    return result;
+  } finally {
+    context.active = false;
+    const retained = await readMaintenanceOwner(target);
+    if (retained.value.ownerId !== ownerData.ownerId) throw busy("Maintenance owner changed; retained exclusion cannot be released");
+    if ((completed || !retainOnError) && !context.releaseBlocked) {
+      if (JSON.stringify((await readdir(directory)).sort()) !== JSON.stringify(["owner.json"])) throw busy("Unexpected maintenance entries require reconciliation");
+      await unlink(await assertSafePath(target, `${EXCLUSION}/owner.json`));
+      await rmdir(directory);
+    }
+  }
+}
+
+export async function assertStorageMaintenanceInactive(target) {
+  const filename = await assertSafePath(target, EXCLUSION);
+  try { await lstat(filename); }
+  catch (error) { if (error.code === "ENOENT") return; throw error; }
+  throw busy("Storage maintenance excludes ordinary commands; inspect and resume the retained maintenance operation");
+}
+
+/** Destructive cutover steps must join the exact live maintenance owner. */
+export async function assertOwnedStorageMaintenance(target) {
+  const directory = await assertSafePath(target, EXCLUSION);
+  const owner = active.getStore();
+  if (!owner?.active || owner.directory !== directory || (await readMaintenanceOwner(target)).value.ownerId !== owner.ownerId) {
+    throw busy("Cutover requires the current owner-bound maintenance context");
+  }
+  return owner.ownerId;
+}
+
+/** Publication stages must retain admission exclusion even after a partial return. */
+export async function retainStorageMaintenance(target) {
+  await assertOwnedStorageMaintenance(target);
+  active.getStore().releaseBlocked = true;
+}
+
+/** Call only after the owning publication validator accepts terminal state. */
+export async function allowStorageMaintenanceRelease(target) {
+  await assertOwnedStorageMaintenance(target);
+  active.getStore().releaseBlocked = false;
+}
+
+async function removeUnpublishedExclusionStage(target, relativePath) {
+  let directory;
+  try { directory = await assertSafePath(target, relativePath); }
+  catch (error) { if (error.code === "ENOENT") return; throw error; }
+  let entries;
+  try { entries = await readdir(directory); }
+  catch (error) { if (error.code === "ENOENT") return; throw error; }
+  if (entries.some(entry => entry !== "owner.json")) return;
+  if (entries.includes("owner.json")) {
+    const ownerPath = await assertSafePath(target, `${relativePath}/owner.json`);
+    const info = await lstat(ownerPath);
+    if (!info.isFile()) return;
+    await unlink(ownerPath);
+  }
+  await rmdir(directory);
+  await syncDirectory(await assertSafePath(target, ".forgeloop"));
+}
+
+/**
+ * Persist the owner before atomically publishing the exclusion directory.
+ * `beforePublish` is an internal fault-injection seam used by crash tests.
+ */
+export async function publishMaintenanceExclusion(target, ownerData, { beforePublish } = {}) {
+  const relativeStage = `${EXCLUSION_STAGING_PREFIX}${randomUUID()}`;
+  const stage = await assertSafePath(target, relativeStage);
+  const destination = await assertSafePath(target, EXCLUSION);
+  await mkdir(stage, { mode: 0o700 });
+  try {
+    const ownerPath = await assertSafePath(target, `${relativeStage}/owner.json`);
+    const owner = await open(ownerPath, "wx", 0o600);
+    try {
+      await owner.writeFile(`${JSON.stringify(ownerData)}\n`);
+      await owner.sync();
+    } finally { await owner.close(); }
+    await syncDirectory(stage);
+    await syncDirectory(await assertSafePath(target, ".forgeloop"));
+    if (beforePublish) await beforePublish({ stage, destination });
+    try {
+      await lstat(destination);
+      throw busy("A retained storage maintenance operation requires reconciliation");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    try { await rename(stage, destination); }
+    catch (error) {
+      try {
+        await lstat(destination);
+        throw busy("A retained storage maintenance operation requires reconciliation");
+      } catch (inspectionError) {
+        if (inspectionError.code !== "ENOENT") throw inspectionError;
+        throw error;
+      }
+    }
+    await syncDirectory(await assertSafePath(target, ".forgeloop"));
+    return destination;
+  } catch (error) {
+    await removeUnpublishedExclusionStage(target, relativeStage).catch(() => {});
+    throw error;
+  }
+}
+
+/** Excludes version-aware clients. Legacy binaries still require operator exclusion. */
+export async function withStorageMaintenance(target, callback, options = {}) {
+  const directory = await assertSafePath(target, EXCLUSION);
+  const inherited = active.getStore();
+  if (inherited?.directory === directory) {
+    if (!inherited.active) throw busy("Maintenance context already closed");
+    if ((await readMaintenanceOwner(target)).value.ownerId !== inherited.ownerId) throw busy("Maintenance owner changed");
+    return callback();
+  }
+  const ownerData = await createOwner();
+  await publishMaintenanceExclusion(target, ownerData);
+  return runOwnedMaintenance(target, directory, ownerData, callback, options);
+}
+
+async function assertLocalOwnerDead(owner) {
+  if (owner.hostname !== os.hostname()) throw busy("Remote or unbound owner cannot be safely resumed on this host");
+  if (owner.processIncarnation !== undefined) {
+    if (process.platform !== "win32") throw busy("Maintenance owner process incarnation is unsupported or malformed");
+    const { isWindowsProcessIncarnationToken, readWindowsProcessIncarnation } =
+      await import("./windows-process-incarnation.js");
+    if (!isWindowsProcessIncarnationToken(owner.processIncarnation, { pid: owner.pid })) {
+      throw busy("Maintenance owner process incarnation is unsupported or malformed");
+    }
+    for (let attempt = 0; ; attempt += 1) {
+      let observation;
+      try { observation = await readWindowsProcessIncarnation(owner.pid); } catch { observation = null; }
+      if (observation && observation.pid === owner.pid) {
+        if (observation.status === "ALIVE" && observation.hasExited === false) {
+          if (observation.startTimeTicks === owner.processIncarnation.startTimeTicks) throw busy("Maintenance owner process is still present; resume refused");
+          return;
+        }
+        // Exit and kernel-absent observations carry their own proof: HasExited
+        // with matching ticks, or GetProcessById rejecting the PID entirely.
+        if (observation.status === "EXITED" || observation.status === "NOT_FOUND") return;
+      }
+      // A failed query (null/UNAVAILABLE) is ambiguous: it neither proves the
+      // process died nor that it lives. One bounded re-query rides out the
+      // transient kill-to-handle-lookup race; a second failure stays closed.
+      if (attempt >= 1) throw busy("Owner process identity is unavailable; resume refused");
+      await new Promise(resolve => setTimeout(resolve, WINDOWS_OWNER_REQUERY_DELAY_MS));
+    }
+  }
+  try { process.kill(owner.pid, 0); }
+  catch (error) { if (error.code === "ESRCH") return; throw busy("Owner liveness is unavailable; resume refused"); }
+  throw busy("Maintenance owner process is still present; resume refused");
+}
+
+/** Follow only the exact persisted adoption chain; never scan or infer owners. */
+export async function assertStorageMaintenanceOwnerContinuity(target, { expectedOwnerId, recordedOwnerId } = {}) {
+  if (!MAINTENANCE_OWNER_ID.test(expectedOwnerId ?? "") || !MAINTENANCE_OWNER_ID.test(recordedOwnerId ?? "")) throw busy("Owner continuity requires exact identities");
+  const context = active.getStore();
+  const proof = context?.active && context.ownerId === expectedOwnerId
+    && context.directory === await assertSafePath(target, EXCLUSION) ? context.deadOwner : null;
+  let owner = (await readMaintenanceOwner(target)).value;
+  if (owner.ownerId !== expectedOwnerId) throw busy("Current maintenance owner differs from continuity request");
+  const visited = new Set();
+  for (let depth = 0; depth < 64; depth += 1) {
+    if (owner.hostname !== os.hostname() || visited.has(owner.ownerId)) throw busy("Maintenance owner history is remote or cyclic");
+    visited.add(owner.ownerId);
+    if (owner.ownerId === recordedOwnerId) return;
+    if (!MAINTENANCE_OWNER_ID.test(owner.resumedFrom ?? "")) throw busy("Recorded operation owner is outside maintenance adoption history");
+    const previousRelative = `.forgeloop/storage-maintenance-history/${owner.resumedFrom}.json`;
+    const previous = await readMaintenanceOwner(target, previousRelative);
+    if (previous.value.ownerId !== owner.resumedFrom) throw busy("Maintenance owner history identity differs from its pathname");
+    if (context?.active && proof?.ownerId === previous.value.ownerId) {
+      // Adoption already observed this exact owner's death. A later process
+      // may reuse its PID; only unchanged bytes in this live scope retain proof.
+      if (previous.text !== proof.text) throw busy("Verified dead owner archive changed");
+    } else {
+      await assertLocalOwnerDead(previous.value);
+      const rechecked = await readMaintenanceOwner(target, previousRelative);
+      if (rechecked.text !== previous.text || rechecked.value.ownerId !== previous.value.ownerId) {
+        throw busy("Verified dead owner archive changed during liveness verification");
+      }
+      owner = rechecked.value;
+      continue;
+    }
+    owner = previous.value;
+  }
+  throw busy("Maintenance owner history exceeds bounded recovery depth");
+}
+
+async function archiveUnboundLegacyHandoff(target, expectedOwnerId) {
+  const relative = `${EXCLUSION}/handoff`;
+  const source = await assertSafePath(target, relative);
+  let info;
+  try { info = await lstat(source); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  if (!info.isDirectory()) throw busy("Unbound legacy handoff is not a directory; reconciliation refused");
+  const entries = (await readdir(source, { withFileTypes: true }))
+    .map(entry => ({ name: entry.name, type: entry.isDirectory() ? "directory" : entry.isFile() ? "file" : entry.isSymbolicLink() ? "symlink" : "other" }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  const root = await assertSafePath(target, ".forgeloop/storage-maintenance-history/unbound-handoffs");
+  await mkdir(root, { recursive: true });
+  const archivedName = `${expectedOwnerId}-${randomUUID()}`;
+  const archive = await assertSafePath(target, `.forgeloop/storage-maintenance-history/unbound-handoffs/${archivedName}`);
+  const receiptPath = await assertSafePath(target, `.forgeloop/storage-maintenance-history/unbound-handoffs/${archivedName}.json`);
+  try { await lstat(archive); throw busy("Legacy handoff archive identity already exists"); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  await rename(source, archive);
+  const durability = await import("./file-durability.js");
+  await durability.syncDirectory(await assertSafePath(target, EXCLUSION));
+  await durability.syncDirectory(root);
+  const receipt = {
+    schemaVersion: 1,
+    kind: "UNBOUND_LEGACY_MAINTENANCE_HANDOFF_ARCHIVE",
+    previousOwnerId: expectedOwnerId,
+    sourcePath: relative,
+    archivePath: `.forgeloop/storage-maintenance-history/unbound-handoffs/${archivedName}`,
+    archivedAt: new Date().toISOString(),
+    entries,
+    interpretation: "Opaque legacy bytes preserved by atomic rename; no ownership or liveness is inferred from the archived contents.",
+  };
+  const handle = await open(receiptPath, "wx", 0o600);
+  try { await handle.writeFile(`${JSON.stringify(receipt)}\n`); await handle.sync(); }
+  finally { await handle.close(); }
+  await durability.syncDirectory(root);
+  return receipt;
+}
+
+/** Adopt a retained dead local owner without dropping the exclusion. */
+export async function resumeStorageMaintenance(target, { expectedOwnerId, writersQuiesced = false, acknowledgeUnboundHandoff = false } = {}, callback) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Stop and exclude all writers before maintenance resume"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  if (typeof callback !== "function" || typeof expectedOwnerId !== "string" || !MAINTENANCE_OWNER_ID.test(expectedOwnerId)) throw busy("Resume requires an exact owner identity and recovery operation");
+  const previous = await readMaintenanceOwner(target);
+  if (previous.value.ownerId !== expectedOwnerId) throw busy("Retained owner differs from the requested resume identity");
+  await assertLocalOwnerDead(previous.value);
+  const directory = await assertSafePath(target, EXCLUSION);
+  let handoffPresent = false;
+  try { await lstat(await assertSafePath(target, `${EXCLUSION}/handoff`)); handoffPresent = true; }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  if (handoffPresent && acknowledgeUnboundHandoff !== true) throw busy("Unbound legacy handoff requires explicit --reconcile-unbound-handoff acknowledgement");
+  if (handoffPresent) await archiveUnboundLegacyHandoff(target, expectedOwnerId);
+  const ownerData = await createOwner({ resumedFrom: expectedOwnerId });
+  const rechecked = await readMaintenanceOwner(target);
+  if (rechecked.text !== previous.text) throw busy("Owner changed during resume preparation");
+  await assertLocalOwnerDead(rechecked.value);
+  await archiveMaintenanceOwner(target, previous);
+  if ((await readMaintenanceOwner(target)).text !== previous.text) throw busy("Owner changed during archival");
+  const claimedOwner = await claimMaintenanceHandoff(target, previous, ownerData, assertLocalOwnerDead);
+  if ((await readMaintenanceOwner(target)).text !== previous.text) throw busy("Owner changed during handoff");
+  await publishMaintenanceOwner(target, claimedOwner);
+  // Recovery failure retains this new owner's marker; later work must inspect
+  // the operation state instead of reopening normal commands over partial work.
+  return runOwnedMaintenance(target, directory, ownerData, callback, { retainOnError: true }, {
+    ownerId: previous.value.ownerId, text: previous.text,
+  });
+}

package/src/storage/metadata-json.js

@@ -0,0 +1,35 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { assertSafePath, assertRegularProjectFileIdentity, realpathWithTransientWindowsRetry } from "../core/filesystem.js";
+import { assertJsonBytes, assertJsonLimits, JSON_LIMITS } from "../core/json-safety.js";
+
+export const STORAGE_CATALOG_LIMITS = Object.freeze({ ...JSON_LIMITS, maxBytes: 64 * 1024 * 1024, maxArrayLength: 500_000 });
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_METADATA_INVALID" }); }
+
+/** Bound allocation before reading, including growth after the initial stat. */
+export async function readStorageMetadataJson(root, relative, { limits = STORAGE_CATALOG_LIMITS, optional = false } = {}) {
+  const filename = await assertSafePath(root, relative);
+  const resolvedRoot = await realpathWithTransientWindowsRetry(root);
+  let observed, file;
+  try { observed = await lstat(filename, { bigint: true }); file = await open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)); }
+  catch (error) { if (error.code === "ELOOP") throw invalid(`Storage metadata must be a regular file: ${relative}`); if (optional && error.code === "ENOENT") return null; throw error; }
+  try {
+    const info = await assertRegularProjectFileIdentity(file, filename, observed, resolvedRoot,
+      () => invalid(`Storage metadata must retain its admitted project file: ${relative}`));
+    assertJsonBytes({ byteLength: info.size }, relative, limits);
+    const chunks = [];
+    let size = 0;
+    for await (const bytes of file.createReadStream({ autoClose: false, highWaterMark: 64 * 1024 })) {
+      size += bytes.length;
+      assertJsonBytes({ byteLength: size }, relative, limits);
+      chunks.push(bytes);
+    }
+    const bytes = Buffer.concat(chunks, size);
+    const text = bytes.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(bytes)) throw invalid(`Storage metadata must be UTF-8: ${relative}`);
+    const value = JSON.parse(text);
+    assertJsonLimits(value, relative, limits);
+    return value;
+  } finally { await file.close(); }
+}

package/src/storage/migration-activate.js

@@ -0,0 +1,59 @@
+import { lstat, mkdir } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { iterateAttachmentReferences } from "./attachment-references.js";
+import { publishAttachmentFile, withVerifiedAttachmentFile } from "./attachment-files.js";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { assertOwnedStorageMaintenance } from "./maintenance.js";
+import { verifyMigrationPublicationStage } from "./migration-publication.js";
+import { logicalSnapshot } from "./migration-candidate.js";
+import { backupStorageDatabase } from "./backup.js";
+import { checkStorageIntegrity, openStorageDatabase, readStorageMeta } from "./connection.js";
+import { activateStorageVersionMarker, readStorageVersionMarker, writePendingStorageVersionMarker } from "./storage-marker.js";
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_MIGRATION_ACTIVATION_INVALID" }); }
+
+/** Activate only archived, verified storage inside the complete owner callback. */
+export async function activateArchivedMigration(target, destination, { writersQuiesced = false, packageRoot } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Exclude legacy writers before activation"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  await assertOwnedStorageMaintenance(target);
+  const staged = await verifyMigrationPublicationStage(target, destination, { packageRoot, sourcePartition: true });
+  if (staged.journal.phase !== "ARCHIVED") throw invalid("Activation requires completed, verified source archival");
+  const source = await assertSafePath(staged.bundle, "state.sqlite");
+  const db = openStorageDatabase(source, { readOnly: true });
+  const filename = await assertSafePath(target, ".forgeloop/state.sqlite");
+  const binding = { operationId: staged.journal.operationId, sourceInventoryFingerprint: staged.journal.sourceInventoryFingerprint, databaseSchemaVersion: readStorageMeta(db).schema_version };
+  try {
+    const existingMarker = await readStorageVersionMarker(target);
+    const alreadyActive = existingMarker?.phase === "ACTIVE";
+    if (alreadyActive) {
+      if (existingMarker.operationId !== binding.operationId || existingMarker.sourceInventoryFingerprint !== binding.sourceInventoryFingerprint
+        || existingMarker.databaseSchemaVersion !== binding.databaseSchemaVersion) throw invalid("Active marker belongs to a different cutover");
+    } else await writePendingStorageVersionMarker(target, binding);
+    const temporaryRoot = await assertSafePath(staged.path, "activation-attachments");
+    await mkdir(temporaryRoot, { recursive: true });
+    for (const reference of iterateAttachmentReferences(db)) {
+      await assertOwnedStorageMaintenance(target);
+      const copied = await withVerifiedAttachmentFile(staged.bundle, reference, sourceFilename => publishAttachmentFile(target, createReadStream(sourceFilename), { db, temporaryRoot }));
+      if (copied.size !== reference.size || copied.sha256 !== reference.sha256) throw invalid("Activated attachment differs from staged bytes");
+    }
+    let exists = false;
+    try { await lstat(filename); exists = true; } catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (!exists) {
+      if (alreadyActive) throw invalid("Active marker has lost its database; automatic recreation is forbidden");
+      await backupStorageDatabase(db, filename);
+    }
+    for (const suffix of ["-wal", "-shm"]) await assertSafePath(target, `.forgeloop/state.sqlite${suffix}`);
+    const published = openStorageDatabase(filename, { readOnly: true });
+    try {
+      if (!checkStorageIntegrity(published).ok || canonicalFingerprint(logicalSnapshot(published)) !== canonicalFingerprint(logicalSnapshot(db))) throw invalid("Published database differs from the validated staged snapshot");
+    } finally { published.close(); }
+    await assertOwnedStorageMaintenance(target);
+    await verifyMigrationPublicationStage(target, destination, { packageRoot, sourcePartition: true });
+    const marker = alreadyActive ? existingMarker : await activateStorageVersionMarker(target, binding);
+    const journalPath = await assertSafePath(staged.path, "publication-journal.json");
+    const journal = { ...staged.journal, phase: "PUBLISHED", publicationReady: true };
+    await writeFileAtomic(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
+    return { path: filename, marker, journal, source: staged.bundle };
+  } finally { db.close(); }
+}

package/src/storage/migration-archive.js

@@ -0,0 +1,57 @@
+import { mkdir, rename } from "node:fs/promises";
+import path from "node:path";
+import { syncDirectory } from "./file-durability.js";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { assertOwnedStorageMaintenance } from "./maintenance.js";
+import { verifyMigrationPublicationStage } from "./migration-publication.js";
+import { inspectMigrationSourcePartition } from "./migration-source-partition.js";
+import { openStorageDatabase, readStorageMeta } from "./connection.js";
+import { writePendingStorageVersionMarker } from "./storage-marker.js";
+
+/** Must remain inside the owner's complete cutover/recovery callback. */
+export async function archiveMigrationSources(target, destination, { writersQuiesced = false, packageRoot } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Legacy writers must be stopped and excluded before archival"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  await assertOwnedStorageMaintenance(target);
+  const staged = await verifyMigrationPublicationStage(target, destination, { packageRoot, sourcePartition: true });
+  const stagedDb = openStorageDatabase(await assertSafePath(staged.bundle, "state.sqlite"), { readOnly: true });
+  try {
+    await writePendingStorageVersionMarker(target, { operationId: staged.journal.operationId,
+      sourceInventoryFingerprint: staged.journal.sourceInventoryFingerprint, databaseSchemaVersion: readStorageMeta(stagedDb).schema_version });
+  } finally { stagedDb.close(); }
+  const journalPath = await assertSafePath(staged.path, "publication-journal.json");
+  const journal = { ...staged.journal, phase: "ARCHIVING" };
+  const persist = () => writeFileAtomic(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
+  await persist();
+  let partition = await inspectMigrationSourcePartition(target, destination);
+  await mkdir(partition.archive, { recursive: true });
+  await syncDirectory(path.dirname(partition.archive));
+  for (const root of partition.roots) {
+    // Referenced immutable object paths remain valid in the active project.
+    if (root.path === ".forgeloop/attachments" || root.location !== "ACTIVE") continue;
+    await assertOwnedStorageMaintenance(target);
+    partition = await inspectMigrationSourcePartition(target, destination);
+    const current = partition.roots.find(entry => entry.path === root.path);
+    if (current.location === "ARCHIVED") continue;
+    if (current.location !== "ACTIVE") throw Object.assign(new Error("Source location changed during archival"), { code: "E_STORAGE_MIGRATION_ARCHIVE_INVALID" });
+    const original = await assertSafePath(target, root.path);
+    const archived = await assertSafePath(partition.archive, root.path);
+    await mkdir(path.dirname(archived), { recursive: true });
+    await assertSafePath(partition.archive, root.path);
+    await rename(original, archived);
+    await syncDirectory(path.dirname(original));
+    await syncDirectory(path.dirname(archived));
+    await syncDirectory(partition.archive);
+    await syncDirectory(path.dirname(partition.archive));
+    partition = await inspectMigrationSourcePartition(target, destination);
+    journal.lastArchivedRoot = root.path;
+    await persist();
+  }
+  partition = await inspectMigrationSourcePartition(target, destination);
+  if (partition.roots.some(root => root.path !== ".forgeloop/attachments" && root.location === "ACTIVE")) {
+    throw Object.assign(new Error("Legacy source archival is incomplete"), { code: "E_STORAGE_MIGRATION_ARCHIVE_INVALID" });
+  }
+  journal.phase = "ARCHIVED";
+  await persist();
+  await verifyMigrationPublicationStage(target, destination, { packageRoot, sourcePartition: true });
+  return { ...staged, journal, partition };
+}

package/src/storage/migration-attachment-root.js

@@ -0,0 +1,61 @@
+import { createReadStream } from "node:fs";
+import { mkdir, readdir } from "node:fs/promises";
+import { assertSafePath } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { validateAttachmentReference } from "./attachment-binding.js";
+import { publishAttachmentFile, verifyAttachmentFile } from "./attachment-files.js";
+import { prepareRecordedLegacySignatures } from "./legacy-signature.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_ATTACHMENT_INVALID" }); }
+
+/** Build one private root for captured portable objects and legacy signatures. */
+export async function prepareMigrationAttachmentRoot(captured, root, { packageRoot } = {}) {
+  if (!captured.manifest.files.some(file => file.path.endsWith("/statement.sigstore.json"))) {
+    return { root: captured.source, preparedAttachments: null, summary: null, mappings: [], references: [] };
+  }
+  await mkdir(root);
+  const discovered = await prepareRecordedLegacySignatures(captured.source, root, captured.manifest.files, { packageRoot });
+  const index = await readStorageMetadataJson(captured.source, "export-index.json", { optional: true });
+  const portable = index?.attachments ?? [];
+  if (!Array.isArray(portable)) throw invalid("Invalid captured attachment catalog");
+  const references = new Map();
+  for (const value of portable) {
+    const reference = validateAttachmentReference(value);
+    const key = JSON.stringify([reference.taskId, reference.referenceId]);
+    if (references.has(key)) throw invalid("Duplicate captured attachment identity");
+    await verifyAttachmentFile(captured.source, reference);
+    const copied = await publishAttachmentFile(root, createReadStream(await assertSafePath(captured.source, reference.path)));
+    if (copied.size !== reference.size || copied.sha256 !== reference.sha256) throw invalid("Captured attachment changed during preparation");
+    references.set(key, reference);
+  }
+  const newReferences = [];
+  for (const reference of discovered.references) {
+    const key = JSON.stringify([reference.taskId, reference.referenceId]);
+    const prior = references.get(key);
+    if (prior) {
+      if (prior.path !== reference.path || prior.size !== reference.size || prior.sha256 !== reference.sha256) throw invalid("Captured alias conflicts with signature bytes");
+    } else { references.set(key, reference); newReferences.push(reference); }
+  }
+  const all = [...references.values()].sort((left, right) => JSON.stringify([left.taskId, left.referenceId]).localeCompare(JSON.stringify([right.taskId, right.referenceId])));
+  const summary = { root: "candidate-attachments", signatures: discovered.mappings.length, references: all.length, fingerprint: canonicalFingerprint({ references: all, mappings: discovered.mappings }) };
+  return { root, preparedAttachments: { root, references: newReferences }, summary, mappings: discovered.mappings, references: all };
+}
+
+/** A prepared root contains only the independently reproduced canonical objects. */
+export async function verifyMigrationAttachmentRoot(root, references) {
+  const expected = new Map();
+  for (const reference of references) {
+    validateAttachmentReference(reference);
+    const previous = expected.get(reference.sha256);
+    if (previous && previous.size !== reference.size) throw invalid("Candidate object has inconsistent size bindings");
+    expected.set(reference.sha256, reference);
+  }
+  for (const [relative, names] of [[".", [".forgeloop"]], [".forgeloop", ["attachments"]], [".forgeloop/attachments", ["objects"]]]) {
+    const entries = await readdir(await assertSafePath(root, relative));
+    if (canonicalFingerprint(entries.sort()) !== canonicalFingerprint(names)) throw invalid("Candidate attachment root has unexpected membership");
+  }
+  const entries = await readdir(await assertSafePath(root, ".forgeloop/attachments/objects"));
+  if (entries.length !== expected.size || entries.some(name => !expected.has(name))) throw invalid("Candidate attachment object membership changed");
+  for (const reference of expected.values()) await verifyAttachmentFile(root, reference);
+}