@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.4

package/src/storage/migration-candidate.js

@@ -0,0 +1,398 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+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 { captureLegacySource, inventoryLegacySourceLayout, verifyLegacySourceCapture } from "./migration-source.js";
+import { assertOwnedStorageMaintenance, withStorageMaintenance } from "./maintenance.js";
+import { importProjectState } from "./importer.js";
+import { readSingletonImportSource, singletonExportPath } from "./singleton-import.js";
+import { LEGACY_TASK_ARTIFACT_PATHS } from "../core/task-paths.js";
+import { exportDatabase } from "./exporter.js";
+import { checkStorageIntegrity, openStorageDatabase, readStorageMeta } from "./connection.js";
+import { validateMigrationDatabase } from "./migration-validation.js";
+import { inspectMigrationSourcePartition } from "./migration-source-partition.js";
+import { iterateAttachmentReferences } from "./attachment-references.js";
+import { readStorageVersionMarker } from "./storage-marker.js";
+import { prepareMigrationAttachmentRoot, verifyMigrationAttachmentRoot } from "./migration-attachment-root.js";
+
+const PARITY_TABLES = Object.freeze({
+  tasks: "task_id", claims: "task_id, claim_norm", events: "task_id, seq",
+  actions: "task_id, action_id", approvals: "task_id, approval_id",
+  executions: "task_id, execution_id", task_artifacts: "task_id, kind, artifact_id", sessions: "session_id", attachment_references: "task_id, reference_id",
+});
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_MIGRATION_PARITY_INVALID" }); }
+
+function validationSummary(validation) {
+  return { taskCount: validation.tasks.length, taskInventoryFingerprint: canonicalFingerprint(validation.tasks), schemas: validation.schemas };
+}
+
+async function writeTaskInventory(db, directory, validation) {
+  const filename = await assertSafePath(directory, "task-inventory.ndjson");
+  const taskRow = db.prepare("SELECT task_key, state_json FROM tasks WHERE task_id = ?");
+  async function* records() {
+    for (const task of validation.tasks) {
+      const row = taskRow.get(task.taskId);
+      yield `${JSON.stringify({ ...task, taskKey: row.task_key, stateFingerprint: row.state_json === null ? null : canonicalFingerprint(JSON.parse(row.state_json)) })}\n`;
+    }
+  }
+  await writeFileAtomic(filename, records());
+  return { path: "task-inventory.ndjson", records: validation.tasks.length, sha256: await digestFile(filename) };
+}
+
+export function logicalSnapshot(db) {
+  const tables = {};
+  for (const [table, order] of Object.entries(PARITY_TABLES)) {
+    const hash = createHash("sha256");
+    let count = 0;
+    for (const row of db.prepare(`SELECT * FROM ${table} ORDER BY ${order}`).iterate()) {
+      hash.update(`${JSON.stringify(row)}\n`);
+      count += 1;
+    }
+    tables[table] = { count, sha256: hash.digest("hex") };
+  }
+  const { storage_format, storage_version, schema_version, protocol_version, active_session_id } = readStorageMeta(db);
+  return { tables, metadata: { storage_format, storage_version, schema_version, protocol_version, active_session_id } };
+}
+
+async function contentFingerprint(filename, ledger) {
+  if (!ledger) {
+    const text = await readFile(filename);
+    assertJsonBytes(text, filename);
+    if (!Buffer.from(text.toString("utf8"), "utf8").equals(text)) throw invalid(`Source is not valid UTF-8: ${filename}`);
+    const value = JSON.parse(text.toString("utf8"));
+    assertJsonLimits(value, filename);
+    return canonicalFingerprint(value);
+  }
+  const hash = createHash("sha256");
+  const input = createReadStream(filename);
+  async function* strictLines() {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let pending = "";
+    for await (const bytes of input) {
+      pending += decoder.decode(bytes, { stream: true });
+      let newline;
+      while ((newline = pending.indexOf("\n")) !== -1) {
+        yield pending.slice(0, newline);
+        pending = pending.slice(newline + 1);
+      }
+      assertJsonBytes(pending, filename);
+    }
+    pending += decoder.decode();
+    if (pending) yield pending;
+  }
+  try {
+    for await (const line of strictLines()) {
+      if (!line.trim()) continue;
+      assertJsonBytes(line, filename);
+      const value = JSON.parse(line);
+      assertJsonLimits(value, filename);
+      hash.update(`${canonicalFingerprint(value)}\n`);
+    }
+  } finally { input.destroy(); }
+  return hash.digest("hex");
+}
+
+async function capturedSingletonTaskId(captured) {
+  const singletonPaths = new Set(Object.entries(LEGACY_TASK_ARTIFACT_PATHS).filter(([kind]) => kind !== "session").map(([, filename]) => filename));
+  const hasSingleton = captured.manifest.files.some(file => [...singletonPaths].some(root => file.path === root || file.path.startsWith(`${root}/`)))
+    || captured.manifest.directories.some(directory => singletonPaths.has(directory));
+  return hasSingleton ? (await readSingletonImportSource(captured.source)).taskId : null;
+}
+
+async function verifyHistoricalManifestFiles(files, sourceRoot) {
+  const names=new Set();
+  for (const file of files) {
+    if (!file || typeof file.path !== "string" || file.path.split("/").some(part=>!part || part === "." || part === "..")
+      || file.path.includes("\\") || file.path.includes("\u0000") || names.has(file.path)
+      || !Number.isSafeInteger(file.size) || file.size < 0 || !/^[a-f0-9]{64}$/.test(file.sha256 ?? "")) throw invalid("Historical export manifest file binding is invalid");
+    names.add(file.path);
+    await lstat(await assertSafePath(sourceRoot,file.path));
+  }
+  return names;
+}
+
+/** Validate retained export metadata as a historical ledger prefix, never current authority. */
+async function verifyHistoricalExportManifest(source, reproduced) {
+  const read = async filename => {
+    const bytes=await readFile(filename);assertJsonBytes(bytes,"export manifest");
+    const value=JSON.parse(bytes.toString("utf8"));assertJsonLimits(value,"export manifest");return value;
+  };
+  const prior=await read(source), current=await read(reproduced);
+  if (prior.schemaVersion !== 1 || prior.taskId !== current.taskId || prior.taskKey !== current.taskKey
+    || !Number.isSafeInteger(prior.events) || prior.events < 0 || prior.events > current.events
+    || !Array.isArray(prior.claims) || prior.claims.some(claim=>typeof claim !== "string")
+    || !Array.isArray(prior.files) || !Array.isArray(prior.included)) throw invalid("Historical export manifest identity or shape is invalid");
+  const names = await verifyHistoricalManifestFiles(prior.files, path.dirname(source));
+  if (canonicalFingerprint([...names].sort()) !== canonicalFingerprint([...prior.included].sort())) throw invalid("Historical export manifest membership differs");
+  const ledger=prior.files.find(file=>file.path === "events.ndjson");
+  if (!ledger) throw invalid("Historical export manifest omits its ledger binding");
+  const hash=createHash("sha256");let remaining=ledger.size,lines=0,last=null;
+  const input=createReadStream(await assertSafePath(path.dirname(source),"events.ndjson"));
+  try {
+    for await (const chunk of input) {
+      if (!remaining) break;
+      const bytes=chunk.subarray(0,Math.min(chunk.length,remaining));hash.update(bytes);remaining-=bytes.length;
+      for (const byte of bytes) if (byte === 10) lines+=1;
+      last=bytes.at(-1);
+    }
+  } finally {input.destroy();}
+  if (remaining || hash.digest("hex") !== ledger.sha256 || lines !== prior.events || (ledger.size && last !== 10)) throw invalid("Historical export manifest ledger prefix differs");
+}
+
+async function checkSourceParity(captured, exported, db, mappings = []) {
+  const externalAttachments = [];
+  const signatureSources = new Map();
+  let filesCompared = 0;
+  const singletonTaskId = await capturedSingletonTaskId(captured);
+  for (const file of captured.manifest.files) {
+    if (file.path.endsWith("/statement.sigstore.json")) signatureSources.set(file.path, file);
+    if (file.path.startsWith(".forgeloop/.txn/") || file.path.endsWith("/events.ndjson.index.json")) continue;
+    if (file.path.startsWith(".forgeloop/attachments/")) { externalAttachments.push(file); continue; }
+    // The portable index is regenerated with session byte bindings. Imported
+    // session selection/association is compared through the canonical tables.
+    if (file.path === "export-index.json") continue;
+    const original = await assertSafePath(captured.source, file.path);
+    const reproduced = await assertSafePath(exported, singletonTaskId ? singletonExportPath(singletonTaskId, file.path) : file.path);
+    if (/^\.forgeloop\/task-state\/[a-f0-9]{64}\/export-manifest\.json$/.test(file.path)) {
+      await verifyHistoricalExportManifest(original,reproduced);filesCompared+=1;continue;
+    }
+    try { await lstat(reproduced); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      throw Object.assign(new Error(`Source has no canonical export mapping: ${file.path}`), { code: "E_STORAGE_MIGRATION_UNMAPPED_SOURCE" });
+    }
+    const ledger = file.path.endsWith("/events.ndjson");
+    const signature = file.path.endsWith("/statement.sigstore.json");
+    const fingerprint = filename => signature ? digestFile(filename) : contentFingerprint(filename, ledger);
+    if (await fingerprint(original) !== await fingerprint(reproduced)) throw invalid(`Source/export payload differs: ${file.path}`);
+    filesCompared += 1;
+  }
+  const sourceFiles = new Map(externalAttachments.map(file => [file.path, file]));
+  const covered = new Set();
+  const generated = new Map(mappings.flatMap(mapping => mapping.references.map(reference => [JSON.stringify([reference.taskId, reference.referenceId]), { reference, sourcePath: mapping.sourcePath }])));
+  let references = 0;
+  for (const reference of iterateAttachmentReferences(db)) {
+    references += 1;
+    const file = sourceFiles.get(reference.path);
+    if (file) {
+      if (file.size !== reference.size || file.sha256 !== reference.sha256) throw invalid("Canonical attachment reference disagrees with captured bytes");
+      covered.add(reference.path);
+    } else {
+      const binding = generated.get(JSON.stringify([reference.taskId, reference.referenceId]));
+      const source = binding && signatureSources.get(binding.sourcePath);
+      if (!source || canonicalFingerprint(binding.reference) !== canonicalFingerprint(reference) || source.size !== reference.size || source.sha256 !== reference.sha256) throw invalid("Generated attachment has no captured signature binding");
+    }
+  }
+  const attachmentReferenceValidation = externalAttachments.length || references
+    ? (covered.size === externalAttachments.length ? "VERIFIED" : "NOT_VERIFIED") : "NOT_REQUIRED";
+  return { filesCompared, externalAttachments, attachmentReferenceValidation };
+}
+
+/** Prepare a closed private candidate; active layout publication is separate. */
+export async function prepareMigrationCandidate(target, { destination, writersQuiesced = false, packageRoot = getPackageRoot() } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Stop and exclude all writers before candidate preparation"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  return withStorageMaintenance(target, async () => {
+    const captured = await captureLegacySource(target, destination, { writersQuiesced });
+    return prepareCapturedCandidate(target, destination, captured, { packageRoot });
+  }, { retainOnError: true });
+}
+
+async function prepareCapturedCandidate(target, destination, captured, { packageRoot }) {
+    const candidatePath = await assertSafePath(captured.path, "candidate.sqlite");
+    const manifestPath = await assertSafePath(captured.path, "candidate-manifest.json");
+    const manifest = { schemaVersion: 2, status: "PREPARING", publicationReady: false, sourceInventoryFingerprint: canonicalFingerprint({ files: captured.manifest.files, directories: captured.manifest.directories }) };
+    const persist = () => writeFileAtomic(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    await persist();
+    let db;
+    let roundTrip;
+    try {
+      const attachments = await prepareMigrationAttachmentRoot(captured, await assertSafePath(captured.path, "candidate-attachments"), { packageRoot });
+      if (attachments.summary) manifest.attachmentPreparation = attachments.summary;
+      await persist();
+      const imported = await importProjectState(captured.source, candidatePath, { provenance: captured.manifest, preparedAttachments: attachments.preparedAttachments, convertSingleton: true });
+      db = imported.db;
+      const validation = await validateMigrationDatabase(db, { target, packageRoot });
+      const taskInventory = await writeTaskInventory(db, captured.path, validation);
+      const integrity = checkStorageIntegrity(db);
+      if (!integrity.ok) throw invalid("Candidate storage integrity failed");
+      const exported = await assertSafePath(captured.path, "parity-export");
+      await exportDatabase(db, exported, { attachmentRoot: attachments.root });
+      const parity = await checkSourceParity(captured, exported, db, attachments.mappings);
+      roundTrip = (await importProjectState(exported, await assertSafePath(captured.path, "parity.sqlite"))).db;
+      const logical = logicalSnapshot(db);
+      if (JSON.stringify(logical) !== JSON.stringify(logicalSnapshot(roundTrip))) throw invalid("Portable round trip changed canonical rows or metadata");
+      roundTrip.close(); roundTrip = null;
+      await verifyLegacySourceCapture(target, destination);
+      if (canonicalFingerprint(await inventoryLegacySourceLayout(target)) !== manifest.sourceInventoryFingerprint) throw invalid("Active legacy source changed during preparation");
+      const checkpoint = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+      if (checkpoint.busy !== 0 || checkpoint.log !== 0) throw invalid("Candidate checkpoint did not close all WAL contents");
+      const metadata = readStorageMeta(db);
+      db.close(); db = null;
+      const file = await open(candidatePath, "r+");
+      try { await file.sync(); } finally { await file.close(); }
+      manifest.status = "PREPARED";
+      Object.assign(manifest, { candidateSha256: await digestFile(candidatePath), metadata, logical, validation: validationSummary(validation), taskInventory, parity, importReport: { totals: imported.report.totals, importedTasks: imported.report.imported.length, skipped: imported.report.skipped, errors: imported.report.errors } });
+      await persist();
+      return { path: captured.path, candidatePath, manifest, attachmentRoot: attachments.root };
+    } catch (error) {
+      manifest.status = "FAILED";
+      manifest.error = { code: error.code ?? "E_STORAGE_MIGRATION_VALIDATION_FAILED", message: error.message, ...(error.errors ? { errors: error.errors } : {}), ...(error.report ? { report: error.report } : {}) };
+      try { await persist(); } catch { /* A retained PREPARING marker is never accepted as prepared. */ }
+      throw error;
+    } finally { roundTrip?.close(); db?.close(); }
+}
+
+async function readPreparedCandidateManifest(target, captured, allowSignatureObjectGrowth) {
+  const manifestBytes = await readFile(await assertSafePath(captured.path, "candidate-manifest.json"));
+  assertJsonBytes(manifestBytes, "candidate manifest");
+  const manifest = JSON.parse(manifestBytes.toString("utf8"));
+  assertJsonLimits(manifest, "candidate manifest");
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)
+    || manifest.schemaVersion !== 2 || manifest.status !== "PREPARED" || manifest.publicationReady !== false
+    || manifest.sourceInventoryFingerprint !== canonicalFingerprint({ files: captured.manifest.files, directories: captured.manifest.directories })) throw invalid("Retained candidate manifest is incomplete or inconsistent");
+  if (allowSignatureObjectGrowth) {
+    const marker = await readStorageVersionMarker(target);
+    if (!marker || !["CUTOVER_PENDING", "ACTIVE"].includes(marker.phase) || marker.sourceInventoryFingerprint !== manifest.sourceInventoryFingerprint) throw invalid("Pending signature growth requires a matching cutover marker");
+  }
+  return manifest;
+}
+
+async function assertCandidateFiles(captured, candidatePath, manifest) {
+  for (const suffix of ["-wal", "-shm"]) {
+    const sidecar = await assertSafePath(captured.path, `candidate.sqlite${suffix}`);
+    try { if (suffix === "-wal" && (await lstat(sidecar)).size !== 0) throw invalid("Candidate has unshipped WAL contents"); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  if (await digestFile(candidatePath) !== manifest.candidateSha256) throw invalid("Candidate database bytes disagree with retained digest");
+  if (manifest.taskInventory?.path !== "task-inventory.ndjson"
+    || await digestFile(await assertSafePath(captured.path, manifest.taskInventory.path)) !== manifest.taskInventory.sha256) throw invalid("Task inventory bytes disagree with retained digest");
+}
+
+/** Revalidate a retained private candidate; never treat its manifest as authority alone. */
+export async function verifyMigrationCandidate(target, destination, { packageRoot = getPackageRoot(), sourcePartition = false, allowAttachmentGrowth = false, allowSignatureObjectGrowth = false } = {}) {
+  const captured = await verifyLegacySourceCapture(target, destination);
+  const manifest = await readPreparedCandidateManifest(target, captured, allowSignatureObjectGrowth);
+  const currentSourceFingerprint = async () => sourcePartition
+    ? (await inspectMigrationSourcePartition(target, destination, { allowAttachmentGrowth, allowSignatureObjectGrowth })).sourceInventoryFingerprint
+    : canonicalFingerprint(await inventoryLegacySourceLayout(target));
+  if (await currentSourceFingerprint() !== manifest.sourceInventoryFingerprint) throw invalid("Active legacy source changed after candidate preparation");
+  const candidatePath = await assertSafePath(captured.path, "candidate.sqlite");
+  await assertCandidateFiles(captured, candidatePath, manifest);
+  const db = openStorageDatabase(candidatePath, { readOnly: true });
+  let recheck;
+  let sourceDb;
+  try {
+    recheck = await mkdtemp(path.join(captured.path, ".candidate-verification-"));
+    const integrity = checkStorageIntegrity(db);
+    if (!integrity.ok || canonicalFingerprint(logicalSnapshot(db)) !== canonicalFingerprint(manifest.logical)) throw invalid("Retained candidate failed integrity or logical parity");
+    const validation = await validateMigrationDatabase(db, { target, packageRoot });
+    if (canonicalFingerprint(validationSummary(validation)) !== canonicalFingerprint(manifest.validation)) throw invalid("Retained candidate domain projection changed");
+    const inventory = await writeTaskInventory(db, recheck, validation);
+    if (canonicalFingerprint(inventory) !== canonicalFingerprint(manifest.taskInventory)) throw invalid("Retained task inventory disagrees with canonical tasks");
+    const attachments = await prepareMigrationAttachmentRoot(captured, path.join(recheck, "attachments"), { packageRoot });
+    if (canonicalFingerprint(attachments.summary) !== canonicalFingerprint(manifest.attachmentPreparation ?? null)) throw invalid("Candidate attachment preparation disagrees with captured signatures");
+    const attachmentRoot = attachments.summary ? await assertSafePath(captured.path, "candidate-attachments") : captured.source;
+    if (attachments.summary) await verifyMigrationAttachmentRoot(attachmentRoot, attachments.references);
+    else if (await info(await assertSafePath(captured.path, "candidate-attachments"))) throw invalid("Unbound candidate attachment root");
+    sourceDb = (await importProjectState(captured.source, path.join(recheck, "source.sqlite"), { preparedAttachments: attachments.preparedAttachments, convertSingleton: true })).db;
+    if (canonicalFingerprint(logicalSnapshot(sourceDb)) !== canonicalFingerprint(logicalSnapshot(db))) throw invalid("Retained source/candidate canonical rows differ");
+    const exported = path.join(recheck, "export");
+    await exportDatabase(db, exported, { attachmentRoot });
+    if (canonicalFingerprint(await checkSourceParity(captured, exported, db, attachments.mappings)) !== canonicalFingerprint(manifest.parity)) throw invalid("Retained source/export parity changed");
+    await verifyLegacySourceCapture(target, destination);
+    if (await currentSourceFingerprint() !== manifest.sourceInventoryFingerprint) throw invalid("Active legacy source changed during candidate verification");
+    return { path: captured.path, candidatePath, manifest, attachmentRoot };
+  } finally { try { sourceDb?.close(); db.close(); } finally { if (recheck) await rm(recheck, { recursive: true, force: true }); } }
+}
+
+const CANDIDATE_FILES = Object.freeze(["candidate-manifest.json", "candidate.sqlite", "candidate.sqlite-wal", "candidate.sqlite-shm", "candidate-attachments", "task-inventory.ndjson", "parity-export", "parity.sqlite", "parity.sqlite-wal", "parity.sqlite-shm"]);
+async function info(filename) {
+  try { return await lstat(filename); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+async function syncRecoveryDirectory(directory) {
+  const handle = await open(directory, "r");
+  try { await handle.sync(); }
+  catch (error) { if (!["EINVAL", "EPERM", "EISDIR", "ENOTSUP", "UNKNOWN"].includes(error.code)) throw error; }
+  finally { await handle.close(); }
+}
+async function readRecoveryJson(filename, label) {
+  const bytes = await readFile(filename);
+  assertJsonBytes(bytes, label);
+  if (!Buffer.from(bytes.toString("utf8")).equals(bytes)) throw invalid(`${label} is not UTF-8`);
+  const value = JSON.parse(bytes.toString("utf8"));
+  assertJsonLimits(value, label);
+  return value;
+}
+
+/** Preserve interrupted candidate work using a resumable rename intent. */
+export async function resumeMigrationCandidate(target, destination, { writersQuiesced = false, packageRoot = getPackageRoot() } = {}) {
+  if (writersQuiesced !== true) throw invalid("Candidate recovery requires excluded writers");
+  await assertOwnedStorageMaintenance(target);
+  const captured = await verifyLegacySourceCapture(target, destination);
+  const root = captured.path;
+  const intentPath = await assertSafePath(root, "candidate-recovery.json");
+  let intent = await info(intentPath) ? await readRecoveryJson(intentPath, "candidate recovery") : null;
+  const manifestPath = await assertSafePath(root, "candidate-manifest.json");
+  const manifest = await info(manifestPath) ? await readRecoveryJson(manifestPath, "candidate manifest") : null;
+  if (!intent && manifest?.status === "PREPARED") return; // Publication verification remains authoritative.
+  if (await readStorageVersionMarker(target) || await info(await assertSafePath(target, ".forgeloop/state.sqlite"))
+    || await info(await assertSafePath(root, "publication"))) throw invalid("Candidate rebuild is forbidden after staging or cutover begins");
+  const fingerprint = canonicalFingerprint({ files: captured.manifest.files, directories: captured.manifest.directories });
+  if (canonicalFingerprint(await inventoryLegacySourceLayout(target)) !== fingerprint) throw invalid("Active legacy source differs from the capture");
+  if (!intent) {
+    if (manifest && (manifest.schemaVersion !== 2 || !["PREPARING", "FAILED"].includes(manifest.status)
+      || manifest.publicationReady !== false || manifest.sourceInventoryFingerprint !== fingerprint)) throw invalid("Interrupted candidate has unsupported source bindings");
+    const files = [];
+    for (const name of CANDIDATE_FILES) if (await info(await assertSafePath(root, name))) files.push(name);
+    if (!manifest && files.length) throw invalid("Candidate files without a preparation identity require reconciliation");
+    if (!files.length) return prepareCapturedCandidate(target, destination, captured, { packageRoot });
+    intent = { schemaVersion: 1, kind: "CANDIDATE_RECOVERY", operationId: randomUUID(), sourceInventoryFingerprint: fingerprint, files };
+    await writeFileAtomic(intentPath, `${JSON.stringify(intent)}\n`);
+  }
+  await retainInterruptedCandidate(target, root, intent, fingerprint);
+  return prepareCapturedCandidate(target, destination, captured, { packageRoot });
+}
+
+async function retainInterruptedCandidate(target, root, intent, fingerprint) {
+  const intentPath = await assertSafePath(root, "candidate-recovery.json");
+  if (intent.schemaVersion !== 1 || intent.kind !== "CANDIDATE_RECOVERY" || intent.sourceInventoryFingerprint !== fingerprint
+    || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(intent.operationId ?? "")
+    || !Array.isArray(intent.files) || !intent.files.length || intent.files.length !== new Set(intent.files).size
+    || intent.files.some(name => !CANDIDATE_FILES.includes(name))) throw invalid("Candidate recovery intent is malformed or changed");
+  const history = await assertSafePath(root, "candidate-history");
+  await mkdir(history, { recursive: true });
+  const attempt = await assertSafePath(history, intent.operationId);
+  await mkdir(attempt, { recursive: true });
+  await syncRecoveryDirectory(root);
+  await syncRecoveryDirectory(history);
+  await syncRecoveryDirectory(attempt);
+  if ((await readdir(attempt)).some(name => !intent.files.includes(name))) throw invalid("Candidate history has unexpected entries");
+  for (const name of CANDIDATE_FILES) {
+    const source = await assertSafePath(root, name);
+    const destinationPath = await assertSafePath(attempt, name);
+    const from = await info(source);
+    const to = await info(destinationPath);
+    if (!intent.files.includes(name)) { if (from || to) throw invalid("Unexpected candidate files appeared during recovery"); continue; }
+    if (Boolean(from) === Boolean(to)) throw invalid("Candidate recovery file is missing or duplicated");
+    if (from) {
+      await assertOwnedStorageMaintenance(target);
+      await rename(source, destinationPath);
+      await syncRecoveryDirectory(root);
+      await syncRecoveryDirectory(attempt);
+    }
+  }
+  await syncRecoveryDirectory(history);
+  const receipt = await assertSafePath(attempt, "recovery.json");
+  if (await info(receipt)) throw invalid("Candidate recovery receipt already exists");
+  await rename(intentPath, receipt);
+  await syncRecoveryDirectory(root);
+  await syncRecoveryDirectory(attempt);
+
+}

package/src/storage/migration-publication.js

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, readdir, 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 { assertJsonBytes, assertJsonLimits } from "../core/json-safety.js";
+import { assertOwnedStorageMaintenance, withStorageMaintenance } from "./maintenance.js";
+import { logicalSnapshot, verifyMigrationCandidate } from "./migration-candidate.js";
+import { backupProjectStorage, verifyProjectStorageBackup } from "./project-backup.js";
+import { openStorageDatabase, readStorageMeta } from "./connection.js";
+import { inspectMigrationSourcePartition } from "./migration-source-partition.js";
+import { readStorageVersionMarker } from "./storage-marker.js";
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_MIGRATION_PUBLICATION_INVALID" }); }
+
+function requireAttachmentsVerified(candidate) {
+  if (!["NOT_REQUIRED", "VERIFIED"].includes(candidate.manifest.parity.attachmentReferenceValidation)) {
+    throw invalid("Attachment reference coverage must be validated before staging publication");
+  }
+}
+
+function assertPublicationJournal(journal, candidate, published, marker) {
+  if (!journal || journal.schemaVersion !== 1 || (!["STAGED", "ARCHIVING", "ARCHIVED"].includes(journal.phase) && !published) || journal.publicationReady !== published
+    || typeof journal.operationId !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(journal.operationId)
+    || journal.candidateSha256 !== candidate.manifest.candidateSha256
+    || journal.sourceInventoryFingerprint !== candidate.manifest.sourceInventoryFingerprint) throw invalid("Publication journal is incomplete or has changed bindings");
+  if (marker && (marker.operationId !== journal.operationId || marker.sourceInventoryFingerprint !== journal.sourceInventoryFingerprint)) throw invalid("Cutover marker belongs to another publication");
+}
+
+/** Revalidate a closed stage; no journal field alone authorizes publication. */
+export async function verifyMigrationPublicationStage(target, destination, options = {}) {
+  const marker = options.sourcePartition ? await readStorageVersionMarker(target) : null;
+  const allowSignatureObjectGrowth = Boolean(marker && ["CUTOVER_PENDING", "ACTIVE"].includes(marker.phase));
+  const directory = await assertSafePath(await assertSafePath(target, destination), "publication");
+  const bytes = await readFile(await assertSafePath(directory, "publication-journal.json"));
+  assertJsonBytes(bytes, "publication journal");
+  if (!Buffer.from(bytes.toString("utf8")).equals(bytes)) throw invalid("Publication journal is not UTF-8");
+  const journal = JSON.parse(bytes.toString("utf8"));
+  assertJsonLimits(journal, "publication journal");
+  const published = journal?.phase === "PUBLISHED" && options.allowPublished === true;
+  const candidate = await verifyMigrationCandidate(target, destination, { ...options, allowAttachmentGrowth: published, allowSignatureObjectGrowth });
+  requireAttachmentsVerified(candidate);
+  assertPublicationJournal(journal, candidate, published, marker);
+  if (journal.phase === "ARCHIVED" || published) {
+    const partition = await inspectMigrationSourcePartition(target, destination, { allowAttachmentGrowth: published, allowSignatureObjectGrowth });
+    if (partition.roots.some(root => root.path !== ".forgeloop/attachments" && root.location === "ACTIVE")) throw invalid("Journal claims archival while legacy roots remain active");
+  }
+  const bundle = await assertSafePath(directory, "bundle");
+  await verifyProjectStorageBackup(bundle);
+  const manifest = JSON.parse(await readFile(await assertSafePath(bundle, "backup-manifest.json"), "utf8"));
+  if (journal.databaseSha256 !== manifest.databaseSha256 || journal.inventorySha256 !== manifest.inventorySha256) throw invalid("Publication bundle bytes disagree with journal bindings");
+  const db = openStorageDatabase(await assertSafePath(bundle, "state.sqlite"), { readOnly: true });
+  try {
+    if (marker && marker.databaseSchemaVersion !== readStorageMeta(db).schema_version) throw invalid("Cutover marker schema disagrees with staged storage");
+    if (canonicalFingerprint(logicalSnapshot(db)) !== canonicalFingerprint(candidate.manifest.logical)) throw invalid("Publication bundle canonical rows differ from retained candidate");
+  } finally { db.close(); }
+  return { path: directory, bundle, journal };
+}
+
+/** Stage an independent publication copy; archiving/marker/activation are separate. */
+export async function stageMigrationPublication(target, destination, { writersQuiesced = false, packageRoot } = {}) {
+  if (writersQuiesced !== true) throw Object.assign(new Error("Stop and exclude writers before staging publication"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
+  return withStorageMaintenance(target, async () => {
+    const candidate = await verifyMigrationCandidate(target, destination, { packageRoot });
+    requireAttachmentsVerified(candidate);
+    const directory = await assertSafePath(candidate.path, "publication");
+    await mkdir(directory); // Exclusive: an interrupted stage requires explicit reconciliation.
+    const journalPath = await assertSafePath(directory, "publication-journal.json");
+    const journal = { schemaVersion: 1, operationId: randomUUID(), phase: "STAGING", publicationReady: false,
+      candidateSha256: candidate.manifest.candidateSha256, sourceInventoryFingerprint: candidate.manifest.sourceInventoryFingerprint };
+    const persist = () => writeFileAtomic(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
+    await persist();
+    let db;
+    try {
+      db = openStorageDatabase(candidate.candidatePath, { readOnly: true });
+      await backupProjectStorage(db, candidate.attachmentRoot, path.join(directory, "bundle"));
+      db.close(); db = null;
+      await verifyMigrationCandidate(target, destination, { packageRoot });
+      const bundleManifest = JSON.parse(await readFile(await assertSafePath(directory, "bundle/backup-manifest.json"), "utf8"));
+      Object.assign(journal, { phase: "STAGED", databaseSha256: bundleManifest.databaseSha256, inventorySha256: bundleManifest.inventorySha256 });
+      await persist();
+      return await verifyMigrationPublicationStage(target, destination, { packageRoot });
+    } catch (error) {
+      journal.phase = "FAILED";
+      journal.error = { code: error.code ?? "E_STORAGE_MIGRATION_PUBLICATION_INVALID", message: error.message };
+      try { await persist(); } catch { /* Retained STAGING cannot authorize publication. */ }
+      throw error;
+    } finally { db?.close(); }
+  }, { retainOnError: true });
+}
+
+async function present(filename) {
+  try { return await lstat(filename); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+/** Preserve an unpublished interrupted stage, then rebuild from verified sources. */
+export async function resumeMigrationPublicationStage(target, destination, { writersQuiesced = false, packageRoot } = {}) {
+  if (writersQuiesced !== true) throw invalid("Publication recovery requires excluded writers");
+  await assertOwnedStorageMaintenance(target);
+  const root = await assertSafePath(target, destination);
+  const directory = await assertSafePath(root, "publication");
+  const existing = await present(directory);
+  let journal;
+  if (existing) {
+    if (!existing.isDirectory()) throw invalid("Publication stage is not a directory");
+    const journalPath = await assertSafePath(directory, "publication-journal.json");
+    if (await present(journalPath)) {
+      const bytes = await readFile(journalPath);
+      assertJsonBytes(bytes, "publication journal");
+      if (!Buffer.from(bytes.toString("utf8")).equals(bytes)) throw invalid("Publication journal is not UTF-8");
+      journal = JSON.parse(bytes.toString("utf8"));
+      assertJsonLimits(journal, "publication journal");
+      if (["STAGED", "ARCHIVING", "ARCHIVED", "PUBLISHED"].includes(journal?.phase)) {
+        return verifyMigrationPublicationStage(target, destination, { packageRoot, sourcePartition: true, allowPublished: true });
+      }
+      if (journal?.schemaVersion !== 1 || !["STAGING", "FAILED"].includes(journal.phase) || journal.publicationReady !== false
+        || typeof journal.operationId !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(journal.operationId)) throw invalid("Interrupted stage has unsupported publication identity");
+    } else if ((await readdir(directory)).length !== 0) throw invalid("Nonempty publication without an identity requires reconciliation");
+  }
+  // A stage rebuild is forbidden after any cutover marker/database publication.
+  if (await readStorageVersionMarker(target) || await present(await assertSafePath(target, ".forgeloop/state.sqlite"))) throw invalid("Published or pending storage cannot be rebuilt from an old candidate");
+  const candidate = await verifyMigrationCandidate(target, destination, { packageRoot });
+  requireAttachmentsVerified(candidate);
+  if (journal && (journal.candidateSha256 !== candidate.manifest.candidateSha256
+    || journal.sourceInventoryFingerprint !== candidate.manifest.sourceInventoryFingerprint)) throw invalid("Interrupted stage differs from the retained candidate");
+  if (existing) {
+    await assertOwnedStorageMaintenance(target);
+    const history = await assertSafePath(root, "publication-history");
+    await mkdir(history, { recursive: true });
+    const attempt = await assertSafePath(history, randomUUID());
+    await mkdir(attempt); // Exclusive history allocation; never replace an older attempt.
+    await syncDirectory(root, { catchOpenErrors: false, catchCloseErrors: false });
+    await syncDirectory(history, { catchOpenErrors: false, catchCloseErrors: false });
+    await syncDirectory(attempt, { catchOpenErrors: false, catchCloseErrors: false });
+    const retained = await assertSafePath(attempt, "publication");
+    await rename(directory, retained);
+    await syncDirectory(attempt, { catchOpenErrors: false, catchCloseErrors: false });
+    await syncDirectory(root, { catchOpenErrors: false, catchCloseErrors: false });
+    await syncDirectory(history, { catchOpenErrors: false, catchCloseErrors: false });
+  }
+  return stageMigrationPublication(target, destination, { writersQuiesced, packageRoot });
+}

package/src/storage/migration-rollback-admission.js

@@ -0,0 +1,54 @@
+import { lstat } from "node:fs/promises";
+import { assertSafePath } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { openStorageDatabase } from "./connection.js";
+import { logicalSnapshot } from "./migration-candidate.js";
+import { verifyPublishedMigration } from "./migration-terminal.js";
+import { verifyMigrationPublicationStage } from "./migration-publication.js";
+import { inspectMigrationSourcePartition } from "./migration-source-partition.js";
+import { assertOwnedStorageMaintenance } from "./maintenance.js";
+import { withStorageSnapshot } from "./snapshot.js";
+function invalid(message) { return Object.assign(new Error(message), {code:"E_STORAGE_SOURCE_ROLLBACK_INVALID"}); }
+
+async function assertConnectionsClosed(target) {
+  await assertOwnedStorageMaintenance(target);
+  const filename=await assertSafePath(target,".forgeloop/state.sqlite");
+  try {if (!(await lstat(filename)).isFile()) throw invalid("Source rollback admission requires an existing regular native database");}
+  catch(error){if(error.code === "ENOENT")throw invalid("Source rollback admission requires an existing native database");throw error;}
+  const checkpoint=openStorageDatabase(filename,{allowSchemaUpgrade:false});
+  try {
+    const result=checkpoint.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+    if (result.busy !== 0 || result.log !== 0) throw invalid("Busy SQLite checkpoint forbids source rollback admission");
+  } finally {checkpoint.close();}
+  for (const suffix of ["-wal","-shm"]) {
+    const filename=await assertSafePath(target,`.forgeloop/state.sqlite${suffix}`);
+    try {await lstat(filename);} catch (error) {if (error.code === "ENOENT") continue;throw error;}
+    throw invalid("Close all SQLite connections; retained sidecars forbid source rollback admission");
+  }
+}
+
+/** Owned checkpoint/content admission; not a historical-write proof or restoration token. */
+export async function verifyMigrationSourceRollbackAdmission(target,destination,{writersQuiesced=false,packageRoot}={}) {
+  if (writersQuiesced !== true) throw invalid("Source rollback admission requires excluded writers");
+  await assertOwnedStorageMaintenance(target);
+  await assertConnectionsClosed(target);
+  await verifyPublishedMigration(target,destination,{writersQuiesced,packageRoot});
+  const staged=await verifyMigrationPublicationStage(target,destination,{packageRoot,sourcePartition:true,allowPublished:true});
+  // Refuse added orphan bytes too: source restoration must not silently discard them.
+  await inspectMigrationSourcePartition(target,destination,{allowSignatureObjectGrowth:true});
+  const current=openStorageDatabase(await assertSafePath(target,".forgeloop/state.sqlite"),{readOnly:true});
+  let original;
+  let result;
+  try {
+    original=openStorageDatabase(await assertSafePath(staged.bundle,"state.sqlite"),{readOnly:true});
+    result = await withStorageSnapshot(current,async snapshot=>{
+      const fingerprint=canonicalFingerprint(logicalSnapshot(snapshot));
+      if (fingerprint !== canonicalFingerprint(logicalSnapshot(original))) throw invalid("Accepted native changes forbid preserved-source restoration");
+      await assertOwnedStorageMaintenance(target);
+      return {operationId:staged.journal.operationId,unchangedCanonicalSnapshot:true,fingerprint,restored:false,historicalWritesExcluded:false};
+    });
+  } finally {try {original?.close();} finally {current.close();}}
+  await assertConnectionsClosed(target);
+  await assertOwnedStorageMaintenance(target);
+  return result;
+}