@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

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

@@ -0,0 +1,132 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir } from "node:fs/promises";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { openStorageDatabase } from "./connection.js";
+import { logicalSnapshot } from "./migration-candidate.js";
+import { verifyMigrationSourceRollbackAdmission } from "./migration-rollback-admission.js";
+import { assertOwnedStorageMaintenance, retainStorageMaintenance, resumeStorageMaintenance, assertStorageMaintenanceOwnerContinuity } from "./maintenance.js";
+import { backupProjectStorage, withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { readStorageVersionMarker } from "./storage-marker.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { validateMigrationDatabase } from "./migration-validation.js";
+function invalid(message) {return Object.assign(new Error(message),{code:"E_STORAGE_SOURCE_ROLLBACK_INVALID"});}
+async function operationRoot(target,destination) {
+ return assertSafePath(await assertSafePath(target,destination),"publication/source-rollback");
+}
+
+/** Retain a verified native backup before any source switch; never release exclusion. */
+export async function prepareMigrationSourceRollback(target,destination,options={}) {
+ const ownerId=await assertOwnedStorageMaintenance(target);
+ const admission=await verifyMigrationSourceRollbackAdmission(target,destination,options);
+ const marker=await readStorageVersionMarker(target);
+ const root=await operationRoot(target,destination);
+ await mkdir(root); // Existing/partial preparation requires explicit reconciliation.
+ await retainStorageMaintenance(target);
+ const journal={schemaVersion:1,kind:"MIGRATION_SOURCE_ROLLBACK",phase:"PREPARING",ownerId,operationId:admission.operationId,
+  sourceInventoryFingerprint:marker.sourceInventoryFingerprint,nativeMarker:marker,nativeFingerprint:admission.fingerprint};
+ const journalPath=await assertSafePath(root,"rollback-journal.json");
+ const persist=()=>writeFileAtomic(journalPath,`${JSON.stringify(journal,null,2)}\n`);
+ await persist();
+ const db=openStorageDatabase(await assertSafePath(target,".forgeloop/state.sqlite"),{readOnly:true});
+ try {await backupProjectStorage(db,target,await assertSafePath(root,"native-backup"));} finally {db.close();}
+ journal.nativeBackupFingerprint=await withVerifiedProjectStorageBackup(await assertSafePath(root,"native-backup"),async snapshot=>{
+  if (canonicalFingerprint(logicalSnapshot(snapshot.db)) !== admission.fingerprint) throw invalid("Retained native backup differs from rollback admission");
+  await validateMigrationDatabase(snapshot.db,{target,packageRoot:options.packageRoot});
+  return canonicalFingerprint(snapshot.manifest);
+ });
+ const after=await verifyMigrationSourceRollbackAdmission(target,destination,options);
+ if (after.fingerprint !== admission.fingerprint || canonicalFingerprint(await readStorageVersionMarker(target)) !== canonicalFingerprint(marker)) throw invalid("Native authority changed during rollback preparation");
+ await assertOwnedStorageMaintenance(target);
+ journal.phase="READY";await persist();
+ return verifyPreparedMigrationSourceRollback(target,destination,options);
+}
+
+async function backupRoot(root,journal) {
+ const name=journal.nativeBackupDirectory ?? "native-backup";
+ if (name !== "native-backup" && !/^native-backup-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(name)) throw invalid("Invalid retained backup directory");
+ return assertSafePath(root,name);
+}
+
+/** A READY label alone cannot authorize source restoration. */
+export async function verifyPreparedMigrationSourceRollback(target,destination,options={}) {
+ return verifyReadyPreparation(target,destination,options,false);
+}
+
+async function verifyReadyPreparation(target,destination,options,adoptOwner) {
+ const ownerId=await assertOwnedStorageMaintenance(target);
+ const admission=await verifyMigrationSourceRollbackAdmission(target,destination,options);
+ const root=await operationRoot(target,destination);
+ const journal=await readStorageMetadataJson(root,"rollback-journal.json");
+ if (!journal || journal.schemaVersion !== 1 || journal.kind !== "MIGRATION_SOURCE_ROLLBACK" || journal.phase !== "READY"
+  || (!adoptOwner && journal.ownerId !== ownerId) || journal.operationId !== admission.operationId || journal.nativeFingerprint !== admission.fingerprint
+  || journal.sourceInventoryFingerprint !== journal.nativeMarker?.sourceInventoryFingerprint
+  || canonicalFingerprint(journal.nativeMarker) !== canonicalFingerprint(await readStorageVersionMarker(target))) throw invalid("Rollback preparation binding or owner differs");
+ if (adoptOwner) await assertStorageMaintenanceOwnerContinuity(target,{expectedOwnerId:ownerId,recordedOwnerId:journal.ownerId});
+ await withVerifiedProjectStorageBackup(await backupRoot(root,journal),async snapshot=>{
+  if (canonicalFingerprint(snapshot.manifest) !== journal.nativeBackupFingerprint || canonicalFingerprint(logicalSnapshot(snapshot.db)) !== admission.fingerprint) throw invalid("Retained native rollback backup binding differs");
+  await validateMigrationDatabase(snapshot.db,{target,packageRoot:options.packageRoot});
+ });
+ await assertOwnedStorageMaintenance(target);
+ return {root,journal,nativeAuthorityRetained:true,restored:false};
+}
+
+/** Revalidate a retained READY backup under exact dead-owner adoption; never switch source. */
+export async function resumePreparedMigrationSourceRollback(target,destination,{expectedOwnerId,...options}={}) {
+ return resumeStorageMaintenance(target,{expectedOwnerId,writersQuiesced:options.writersQuiesced},()=>recoverOwnedMigrationSourceRollbackPreparation(target,destination,options));
+}
+
+/** Compose recovery inside an already adopted live owner; no caller-supplied ownership bypass. */
+export async function recoverOwnedMigrationSourceRollbackPreparation(target,destination,options={}) {
+ await assertOwnedStorageMaintenance(target);
+ await retainStorageMaintenance(target);
+ await recoverPreparingBackup(target,destination,options);
+ const verified=await verifyReadyPreparation(target,destination,options,true);
+ const ownerId=await assertOwnedStorageMaintenance(target);
+ const journal={...verified.journal,ownerId,previousOwnerId:verified.journal.ownerId === ownerId ? verified.journal.previousOwnerId : verified.journal.ownerId};
+ await writeFileAtomic(await assertSafePath(verified.root,"rollback-journal.json"),`${JSON.stringify(journal,null,2)}\n`);
+ return verifyPreparedMigrationSourceRollback(target,destination,options);
+}
+
+/** Preserve interrupted attempts; only a validated committed backup may become READY. */
+async function recoverPreparingBackup(target,destination,options) {
+ const root=await operationRoot(target,destination);
+ const journal=await readStorageMetadataJson(root,"rollback-journal.json");
+ if (journal?.phase === "READY") return;
+ const ownerId=await assertOwnedStorageMaintenance(target);
+ const admission=await verifyMigrationSourceRollbackAdmission(target,destination,options);
+ if (!journal || journal.schemaVersion !== 1 || journal.kind !== "MIGRATION_SOURCE_ROLLBACK" || journal.phase !== "PREPARING"
+  || journal.operationId !== admission.operationId || journal.nativeFingerprint !== admission.fingerprint
+  || journal.sourceInventoryFingerprint !== journal.nativeMarker?.sourceInventoryFingerprint
+  || canonicalFingerprint(journal.nativeMarker) !== canonicalFingerprint(await readStorageVersionMarker(target))) throw invalid("Interrupted rollback preparation binding differs");
+ await assertStorageMaintenanceOwnerContinuity(target,{expectedOwnerId:ownerId,recordedOwnerId:journal.ownerId});
+ let directory=await backupRoot(root,journal);
+ let exists=true;
+ try {if (!(await lstat(directory)).isDirectory()) throw invalid("Backup attempt must be a directory");}
+ catch(error){if(error.code !== "ENOENT") throw error;exists=false;}
+ const manifest=exists ? await readStorageMetadataJson(directory,"backup-manifest.json",{optional:true}) : null;
+ const journalPath=await assertSafePath(root,"rollback-journal.json");
+ const persist=()=>writeFileAtomic(journalPath,`${JSON.stringify(journal,null,2)}\n`);
+ if (manifest?.status !== "READY") {
+  // Never replace bytes from a prior incomplete attempt, including one with no manifest.
+  if (exists) {
+   journal.nativeBackupDirectory=`native-backup-${randomUUID()}`;
+   directory=await backupRoot(root,journal);
+  }
+  journal.previousOwnerId=journal.ownerId;journal.ownerId=ownerId;
+  await persist();
+  const db=openStorageDatabase(await assertSafePath(target,".forgeloop/state.sqlite"),{readOnly:true});
+  try {await backupProjectStorage(db,target,directory);} finally {db.close();}
+ }
+ const fingerprint=await withVerifiedProjectStorageBackup(directory,async snapshot=>{
+  if (canonicalFingerprint(logicalSnapshot(snapshot.db)) !== admission.fingerprint) throw invalid("Recovered backup differs from rollback admission");
+  await validateMigrationDatabase(snapshot.db,{target,packageRoot:options.packageRoot});
+  return canonicalFingerprint(snapshot.manifest);
+ });
+ if (journal.nativeBackupFingerprint && journal.nativeBackupFingerprint !== fingerprint) throw invalid("Interrupted backup fingerprint differs");
+ const after=await verifyMigrationSourceRollbackAdmission(target,destination,options);
+ if (after.fingerprint !== admission.fingerprint || canonicalFingerprint(await readStorageVersionMarker(target)) !== canonicalFingerprint(journal.nativeMarker)) throw invalid("Native authority changed during rollback recovery");
+ await assertOwnedStorageMaintenance(target);
+ journal.nativeBackupFingerprint=fingerprint;journal.phase="READY";
+ await persist();
+}

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

@@ -0,0 +1,183 @@
+import { lstat, 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 { canonicalFingerprint } from "../core/artifacts.js";
+import { assertOwnedStorageMaintenance, assertStorageMaintenanceOwnerContinuity, resumeStorageMaintenance, retainStorageMaintenance } from "./maintenance.js";
+import { verifyMigrationSourceRollbackStage } from "./migration-rollback-source-stage.js";
+import { LEGACY_SOURCE_ROOTS, inventoryLegacyArchiveLayout, inventoryLegacySourceLayout, inventoryStorageRoots, verifyLegacySourceCapture } from "./migration-source.js";
+import { openStorageDatabase } from "./connection.js";
+import { logicalSnapshot } from "./migration-candidate.js";
+import { withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { inventoryPresent, subsetInventory } from "./migration-source-partition.js";
+
+const NATIVE_ROOTS=[".forgeloop/state.sqlite",".forgeloop/storage-version.json",".forgeloop/attachments"];
+function invalid(message){return Object.assign(new Error(message),{code:"E_STORAGE_SOURCE_ROLLBACK_INVALID"});}
+async function exists(filename){try{await lstat(filename);return true;}catch(error){if(error.code === "ENOENT")return false;throw error;}}
+async function retainedRoot(target,destination){return assertSafePath(await assertSafePath(target,destination),"publication/source-rollback/source-publication");}
+async function moveExclusive(sourceRoot,destinationRoot,relative){
+ const source=await assertSafePath(sourceRoot,relative);
+ const destination=await assertSafePath(destinationRoot,relative);
+ if(await exists(destination))throw invalid(`Rollback publication refuses existing destination: ${relative}`);
+ await mkdir(path.dirname(destination),{recursive:true});
+ await assertSafePath(destinationRoot,relative);
+ await rename(source,destination);
+ await syncDirectory(path.dirname(source));await syncDirectory(path.dirname(destination));
+}
+
+/** Conditional pre-write rollback only: operator exclusion is explicit, not inferred from equality. */
+export async function publishMigrationSourceRollback(target,destination,{nativeWritesExcluded=false,...options}={}){
+ if(nativeWritesExcluded !== true)throw invalid("Exclude all post-migration native writes before preserved-source restoration");
+ const staged=await verifyMigrationSourceRollbackStage(target,destination,options);
+ const ownerId=await assertOwnedStorageMaintenance(target);
+ const root=await retainedRoot(target,destination);
+ await mkdir(root); // Preserve any interrupted publication instead of restarting over it.
+ await retainStorageMaintenance(target);
+ const native=await assertSafePath(root,"retained-native");await mkdir(native);
+ const journal={schemaVersion:1,kind:"MIGRATION_SOURCE_ROLLBACK_PUBLICATION",phase:"SWITCHING",ownerId,
+  operationId:staged.manifest.operationId,sourceInventoryFingerprint:staged.manifest.sourceInventoryFingerprint,
+  nativeFingerprint:staged.manifest.nativeFingerprint,nativeBackupFingerprint:staged.manifest.nativeBackupFingerprint,
+  nativeWritesExcludedByOperator:true,nativeInventory:await inventoryStorageRoots(target,NATIVE_ROOTS)};
+ const filename=await assertSafePath(root,"publication-journal.json");
+ const persist=()=>writeFileAtomic(filename,`${JSON.stringify(journal,null,2)}\n`);
+ await persist();
+ return finishPublication(target,destination,root,journal,options);
+}
+
+async function finishPublication(target,destination,root,journal,options){
+ const result=await continuePublication(target,destination,root,journal);
+ if(options.legacyRoot){
+  const {validateAndReleaseMigrationSourceRollback}=await import("./migration-rollback-release.js");
+  return validateAndReleaseMigrationSourceRollback(target,destination,{legacyRoot:options.legacyRoot});
+ }
+ return result;
+}
+
+async function continuePublication(target,destination,root,journal){
+ const native=await assertSafePath(root,"retained-native");
+ const source=await assertSafePath(path.dirname(root),"source-stage/source");
+ const filename=await assertSafePath(root,"publication-journal.json");
+ const persist=()=>writeFileAtomic(filename,`${JSON.stringify(journal,null,2)}\n`);
+ if(journal.phase === "SWITCHING"){
+  await verifyNativePartition(target,native,journal);
+  for(const relative of NATIVE_ROOTS){
+   await assertOwnedStorageMaintenance(target);
+   if(await exists(await assertSafePath(target,relative)))await moveExclusive(target,native,relative);
+  }
+  if(canonicalFingerprint(await inventoryStorageRoots(native,NATIVE_ROOTS)) !== canonicalFingerprint(journal.nativeInventory))throw invalid("Retained native bytes changed during source publication");
+  journal.phase="NATIVE_RETAINED";await persist();
+ }
+ if(journal.phase === "NATIVE_RETAINED"){
+  await verifySourcePartition(target,destination,source);
+  for(const relative of LEGACY_SOURCE_ROOTS){
+   await assertOwnedStorageMaintenance(target);
+   if(await exists(await assertSafePath(source,relative)))await moveExclusive(source,target,relative);
+  }
+  const captured=await verifyLegacySourceCapture(target,destination);
+  if(canonicalFingerprint(await inventoryLegacySourceLayout(target)) !== canonicalFingerprint({files:captured.manifest.files,directories:captured.manifest.directories}))throw invalid("Restored source differs from preserved capture");
+  journal.phase="RESTORED";await persist();
+ }
+ return verifyPublishedMigrationSourceRollback(target,destination);
+}
+
+async function verifyNativePartition(target,native,journal){
+ const active=await inventoryStorageRoots(target,NATIVE_ROOTS);
+ const retained=await inventoryStorageRoots(native,NATIVE_ROOTS);
+ for(const root of NATIVE_ROOTS){
+  const a=subsetInventory(active,root),r=subsetInventory(retained,root),expected=subsetInventory(journal.nativeInventory,root);
+  if(inventoryPresent(a) && inventoryPresent(r))throw invalid(`Native root duplicated during rollback: ${root}`);
+  if(canonicalFingerprint(inventoryPresent(a)?a:r) !== canonicalFingerprint(expected))throw invalid(`Native root bytes changed during rollback: ${root}`);
+ }
+}
+async function verifySourcePartition(target,destination,source){
+ const captured=await verifyLegacySourceCapture(target,destination);
+ const expected={files:captured.manifest.files,directories:captured.manifest.directories};
+ const active=await inventoryLegacySourceLayout(target),staged=await inventoryLegacyArchiveLayout(source);
+ for(const root of LEGACY_SOURCE_ROOTS){
+  const a=subsetInventory(active,root),s=subsetInventory(staged,root);
+  if(inventoryPresent(a) && inventoryPresent(s))throw invalid(`Source root duplicated during rollback: ${root}`);
+  if(canonicalFingerprint(inventoryPresent(a)?a:s) !== canonicalFingerprint(subsetInventory(expected,root)))throw invalid(`Source root bytes changed during rollback: ${root}`);
+ }
+}
+
+/** Adopt only a dead local owner; recover persisted locations rather than trusting phase labels. */
+async function verifyRecoveryJournalBindings(target, ownerId, journal, preparation, stage) {
+  if(!journal || journal.schemaVersion !== 1 || journal.kind !== "MIGRATION_SOURCE_ROLLBACK_PUBLICATION" || !["SWITCHING","NATIVE_RETAINED","RESTORED"].includes(journal.phase)
+   || journal.nativeWritesExcludedByOperator !== true || preparation?.schemaVersion !== 1 || preparation.kind !== "MIGRATION_SOURCE_ROLLBACK" || preparation.phase !== "READY"
+   || stage?.schemaVersion !== 1 || stage.kind !== "MIGRATION_SOURCE_ROLLBACK_STAGE" || stage.phase !== "READY")throw invalid("Rollback recovery journals are incomplete");
+  for(const recorded of [journal,preparation,stage]){
+   await assertStorageMaintenanceOwnerContinuity(target,{expectedOwnerId:ownerId,recordedOwnerId:recorded.ownerId});
+   for(const key of ["operationId","sourceInventoryFingerprint","nativeFingerprint","nativeBackupFingerprint"]){if(recorded[key] !== preparation[key])throw invalid("Rollback recovery bindings differ");}
+  }
+}
+
+export async function resumeMigrationSourceRollbackPublication(target,destination,{expectedOwnerId,nativeWritesExcluded=false,...options}={}){
+ if(nativeWritesExcluded !== true)throw invalid("Exclude all post-migration native writes before rollback recovery");
+ return resumeStorageMaintenance(target,{expectedOwnerId,writersQuiesced:options.writersQuiesced},async()=>{
+  await retainStorageMaintenance(target);
+  const ownerId=await assertOwnedStorageMaintenance(target);
+  const root=await retainedRoot(target,destination),operation=path.dirname(root);
+  const journal=await readStorageMetadataJson(root,"publication-journal.json");
+  const preparation=await readStorageMetadataJson(operation,"rollback-journal.json");
+  const stage=await readStorageMetadataJson(await assertSafePath(operation,"source-stage"),"source-stage.json");
+  await verifyRecoveryJournalBindings(target, ownerId, journal, preparation, stage);
+  const captured=await verifyLegacySourceCapture(target,destination);
+  if(canonicalFingerprint({files:captured.manifest.files,directories:captured.manifest.directories}) !== journal.sourceInventoryFingerprint)throw invalid("Rollback recovery capture differs");
+  const backupName=preparation.nativeBackupDirectory ?? "native-backup";
+  if(backupName !== "native-backup" && !/^native-backup-[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(backupName))throw invalid("Rollback backup path differs");
+  await withVerifiedProjectStorageBackup(await assertSafePath(operation,backupName),async snapshot=>{
+   if(canonicalFingerprint(snapshot.manifest) !== journal.nativeBackupFingerprint || canonicalFingerprint(logicalSnapshot(snapshot.db)) !== journal.nativeFingerprint)throw invalid("Rollback recovery backup differs");
+  });
+  const native=await assertSafePath(root,"retained-native"),source=await assertSafePath(operation,"source-stage/source");
+  if(journal.phase === "SWITCHING"){
+   await verifyNativePartition(target,native,journal);
+   // No source root may have been published before native retention completes.
+   const staged=await inventoryLegacyArchiveLayout(source);
+   staged.directories=staged.directories.filter(name=>LEGACY_SOURCE_ROOTS.some(root=>name === root || name.startsWith(`${root}/`)));
+   if(canonicalFingerprint(staged) !== journal.sourceInventoryFingerprint)throw invalid("Source stage differs before native retention");
+   const active=await inventoryLegacySourceLayout(target);
+   if(active.files.some(file=>!file.path.startsWith(".forgeloop/attachments/")) || active.directories.some(name=>name !== ".forgeloop/attachments" && !name.startsWith(".forgeloop/attachments/")))throw invalid("Source published before native retention");
+  }else{
+   for(const relative of [".forgeloop/state.sqlite",".forgeloop/state.sqlite-wal",".forgeloop/state.sqlite-shm",".forgeloop/storage-version.json"]){
+    if(await exists(await assertSafePath(target,relative)))throw invalid("Native authority reappeared before rollback recovery; source publication refused");
+   }
+   if(canonicalFingerprint(await inventoryStorageRoots(native,NATIVE_ROOTS)) !== canonicalFingerprint(journal.nativeInventory))throw invalid("Retained native inventory differs");
+   await verifySourcePartition(target,destination,source);
+  }
+  const databaseRoot=await exists(await assertSafePath(native,".forgeloop/state.sqlite")) ? native : target;
+  const db=openStorageDatabase(await assertSafePath(databaseRoot,".forgeloop/state.sqlite"),{readOnly:true});
+  try{if(canonicalFingerprint(logicalSnapshot(db)) !== journal.nativeFingerprint)throw invalid("Original native canonical state differs during rollback recovery");}finally{db.close();}
+  const checkpoint=openStorageDatabase(await assertSafePath(databaseRoot,".forgeloop/state.sqlite"));
+  try{const result=checkpoint.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();if(result.busy !== 0 || result.log !== 0)throw invalid("Busy original native database forbids rollback recovery");}finally{checkpoint.close();}
+  for(const suffix of ["-wal","-shm"]){if(await exists(await assertSafePath(databaseRoot,`.forgeloop/state.sqlite${suffix}`)))throw invalid("Close all original native connections before rollback recovery");}
+  // Adopt metadata only after bytes and the exact owner chain pass verification.
+  for(const [recorded,recordRoot,filename] of [[preparation,operation,"rollback-journal.json"],[stage,await assertSafePath(operation,"source-stage"),"source-stage.json"],[journal,root,"publication-journal.json"]]){
+   recorded.previousOwnerId=recorded.ownerId;recorded.ownerId=ownerId;
+   await writeFileAtomic(await assertSafePath(recordRoot,filename),`${JSON.stringify(recorded,null,2)}\n`);
+  }
+  return finishPublication(target,destination,root,journal,options);
+ });
+}
+
+/** Verify source bytes and retained original native files; keep exclusion for target-version validation. */
+export async function verifyPublishedMigrationSourceRollback(target,destination){
+ const ownerId=await assertOwnedStorageMaintenance(target);
+ const root=await retainedRoot(target,destination);
+ const journal=await readStorageMetadataJson(root,"publication-journal.json");
+ const preparation=await readStorageMetadataJson(await assertSafePath(await assertSafePath(target,destination),"publication/source-rollback"),"rollback-journal.json");
+ if(!journal || journal.schemaVersion !== 1 || journal.kind !== "MIGRATION_SOURCE_ROLLBACK_PUBLICATION" || journal.phase !== "RESTORED"
+  || journal.ownerId !== ownerId || journal.ownerId !== preparation.ownerId || journal.nativeWritesExcludedByOperator !== true
+  || journal.operationId !== preparation.operationId || journal.sourceInventoryFingerprint !== preparation.sourceInventoryFingerprint
+  || journal.nativeFingerprint !== preparation.nativeFingerprint || journal.nativeBackupFingerprint !== preparation.nativeBackupFingerprint)throw invalid("Source rollback publication binding differs");
+ const captured=await verifyLegacySourceCapture(target,destination);
+ const inventory={files:captured.manifest.files,directories:captured.manifest.directories};
+ if(canonicalFingerprint(inventory) !== journal.sourceInventoryFingerprint || canonicalFingerprint(await inventoryLegacySourceLayout(target)) !== canonicalFingerprint(inventory))throw invalid("Published source inventory differs");
+ const native=await assertSafePath(root,"retained-native");
+ if(canonicalFingerprint(await inventoryStorageRoots(native,NATIVE_ROOTS)) !== canonicalFingerprint(journal.nativeInventory))throw invalid("Retained original native bytes differ");
+ for(const relative of [".forgeloop/state.sqlite",".forgeloop/state.sqlite-wal",".forgeloop/state.sqlite-shm",".forgeloop/storage-version.json"]){
+  if(await exists(await assertSafePath(target,relative)))throw invalid("Native authority remains active after preserved-source restoration");
+ }
+ await assertOwnedStorageMaintenance(target);
+ return {root,native,source:target,journal,restored:true,nativeAuthorityRetained:true,historicalWritesExcluded:false,nativeWritesExcludedByOperator:true,targetVersionValidated:false};
+}

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

@@ -0,0 +1,66 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { assertOwnedStorageMaintenance, allowStorageMaintenanceRelease, retainStorageMaintenance } from "./maintenance.js";
+import { verifyPublishedMigrationSourceRollback } from "./migration-rollback-publication.js";
+import { withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { logicalSnapshot } from "./migration-candidate.js";
+
+const SUPPORTED_TARGET_COMMIT="ee9ce11123d4e728d3dbc92f5d62d4bf41bb79c5";
+function invalid(message){return Object.assign(new Error(message),{code:"E_STORAGE_SOURCE_ROLLBACK_VALIDATION_INVALID"});}
+function run(executable,args){
+ const result=spawnSync(executable,args,{encoding:"utf8",timeout:60000,maxBuffer:16*1024*1024});
+ if(result.status !== 0)throw invalid(`Rollback target validation failed: ${args[0]} (${result.error?.code ?? result.status ?? result.signal})`);
+ return result.stdout;
+}
+
+/** The supported target is explicit and source-pinned; arbitrary validator callbacks are not accepted. */
+export async function verifyRollbackLegacyTarget(legacyRoot){
+ if(typeof legacyRoot !== "string" || !legacyRoot)throw invalid("Rollback release requires a supported legacy checkout");
+ const root=await assertSafePath(path.resolve(legacyRoot),".");
+ const commit=run("git",["-C",root,"rev-parse","HEAD"]).trim();
+ if(commit !== SUPPORTED_TARGET_COMMIT || run("git",["-C",root,"status","--porcelain","--untracked-files=no"]).trim())throw invalid("Rollback target must be the clean supported pinned checkout");
+ const cli=await assertSafePath(root,"src/cli.js");
+ const metadata=await readStorageMetadataJson(root,"package.json");
+ if(metadata.name !== "@cassiomc1/forgeloop" || typeof metadata.version !== "string")throw invalid("Rollback target package identity differs");
+ return {root,cli,commit,version:metadata.version};
+}
+
+/** Release only after exact-target validation of every retained task and final byte checks. */
+export async function validateAndReleaseMigrationSourceRollback(target,destination,{legacyRoot}={}){
+ await retainStorageMaintenance(target);
+ const published=await verifyPublishedMigrationSourceRollback(target,destination);
+ const validator=await verifyRollbackLegacyTarget(legacyRoot);
+ const operation=path.dirname(published.root);
+ const preparation=await readStorageMetadataJson(operation,"rollback-journal.json");
+ const name=preparation.nativeBackupDirectory ?? "native-backup";
+ if(name !== "native-backup" && !/^native-backup-[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(name))throw invalid("Rollback release backup path differs");
+ const taskIds=await withVerifiedProjectStorageBackup(await assertSafePath(operation,name),snapshot=>{
+  if(canonicalFingerprint(snapshot.manifest) !== published.journal.nativeBackupFingerprint || canonicalFingerprint(logicalSnapshot(snapshot.db)) !== published.journal.nativeFingerprint)throw invalid("Rollback release native backup binding differs");
+  return snapshot.db.prepare("SELECT task_id FROM tasks ORDER BY task_id").all().map(row=>row.task_id);
+ });
+ const invoke=(command,args=[])=>{
+  let value;try{value=JSON.parse(run(process.execPath,[validator.cli,command,"--path",target,...args,"--json"]));}catch(error){if(error.code)throw error;throw invalid("Rollback target returned invalid JSON");}
+  return value;
+ };
+ const catalog=invoke("task-list");
+ if(!Array.isArray(catalog.tasks) || canonicalFingerprint(catalog.tasks.map(task=>task.taskId).sort()) !== canonicalFingerprint(taskIds))throw invalid("Rollback target task identities differ from native authority");
+ const validations=[];
+ for(const taskId of taskIds){
+  await assertOwnedStorageMaintenance(target);
+  const result=invoke("validate-protocol",["--task",taskId]);
+  if(result.status !== "VALID")throw invalid(`Rollback target protocol validation refused task ${taskId}`);
+  validations.push({taskId,status:result.status});
+ }
+ await verifyRollbackLegacyTarget(validator.root);
+ await verifyPublishedMigrationSourceRollback(target,destination);
+ const receipt={schemaVersion:1,kind:"MIGRATION_SOURCE_ROLLBACK_VALIDATION",status:"VALID",ownerId:await assertOwnedStorageMaintenance(target),
+  operationId:published.journal.operationId,sourceInventoryFingerprint:published.journal.sourceInventoryFingerprint,nativeFingerprint:published.journal.nativeFingerprint,
+  target:{commit:validator.commit,version:validator.version},tasks:validations};
+ await writeFileAtomic(await assertSafePath(published.root,"target-validation.json"),`${JSON.stringify(receipt,null,2)}\n`);
+ await verifyPublishedMigrationSourceRollback(target,destination);
+ await allowStorageMaintenanceRelease(target);
+ return {...published,targetVersionValidated:true,validation:receipt,maintenanceReleaseAllowed:true};
+}

package/src/storage/migration-rollback-source-stage.js

@@ -0,0 +1,103 @@
+import { randomUUID } from "node:crypto";
+import { cp, lstat, mkdir, rename } from "node:fs/promises";
+import { syncDirectory } from "./file-durability.js";
+import { assertSafePath, writeFileAtomic } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { assertOwnedStorageMaintenance, assertStorageMaintenanceOwnerContinuity, resumeStorageMaintenance, retainStorageMaintenance } from "./maintenance.js";
+import { verifyPreparedMigrationSourceRollback, recoverOwnedMigrationSourceRollbackPreparation } from "./migration-rollback-preparation.js";
+import { LEGACY_SOURCE_ROOTS, inventoryLegacyArchiveLayout, verifyLegacySourceCapture } from "./migration-source.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+
+function invalid(message) {return Object.assign(new Error(message),{code:"E_STORAGE_SOURCE_ROLLBACK_INVALID"});}
+async function verifySourceInventory(source, captured) {
+ const inventory=await inventoryLegacyArchiveLayout(source);
+ inventory.directories=inventory.directories.filter(name=>LEGACY_SOURCE_ROOTS.some(root=>name === root || name.startsWith(`${root}/`)));
+ if (canonicalFingerprint(inventory) !== canonicalFingerprint({files:captured.manifest.files,directories:captured.manifest.directories})) throw invalid("Rollback source stage membership or bytes differ from captured source");
+}
+
+/** Build an exclusive publication copy; preserve both source capture and active authority. */
+export async function stageMigrationSourceRollback(target,destination,options={}) {
+ const prepared=await verifyPreparedMigrationSourceRollback(target,destination,options);
+ const captured=await verifyLegacySourceCapture(target,destination);
+ const root=await assertSafePath(prepared.root,"source-stage");
+ await mkdir(root); // Existing and interrupted stages are retained, never replaced.
+ const manifest={schemaVersion:1,kind:"MIGRATION_SOURCE_ROLLBACK_STAGE",phase:"PREPARING",ownerId:prepared.journal.ownerId,
+  operationId:prepared.journal.operationId,sourceInventoryFingerprint:prepared.journal.sourceInventoryFingerprint,
+  nativeFingerprint:prepared.journal.nativeFingerprint,nativeBackupFingerprint:prepared.journal.nativeBackupFingerprint};
+ const filename=await assertSafePath(root,"source-stage.json");
+ const persist=()=>writeFileAtomic(filename,`${JSON.stringify(manifest,null,2)}\n`);
+ await persist();
+ const source=await assertSafePath(root,"source");
+ await cp(captured.source,source,{recursive:true,errorOnExist:true,force:false});
+ await verifySourceInventory(source,captured);
+ await verifyPreparedMigrationSourceRollback(target,destination,options);
+ await assertOwnedStorageMaintenance(target);
+ manifest.phase="READY";await persist();
+ return verifyMigrationSourceRollbackStage(target,destination,options);
+}
+
+/** A READY stage must still match captured bytes and the live prepared native authority. */
+export async function verifyMigrationSourceRollbackStage(target,destination,options={}) {
+ const prepared=await verifyPreparedMigrationSourceRollback(target,destination,options);
+ const root=await assertSafePath(prepared.root,"source-stage");
+ const manifest=await readStorageMetadataJson(root,"source-stage.json");
+ if (!manifest || manifest.schemaVersion !== 1 || manifest.kind !== "MIGRATION_SOURCE_ROLLBACK_STAGE" || manifest.phase !== "READY"
+  || manifest.ownerId !== prepared.journal.ownerId || manifest.operationId !== prepared.journal.operationId
+  || manifest.sourceInventoryFingerprint !== prepared.journal.sourceInventoryFingerprint
+  || manifest.nativeFingerprint !== prepared.journal.nativeFingerprint || manifest.nativeBackupFingerprint !== prepared.journal.nativeBackupFingerprint) throw invalid("Rollback source stage binding differs");
+ const captured=await verifyLegacySourceCapture(target,destination);
+ const source=await assertSafePath(root,"source");
+ await verifySourceInventory(source,captured);
+ await assertOwnedStorageMaintenance(target);
+ return {root,source,manifest,nativeAuthorityRetained:true,restored:false};
+}
+
+/** Recover a dead stage owner; incomplete copies are retained as independent attempts. */
+export async function resumeMigrationSourceRollbackStage(target,destination,{expectedOwnerId,...options}={}){
+ return resumeStorageMaintenance(target,{expectedOwnerId,writersQuiesced:options.writersQuiesced},()=>recoverOwnedMigrationSourceRollbackStage(target,destination,options));
+}
+
+/** Recover staging inside the already adopted maintenance owner. */
+export async function recoverOwnedMigrationSourceRollbackStage(target,destination,options={}){
+  await assertOwnedStorageMaintenance(target);
+  await retainStorageMaintenance(target);
+  const ownerId=await assertOwnedStorageMaintenance(target);
+  const operation=await assertSafePath(await assertSafePath(target,destination),"publication/source-rollback");
+  const root=await assertSafePath(operation,"source-stage");
+  const manifest=await readStorageMetadataJson(root,"source-stage.json");
+  const preparation=await readStorageMetadataJson(operation,"rollback-journal.json");
+  if(!manifest || manifest.schemaVersion !== 1 || manifest.kind !== "MIGRATION_SOURCE_ROLLBACK_STAGE" || !["PREPARING","READY"].includes(manifest.phase)
+   || preparation?.schemaVersion !== 1 || preparation.kind !== "MIGRATION_SOURCE_ROLLBACK" || preparation.phase !== "READY")throw invalid("Source stage recovery journals are incomplete");
+  for(const recorded of [manifest,preparation])await assertStorageMaintenanceOwnerContinuity(target,{expectedOwnerId:ownerId,recordedOwnerId:recorded.ownerId});
+  for(const key of ["operationId","sourceInventoryFingerprint","nativeFingerprint","nativeBackupFingerprint"]){if(manifest[key] !== preparation[key])throw invalid("Source stage recovery binding differs");}
+  const captured=await verifyLegacySourceCapture(target,destination);
+  const expected={files:captured.manifest.files,directories:captured.manifest.directories};
+  if(canonicalFingerprint(expected) !== manifest.sourceInventoryFingerprint)throw invalid("Source stage recovery capture differs");
+  const source=await assertSafePath(root,"source");
+  const partial=await inventoryLegacyArchiveLayout(source);
+  partial.directories=partial.directories.filter(name=>LEGACY_SOURCE_ROOTS.some(relative=>name === relative || name.startsWith(`${relative}/`)));
+  const files=new Set(expected.files.map(file=>file.path)),directories=new Set(expected.directories);
+  if(partial.files.some(file=>!files.has(file.path)) || partial.directories.some(name=>!directories.has(name)))throw invalid("Interrupted source stage contains unrecorded entries");
+  const complete=canonicalFingerprint(partial) === canonicalFingerprint(expected);
+  if(manifest.phase === "READY" && !complete)throw invalid("Completed source stage bytes changed; recovery refused");
+  await recoverOwnedMigrationSourceRollbackPreparation(target,destination,options);
+  manifest.previousOwnerId=manifest.ownerId;manifest.ownerId=ownerId;
+  const filename=await assertSafePath(root,"source-stage.json");
+  const persist=()=>writeFileAtomic(filename,`${JSON.stringify(manifest,null,2)}\n`);
+  if(!complete){
+   let present=true;try{await lstat(source);}catch(error){if(error.code !== "ENOENT")throw error;present=false;}
+   if(present){
+    manifest.retainedAttempt=randomUUID();await persist();
+    const history=await assertSafePath(root,"recovery-history");await mkdir(history,{recursive:true});
+    const attempt=await assertSafePath(history,manifest.retainedAttempt);await mkdir(attempt);
+    await syncDirectory(history);await syncDirectory(attempt);
+    await rename(source,await assertSafePath(attempt,"source"));
+    await syncDirectory(root);await syncDirectory(attempt);
+   }else await persist();
+   await cp(captured.source,source,{recursive:true,errorOnExist:true,force:false});
+  }
+  await verifySourceInventory(source,captured);
+  await verifyPreparedMigrationSourceRollback(target,destination,options);
+  manifest.phase="READY";await persist();
+  return verifyMigrationSourceRollbackStage(target,destination,options);
+}

package/src/storage/migration-rollback.js

@@ -0,0 +1,43 @@
+import { assertSafePath } from "../core/filesystem.js";
+import { readStorageMetadataJson } from "./metadata-json.js";
+import { withStorageMaintenance, resumeStorageMaintenance } from "./maintenance.js";
+import { verifyRollbackLegacyTarget } from "./migration-rollback-release.js";
+import { prepareMigrationSourceRollback, recoverOwnedMigrationSourceRollbackPreparation } from "./migration-rollback-preparation.js";
+import { stageMigrationSourceRollback, recoverOwnedMigrationSourceRollbackStage } from "./migration-rollback-source-stage.js";
+import { publishMigrationSourceRollback, resumeMigrationSourceRollbackPublication } from "./migration-rollback-publication.js";
+
+/** Supported conditional rollback entry point: verify the target before acquiring or altering storage. */
+export async function rollbackProjectStorage(target,{destination,legacyRoot,writersQuiesced=false,nativeWritesExcluded=false,packageRoot}={}){
+ if(typeof destination !== "string" || !destination || writersQuiesced !== true || nativeWritesExcluded !== true){
+  throw Object.assign(new Error("Source rollback requires a retained migration destination, excluded writers and excluded post-migration native writes"),{code:"E_CLI_INVOCATION_INVALID"});
+ }
+ const validator=await verifyRollbackLegacyTarget(legacyRoot);
+ const options={writersQuiesced,nativeWritesExcluded,packageRoot,legacyRoot:validator.root};
+ return withStorageMaintenance(target,async()=>{
+  await prepareMigrationSourceRollback(target,destination,options);
+  await stageMigrationSourceRollback(target,destination,options);
+  return publishMigrationSourceRollback(target,destination,options);
+ },{retainOnError:true});
+}
+
+/** Resume a recorded rollback under the exact dead owner, through target validation and release. */
+export async function resumeProjectStorageRollback(target,{destination,legacyRoot,expectedOwnerId,writersQuiesced=false,nativeWritesExcluded=false,packageRoot}={}){
+ if(typeof destination !== "string" || !destination || writersQuiesced !== true || nativeWritesExcluded !== true || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(expectedOwnerId ?? "")){
+  throw Object.assign(new Error("Rollback publication resume requires destination, exact owner, excluded writers and excluded native writes"),{code:"E_CLI_INVOCATION_INVALID"});
+ }
+ const validator=await verifyRollbackLegacyTarget(legacyRoot);
+ const options={writersQuiesced,nativeWritesExcluded,packageRoot,legacyRoot:validator.root};
+ const operation=await assertSafePath(await assertSafePath(target,destination),"publication/source-rollback");
+ const publication=await readStorageMetadataJson(operation,"source-publication/publication-journal.json",{optional:true});
+ if(publication)return resumeMigrationSourceRollbackPublication(target,destination,{expectedOwnerId,...options});
+ return resumeStorageMaintenance(target,{expectedOwnerId,writersQuiesced},async()=>{
+  if(await readStorageMetadataJson(operation,"source-publication/publication-journal.json",{optional:true}))throw Object.assign(new Error("Rollback publication appeared during recovery; retry publication recovery"),{code:"E_STORAGE_SOURCE_ROLLBACK_INVALID"});
+  const stage=await readStorageMetadataJson(operation,"source-stage/source-stage.json",{optional:true});
+  if(stage)await recoverOwnedMigrationSourceRollbackStage(target,destination,options);
+  else{
+   await recoverOwnedMigrationSourceRollbackPreparation(target,destination,options);
+   await stageMigrationSourceRollback(target,destination,options);
+  }
+  return publishMigrationSourceRollback(target,destination,options);
+ });
+}

package/src/storage/migration-source-partition.js

@@ -0,0 +1,56 @@
+import { assertSafePath } from "../core/filesystem.js";
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { LEGACY_SOURCE_ROOTS, inventoryLegacyArchiveLayout, inventoryLegacySourceLayout, verifyLegacySourceCapture } from "./migration-source.js";
+
+function invalid(message) { return Object.assign(new Error(message), { code: "E_STORAGE_MIGRATION_ARCHIVE_INVALID" }); }
+
+export function subsetInventory(inventory, root) {
+  const matches = name => name === root || name.startsWith(`${root}/`);
+  return { files: inventory.files.filter(file => matches(file.path)), directories: inventory.directories.filter(matches) };
+}
+
+export function inventoryPresent(inventory) { return inventory.files.length > 0 || inventory.directories.length > 0; }
+
+function assertAttachmentGrowth(root, original, active, archived, signatureObjects, allowAttachmentGrowth) {
+  if (inventoryPresent(archived)) throw invalid("Published attachment objects must remain active");
+  const originalFiles = new Map(original.files.map(file => [file.path, file]));
+  const activeFiles = new Map(active.files.map(file => [file.path, file]));
+  for (const file of original.files) {
+    if (canonicalFingerprint(activeFiles.get(file.path) ?? null) !== canonicalFingerprint(file)) throw invalid("Captured attachment bytes were lost or changed");
+  }
+  for (const file of active.files) {
+    if (originalFiles.has(file.path)) continue;
+    const match = /^\.forgeloop\/attachments\/objects\/([a-f0-9]{64})$/.exec(file.path);
+    if (!match || match[1] !== file.sha256) throw invalid("New attachment object path disagrees with immutable bytes");
+    if (!allowAttachmentGrowth && signatureObjects.get(file.sha256) !== file.size) throw invalid("Pending attachment growth has no captured signature binding");
+  }
+  if (original.directories.some(directory => !active.directories.includes(directory))
+    || active.directories.some(directory => !original.directories.includes(directory)
+      && ![root, `${root}/objects`].includes(directory))) throw invalid("Attachment directory membership is invalid");
+}
+
+/** Verify crash-time source location from bytes/membership, never journal claims. */
+export async function inspectMigrationSourcePartition(target, destination, { allowAttachmentGrowth = false, allowSignatureObjectGrowth = false } = {}) {
+  const captured = await verifyLegacySourceCapture(target, destination);
+  const archive = await assertSafePath(captured.path, "publication/legacy-archive");
+  const activeInventory = await inventoryLegacySourceLayout(target);
+  const archiveInventory = await inventoryLegacyArchiveLayout(archive);
+  const expected = { files: captured.manifest.files, directories: captured.manifest.directories };
+  const signatureObjects = new Map(expected.files.filter(file => /^\.forgeloop\/task-state\/[a-f0-9]{64}\/attestations\/(?:history\/cycle-[1-9][0-9]*\/)?statement\.sigstore\.json$/u.test(file.path)).map(file => [file.sha256, file.size]));
+  const roots = [];
+  for (const root of LEGACY_SOURCE_ROOTS) {
+    const original = subsetInventory(expected, root);
+    const active = subsetInventory(activeInventory, root);
+    const archived = subsetInventory(archiveInventory, root);
+    if ((allowAttachmentGrowth || allowSignatureObjectGrowth) && root === ".forgeloop/attachments") {
+      assertAttachmentGrowth(root, original, active, archived, signatureObjects, allowAttachmentGrowth);
+      roots.push({ path: root, location: inventoryPresent(active) ? "ACTIVE" : "ABSENT" });
+      continue;
+    }
+    if (inventoryPresent(active) && inventoryPresent(archived)) throw invalid(`Source exists in both active and archived locations: ${root}`);
+    const actual = inventoryPresent(active) ? active : archived;
+    if (canonicalFingerprint(actual) !== canonicalFingerprint(original)) throw invalid(`Source membership or bytes differ from retained capture: ${root}`);
+    roots.push({ path: root, location: inventoryPresent(active) ? "ACTIVE" : inventoryPresent(archived) ? "ARCHIVED" : "ABSENT" });
+  }
+  return { archive, sourceInventoryFingerprint: canonicalFingerprint(expected), roots };
+}