@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/orchestrators/snapshot/prune.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"prune.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/prune.ts"],"sourcesContent":["// Prune — label-scoped orphan sweep.\n//\n// Architecture § 4: the L3 prune orchestrator sweeps committed snapshot\n// byproduct images and snapshot-catalog directories whose meta document\n// is missing (partial artifacts) or unreadable. Stack-wide registry\n// pruning (engine resources / stack roster) is a sibling orchestrator and\n// lives elsewhere; this file is scoped to snapshot-adjacent artifacts.\n//\n// Image sweep scope (load-bearing): committed snapshot images are stamped\n// at `docker commit` time with `{managed, app, stack, role:\n// SNAPSHOT_IMAGE_ROLE}` (see `runtime/docker/container.ts`). Prune scopes\n// its sweep to THAT role so it reaps only snapshot byproducts. Plugin\n// BUILD images share `{managed, app, stack}` but carry the source\n// plugin's real role (or none) — never `SNAPSHOT_IMAGE_ROLE` — so the\n// sweep can NEVER untag a live stack's build images and force a silent\n// rebuild. Prune holds only `snapshot.reservation` (not stack liveness)\n// and is CLI-exposed, so this scoping is what keeps it safe against a\n// running stack.\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport type { ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport { SNAPSHOT_IMAGE_ROLE } from '../../runtime/docker/container.ts';\nimport { decodeJsonText } from '../../substrate/runtime/runtime-decode.ts';\nimport { SnapshotMetadataSchema, type SnapshotMetadata } from './descriptor.ts';\nimport { makePhaseFailer } from './phase-error.ts';\nimport { SNAPSHOTS_DIR_NAME } from './wipe.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\nexport class PrunePhaseError extends Schema.TaggedErrorClass<PrunePhaseError>()(\n\t'SnapshotPrunePhaseError',\n\t{\n\t\tphase: Schema.Literals([\n\t\t\t'enumerate-catalog',\n\t\t\t'read-meta',\n\t\t\t'sweep-images',\n\t\t\t'sweep-directories',\n\t\t]),\n\t\tdetail: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\nconst failPhase = makePhaseFailer(PrunePhaseError);\n\n// -----------------------------------------------------------------------------\n// Inputs\n// -----------------------------------------------------------------------------\n\nexport interface PruneInputs {\n\t/** Stack root containing the `snapshots/` catalog. */\n\treadonly stackRoot: string;\n\t/** App/stack scope for the committed-snapshot-image sweep. Prune\n\t *  narrows this to `role: SNAPSHOT_IMAGE_ROLE` before removing images,\n\t *  so only this stack's snapshot byproducts are swept — never its\n\t *  build images, never a sibling stack. */\n\treadonly imageLabelFilter: { readonly app: string; readonly stack: string };\n\treadonly runtime: ContainerRuntime;\n}\n\nexport interface PruneResult {\n\treadonly inspected: number;\n\treadonly reaped: ReadonlyArray<{\n\t\treadonly id: string;\n\t\t/** Reason the artifact was reaped. Currently only `'abandoned'`\n\t\t *  (partial artifact with no readable meta document). */\n\t\treadonly classification: 'abandoned';\n\t}>;\n\t/** Count of committed snapshot byproduct images removed (those stamped\n\t *  with `role: SNAPSHOT_IMAGE_ROLE` in this app/stack). Build images\n\t *  are never included. */\n\treadonly imagesSwept: number;\n}\n\n// -----------------------------------------------------------------------------\n// Helpers\n// -----------------------------------------------------------------------------\n\nconst readMetaOpt = (\n\tdir: string,\n): Effect.Effect<SnapshotMetadata | null, PrunePhaseError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst path = `${dir}/meta.json`;\n\t\tconst exists = yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false)));\n\t\tif (!exists) return null;\n\t\tconst text = yield* fs\n\t\t\t.readFileString(path)\n\t\t\t.pipe(Effect.catch(failPhase('read-meta', `read ${path} failed`)));\n\t\treturn yield* decodeJsonText(SnapshotMetadataSchema, text, {\n\t\t\tsource: path,\n\t\t\tmkError: () => null,\n\t\t}).pipe(Effect.catch(() => Effect.succeed(null)));\n\t});\n\n// -----------------------------------------------------------------------------\n// Top-level prune\n// -----------------------------------------------------------------------------\n\n/**\n * Walk the snapshot catalog and reap partial artifacts (entries whose\n * `meta.json` is missing or unparseable). Concurrent sweeps over the\n * same catalog are not supported (caller holds `snapshot.reservation`\n * or `stack.lock`).\n *\n * Also removes committed snapshot byproduct images via the runtime\n * adapter's label-filtered image cleanup, scoped to `role:\n * SNAPSHOT_IMAGE_ROLE` so build images are never touched.\n */\nexport const runPrune = (\n\tinputs: PruneInputs,\n): Effect.Effect<PruneResult, PrunePhaseError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.snapshot.phase': 'prune',\n\t\t});\n\t\tconst catalogDir = `${inputs.stackRoot}/${SNAPSHOTS_DIR_NAME}`;\n\t\tconst catalogExists = yield* fs\n\t\t\t.exists(catalogDir)\n\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\tif (!catalogExists) {\n\t\t\treturn { inspected: 0, reaped: [], imagesSwept: 0 } satisfies PruneResult;\n\t\t}\n\t\tconst ids = yield* fs\n\t\t\t.readDirectory(catalogDir)\n\t\t\t.pipe(Effect.catch(failPhase('enumerate-catalog', `readdir ${catalogDir} failed`)));\n\n\t\tconst reaped: Array<{ id: string; classification: 'abandoned' }> = [];\n\t\tfor (const id of ids) {\n\t\t\tconst dir = `${catalogDir}/${id}`;\n\t\t\tconst meta = yield* readMetaOpt(dir);\n\t\t\t// Partial artifacts (no meta) — reap to free the disk slot.\n\t\t\t// The catalog list already hides them; reaping is just GC.\n\t\t\tif (meta === null) {\n\t\t\t\tyield* fs\n\t\t\t\t\t.remove(dir, { recursive: true, force: true })\n\t\t\t\t\t.pipe(Effect.catch(failPhase('sweep-directories', `remove ${dir} failed`)));\n\t\t\t\treaped.push({ id, classification: 'abandoned' });\n\t\t\t}\n\t\t}\n\n\t\t// Sweep committed snapshot byproduct images via the runtime\n\t\t// adapter's label-scoped image cleanup. Architecture § Decision §8 —\n\t\t// committed snapshot images accumulate (a hard-killed capture can\n\t\t// leak its temp image before cleanup); the orchestrator GCs them\n\t\t// alongside catalog prune. The `role: SNAPSHOT_IMAGE_ROLE` narrowing\n\t\t// is what distinguishes these byproducts from the live stack's\n\t\t// build images (which share `{app, stack}` but carry a different\n\t\t// role / no role) — without it, prune would untag build images and\n\t\t// force silent rebuilds.\n\t\tconst imagesSwept = yield* inputs.runtime\n\t\t\t.removeManagedImages({ ...inputs.imageLabelFilter, role: SNAPSHOT_IMAGE_ROLE })\n\t\t\t.pipe(Effect.catch(failPhase('sweep-images', `image sweep failed`)));\n\n\t\treturn {\n\t\t\tinspected: ids.length,\n\t\t\treaped,\n\t\t\timagesSwept,\n\t\t} satisfies PruneResult;\n\t}).pipe(Effect.withSpan('orchestrator.snapshot.prune'));\n"],"mappings":";;;;;;;AAgCA,IAAa,kBAAb,cAAqC,OAAO,kBAAmC,CAC9E,2BACA;CACC,OAAO,OAAO,SAAS;EACtB;EACA;EACA;EACA;EACA,CAAC;CACF,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CACD,CAAC;AAEF,MAAM,YAAY,gBAAgB,gBAAgB;AAmClD,MAAM,eACL,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,OAAO,GAAG,IAAI;AAEpB,KAAI,EAAC,OADiB,GAAG,OAAO,KAAK,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,EACxE,QAAO;AAIpB,QAAO,OAAO,eAAe,wBAAwB,OAHjC,GAClB,eAAe,KAAK,CACpB,KAAK,OAAO,MAAM,UAAU,aAAa,QAAQ,KAAK,SAAS,CAAC,CAAC,EACR;EAC1D,QAAQ;EACR,eAAe;EACf,CAAC,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,KAAK,CAAC,CAAC;EAChD;;;;;;;;;;;AAgBH,MAAa,YACZ,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;AAC7B,QAAO,OAAO,oBAAoB,EACjC,2BAA2B,SAC3B,CAAC;CACF,MAAM,aAAa,GAAG,OAAO,UAAU,GAAG;AAI1C,KAAI,EAAC,OAHwB,GAC3B,OAAO,WAAW,CAClB,KAAK,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,EAEhD,QAAO;EAAE,WAAW;EAAG,QAAQ,EAAE;EAAE,aAAa;EAAG;CAEpD,MAAM,MAAM,OAAO,GACjB,cAAc,WAAW,CACzB,KAAK,OAAO,MAAM,UAAU,qBAAqB,WAAW,WAAW,SAAS,CAAC,CAAC;CAEpF,MAAM,SAA6D,EAAE;AACrE,MAAK,MAAM,MAAM,KAAK;EACrB,MAAM,MAAM,GAAG,WAAW,GAAG;AAI7B,OAAI,OAHgB,YAAY,IAAI,MAGvB,MAAM;AAClB,UAAO,GACL,OAAO,KAAK;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,CAC7C,KAAK,OAAO,MAAM,UAAU,qBAAqB,UAAU,IAAI,SAAS,CAAC,CAAC;AAC5E,UAAO,KAAK;IAAE;IAAI,gBAAgB;IAAa,CAAC;;;CAalD,MAAM,cAAc,OAAO,OAAO,QAChC,oBAAoB;EAAE,GAAG,OAAO;EAAkB,MAAM;EAAqB,CAAC,CAC9E,KAAK,OAAO,MAAM,UAAU,gBAAgB,qBAAqB,CAAC,CAAC;AAErE,QAAO;EACN,WAAW,IAAI;EACf;EACA;EACA;EACA,CAAC,KAAK,OAAO,SAAS,8BAA8B,CAAC"}
+{"version":3,"file":"prune.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/prune.ts"],"sourcesContent":["// Prune — label-scoped orphan sweep.\n//\n// Architecture § 4: the L3 prune orchestrator sweeps committed snapshot\n// byproduct images and snapshot-catalog directories whose meta document\n// is missing (partial artifacts) or unreadable. Stack-wide registry\n// pruning (engine resources / stack roster) is a sibling orchestrator and\n// lives elsewhere; this file is scoped to snapshot-adjacent artifacts.\n//\n// Image sweep scope (load-bearing): committed snapshot images are stamped\n// at `docker commit` time with `{managed, app, stack, role:\n// SNAPSHOT_IMAGE_ROLE}` (see `runtime/docker/container.ts`). Prune scopes\n// its sweep to THAT role so it reaps only snapshot byproducts. Plugin\n// BUILD images share `{managed, app, stack}` but carry the source\n// plugin's real role (or none) — never `SNAPSHOT_IMAGE_ROLE` — so the\n// sweep can NEVER untag a live stack's build images and force a silent\n// rebuild. Prune holds `stack.lock` only briefly (not stack liveness)\n// and is CLI-exposed, so this scoping is what keeps it safe against a\n// running stack.\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport type { ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport { SNAPSHOT_IMAGE_ROLE } from '../../runtime/docker/container.ts';\nimport { appName, stackName } from '../../substrate/brand.ts';\nimport {\n\tlabelScope,\n\treconcileLabel,\n\treconcileSpec,\n\ttype ReconcileFsOp,\n} from '../../substrate/runtime/reconcile/index.ts';\nimport { decodeJsonText } from '../../substrate/runtime/runtime-decode.ts';\nimport { SnapshotMetadataSchema, type SnapshotMetadata } from './descriptor.ts';\nimport { makePhaseFailer } from './phase-error.ts';\nimport { SNAPSHOTS_DIR_NAME } from './wipe.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\nexport class PrunePhaseError extends Schema.TaggedErrorClass<PrunePhaseError>()(\n\t'SnapshotPrunePhaseError',\n\t{\n\t\tphase: Schema.Literals(['enumerate-catalog', 'read-meta', 'sweep-images', 'sweep-directories']),\n\t\tdetail: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\nconst failPhase = makePhaseFailer(PrunePhaseError);\n\n// -----------------------------------------------------------------------------\n// Inputs\n// -----------------------------------------------------------------------------\n\nexport interface PruneInputs {\n\t/** Stack root containing the `snapshots/` catalog. */\n\treadonly stackRoot: string;\n\t/** App/stack scope for the committed-snapshot-image sweep. Prune\n\t *  narrows this to `role: SNAPSHOT_IMAGE_ROLE` before removing images,\n\t *  so only this stack's snapshot byproducts are swept — never its\n\t *  build images, never a sibling stack. */\n\treadonly imageLabelFilter: { readonly app: string; readonly stack: string };\n\treadonly runtime: ContainerRuntime;\n}\n\nexport interface PruneResult {\n\treadonly inspected: number;\n\treadonly reaped: ReadonlyArray<{\n\t\treadonly id: string;\n\t\t/** Reason the artifact was reaped. Currently only `'abandoned'`\n\t\t *  (partial artifact with no readable meta document). */\n\t\treadonly classification: 'abandoned';\n\t}>;\n\t/** Count of committed snapshot byproduct images removed (those stamped\n\t *  with `role: SNAPSHOT_IMAGE_ROLE` in this app/stack). Build images\n\t *  are never included. */\n\treadonly imagesSwept: number;\n}\n\n// -----------------------------------------------------------------------------\n// Helpers\n// -----------------------------------------------------------------------------\n\nconst readMetaOpt = (\n\tdir: string,\n): Effect.Effect<SnapshotMetadata | null, PrunePhaseError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst path = `${dir}/meta.json`;\n\t\tconst exists = yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false)));\n\t\tif (!exists) return null;\n\t\tconst text = yield* fs\n\t\t\t.readFileString(path)\n\t\t\t.pipe(Effect.catch(failPhase('read-meta', `read ${path} failed`)));\n\t\treturn yield* decodeJsonText(SnapshotMetadataSchema, text, {\n\t\t\tsource: path,\n\t\t\tmkError: () => null,\n\t\t}).pipe(Effect.catch(() => Effect.succeed(null)));\n\t});\n\n// -----------------------------------------------------------------------------\n// Top-level prune\n// -----------------------------------------------------------------------------\n\n/**\n * Walk the snapshot catalog and reap partial artifacts (entries whose\n * `meta.json` is missing or unparseable). Concurrent sweeps over the\n * same catalog are not supported (caller holds `stack.lock`).\n *\n * Also removes committed snapshot byproduct images via the runtime\n * adapter's label-filtered image cleanup, scoped to `role:\n * SNAPSHOT_IMAGE_ROLE` so build images are never touched.\n *\n * Routed through the unified reconcile: a flat LABEL-scope spec narrowed\n * to `role: SNAPSHOT_IMAGE_ROLE`, carrying NO container target (prune\n * mutates no containers — `target: 'running'` is the label-scope no-op\n * container target) and an `fsPlan` of two ops — `reap-meta-missing`\n * (catalog GC) then `reap-images` (byproduct image sweep). Prune never\n * touches the live deploy cache — only the snapshot byproducts (the image\n * GC); the `PruneResult` shape carries `reaped` + `imagesSwept`.\n */\nexport const runPrune = (\n\tinputs: PruneInputs,\n): Effect.Effect<PruneResult, PrunePhaseError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst catalogDir = `${inputs.stackRoot}/${SNAPSHOTS_DIR_NAME}`;\n\n\t\t// Catalog GC — reap partial artifacts (no readable meta). The\n\t\t// `isMetaMissing` classifier is prune's projection: a\n\t\t// `readMetaOpt` read+decode lifted to a predicate.\n\t\tconst reapMetaMissing: ReconcileFsOp<PrunePhaseError> = {\n\t\t\top: 'reap-meta-missing',\n\t\t\tcatalogDir,\n\t\t\tisMetaMissing: (dir) => readMetaOpt(dir).pipe(Effect.map((meta) => meta === null)),\n\t\t\tonReaddirError: failPhase('enumerate-catalog', `readdir ${catalogDir} failed`),\n\t\t\tonRemoveError: failPhase('sweep-directories', `remove catalog entry failed`),\n\t\t};\n\n\t\t// Byproduct image sweep — architecture § Decision §8. The\n\t\t// `role: SNAPSHOT_IMAGE_ROLE` narrowing (carried on the label tuple)\n\t\t// distinguishes these byproducts from the live stack's build images\n\t\t// (which share `{app, stack}` but carry a different role / no role) —\n\t\t// without it, prune would untag build images and force silent\n\t\t// rebuilds.\n\t\tconst reapImages: ReconcileFsOp<PrunePhaseError> = {\n\t\t\top: 'reap-images',\n\t\t\tonError: failPhase('sweep-images', `image sweep failed`),\n\t\t};\n\n\t\tconst result = yield* reconcileLabel(\n\t\t\treconcileSpec<PrunePhaseError>({\n\t\t\t\t// No container target — prune mutates no containers. Label-scope\n\t\t\t\t// only sweeps containers/networks/volumes when `target` is\n\t\t\t\t// `absent`; `running` leaves them untouched.\n\t\t\t\ttarget: 'running',\n\t\t\t\tscope: labelScope({\n\t\t\t\t\tapp: appName(inputs.imageLabelFilter.app),\n\t\t\t\t\tstack: stackName(inputs.imageLabelFilter.stack),\n\t\t\t\t\trole: SNAPSHOT_IMAGE_ROLE,\n\t\t\t\t}),\n\t\t\t\tdirection: 'drain',\n\t\t\t\tfsPlan: { ops: [reapMetaMissing, reapImages] },\n\t\t\t}),\n\t\t\t{ runtime: inputs.runtime },\n\t\t);\n\n\t\treturn {\n\t\t\tinspected: result.inspected,\n\t\t\treaped: result.reapedIds.map((id) => ({ id, classification: 'abandoned' as const })),\n\t\t\timagesSwept: result.imagesSwept,\n\t\t} satisfies PruneResult;\n\t});\n"],"mappings":";;;;;;;;;;;AAuCA,IAAa,kBAAb,cAAqC,OAAO,iBAAkC,CAAC,CAC9E,2BACA;CACC,OAAO,OAAO,SAAS;EAAC;EAAqB;EAAa;EAAgB;CAAmB,CAAC;CAC9F,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;AAEH,MAAM,YAAY,gBAAgB,eAAe;AAmCjD,MAAM,eACL,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,OAAO,GAAG,IAAI;CAEpB,IAAI,EAAC,OADiB,GAAG,OAAO,IAAI,CAAC,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,KAAK,CAAC,CAAC,IACvE,OAAO;CAIpB,OAAO,OAAO,eAAe,wBAAwB,OAHjC,GAClB,eAAe,IAAI,CAAC,CACpB,KAAK,OAAO,MAAM,UAAU,aAAa,QAAQ,KAAK,QAAQ,CAAC,CAAC,GACP;EAC1D,QAAQ;EACR,eAAe;CAChB,CAAC,CAAC,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,IAAI,CAAC,CAAC;AACjD,CAAC;;;;;;;;;;;;;;;;;;AAuBF,MAAa,YACZ,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,aAAa,GAAG,OAAO,UAAU,GAAG;CAK1C,MAAM,kBAAkD;EACvD,IAAI;EACJ;EACA,gBAAgB,QAAQ,YAAY,GAAG,CAAC,CAAC,KAAK,OAAO,KAAK,SAAS,SAAS,IAAI,CAAC;EACjF,gBAAgB,UAAU,qBAAqB,WAAW,WAAW,QAAQ;EAC7E,eAAe,UAAU,qBAAqB,6BAA6B;CAC5E;CAQA,MAAM,aAA6C;EAClD,IAAI;EACJ,SAAS,UAAU,gBAAgB,oBAAoB;CACxD;CAEA,MAAM,SAAS,OAAO,eACrB,cAA+B;EAI9B,QAAQ;EACR,OAAO,WAAW;GACjB,KAAK,QAAQ,OAAO,iBAAiB,GAAG;GACxC,OAAO,UAAU,OAAO,iBAAiB,KAAK;GAC9C,MAAM;EACP,CAAC;EACD,WAAW;EACX,QAAQ,EAAE,KAAK,CAAC,iBAAiB,UAAU,EAAE;CAC9C,CAAC,GACD,EAAE,SAAS,OAAO,QAAQ,CAC3B;CAEA,OAAO;EACN,WAAW,OAAO;EAClB,QAAQ,OAAO,UAAU,KAAK,QAAQ;GAAE;GAAI,gBAAgB;EAAqB,EAAE;EACnF,aAAa,OAAO;CACrB;AACD,CAAC"}

package/dist/orchestrators/snapshot/restore.mjs

@@ -3,16 +3,18 @@ import { runtimeControlLockPathForStackRoot } from "../../substrate/runtime/cros
 import { COMMAND_CHANNEL_COMMANDS_FILE_NAME, COMMAND_CHANNEL_EVENTS_FILE_NAME } from "../../substrate/runtime/cross-process/command-channel/channel.mjs";
 import "../../substrate/runtime/cross-process/command-channel/index.mjs";
 import { mintRandomSuffix } from "../../substrate/runtime/random-suffix.mjs";
+import { finishTarReader, makeTarReaderState, processTarChunk, skipEntry, stopScan } from "../../substrate/runtime/tar/reader.mjs";
 import { HostTreeTarError, untarHostTree, validateHostTreeTarEntries } from "../../substrate/runtime/host-tree-tar/index.mjs";
-import { ContributionDocSchema, DEPLOY_CACHE_NAMESPACES, SnapshotLayout, SnapshotMetadataSchema, containerImagesBundlePath, contributionPath, isRestorableContainerImageName, isSafeSnapshotPathSegment, isSafeSnapshotRelativePath, parseSnapshotId } from "./descriptor.mjs";
+import { ContributionDocSchema, SnapshotLayout, SnapshotMetadataSchema, containerImagesBundlePath, contributionPath, deployCacheSubtreeRelPaths, isRestorableContainerImageName, isSafeSnapshotPathSegment, isSafeSnapshotRelativePath, parseSnapshotId } from "./descriptor.mjs";
+import "../../substrate/runtime/stage-and-swap/index.mjs";
+import { executeFsPlan } from "../../substrate/runtime/reconcile/fs-plan.mjs";
+import "../../substrate/runtime/reconcile/index.mjs";
 import { makePhaseFailer } from "./phase-error.mjs";
 import { CACHE_DIR_NAME, SNAPSHOTS_DIR_NAME } from "./wipe.mjs";
 import { readImageBundleTags, verifyImageBundleTags } from "./image-bundle-tags.mjs";
 import { verifyArtifactIntegrity } from "./integrity.mjs";
-import { mergeContributions, runIdentityGuard, runRuntimeIdentityGuard } from "./identity-guard.mjs";
-import { readSnapshotStateDocument, writeSnapshotStateDocument } from "./state-document.mjs";
-import { RESTORE_PENDING_FILE_NAME, RestorePendingDocumentSchema, makePendingMarkerDocument, pendingMarkerPath, removePendingMarker, rewritePendingMarkerContainers, writePendingMarker } from "./pending-marker.mjs";
-import { stageAndSwap } from "../../substrate/runtime/stage-and-swap/index.mjs";
+import { mergeContributions, requireIdentity, runIdentityGuard, runRuntimeIdentityGuard } from "./identity-guard.mjs";
+import { clearRestoreSentinel, writeRestoreSentinel } from "./interrupted-restore.mjs";
 import { Effect, Exit, FileSystem, Schema, Stream } from "effect";
 //#region src/orchestrators/snapshot/restore.ts
 /** Tagged failure during a restore step. Phase discriminates the
@@ -22,22 +24,20 @@ var RestorePhaseError = class extends Schema.TaggedErrorClass()("SnapshotRestore
 		"read-meta",
 		"meta-corrupt",
 		"meta-absent",
-		"read-state",
 		"read-contribution",
 		"read-integrity",
 		"verify-integrity",
 		"preflight",
+		"cache-missing",
 		"pre-restore-hook",
 		"untar-host-tree",
 		"load-image",
 		"retag-image",
-		"expand-state",
 		"post-restore-hook",
 		"pre-cleanup",
-		"write-restore-pending",
-		"read-restore-pending",
-		"clear-restore-pending",
-		"missing-subtree-fatal"
+		"resume",
+		"missing-subtree-fatal",
+		"graph-input-mismatch"
 	]),
 	plugin: Schema.optional(Schema.String),
 	detail: Schema.String,
@@ -55,15 +55,6 @@ const failImageBundleTagScan = (phase, plugin) => (cause) => Effect.fail(new Res
 	detail: cause.detail,
 	cause
 }));
-/** Project a `SnapshotStateDocumentError` onto a `RestorePhaseError`,
-*  branching by `kind` so a phase classifier never inspects message
-*  substrings. */
-const failStateDocument = (readPhase, writePhase, plugin) => (err) => Effect.fail(new RestorePhaseError({
-	phase: err.kind === "write" ? writePhase : readPhase,
-	plugin,
-	detail: err.detail,
-	cause: err.cause
-}));
 const readMeta = (artifactDir, expectedId) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = `${artifactDir}/${SnapshotLayout.metaFile}`;
@@ -90,7 +81,7 @@ const readMeta = (artifactDir, expectedId) => Effect.gen(function* () {
 	if (parsedId === null) return yield* failRestore("meta-corrupt", `meta.json contains an unsafe snapshot id: ${meta.id}`);
 	if (parsedId !== expectedId) return yield* failRestore("meta-corrupt", `meta.json id ${meta.id} does not match requested snapshot id ${expectedId}`);
 	return meta;
-}).pipe(Effect.withSpan("orchestrator.snapshot.restore.read-meta"));
+});
 const verifyIntegrity = (artifactDir) => verifyArtifactIntegrity(artifactDir).pipe(Effect.catchTag("SnapshotIntegrityError", (err) => Effect.fail(new RestorePhaseError({
 	phase: err.kind === "missing" ? "read-integrity" : "verify-integrity",
 	detail: err.detail,
@@ -107,13 +98,6 @@ const removeCapturedContainers = (meta, runtime, runtimeIdentity) => Effect.gen(
 		plugin: captured.plugin,
 		role: captured.role
 	}).pipe(Effect.catch(failPhase("pre-cleanup", `remove managed containers for ${captured.plugin}/${captured.role} failed`, captured.plugin)));
-}).pipe(Effect.withSpan("orchestrator.snapshot.restore.remove-containers"));
-const stagedImageToPendingEntry = (image) => ({
-	plugin: image.captured.plugin,
-	role: image.captured.role,
-	targetImageName: image.captured.imageName,
-	stagedImageTag: image.stagedImageTag,
-	digest: image.stagedRef.digest
 });
 const loadedBundleTags = (bundle) => {
 	const tags = /* @__PURE__ */ new Set();
@@ -121,42 +105,6 @@ const loadedBundleTags = (bundle) => {
 	return tags;
 };
 const mintRestoreStagingTag = () => `devstack-snapshot:restore-${mintRandomSuffix(24)}`;
-const mapMarkerIoError = (phase) => (err) => Effect.fail(new RestorePhaseError({
-	phase,
-	detail: err.detail,
-	cause: err.cause
-}));
-const writeRestorePendingMarker = (args) => {
-	if (args.stagedImages.length === 0) return Effect.void;
-	const doc = makePendingMarkerDocument({
-		meta: args.meta,
-		artifactDir: args.artifactDir,
-		containers: args.stagedImages.map(stagedImageToPendingEntry)
-	});
-	return writePendingMarker(args.runtimeRoot, doc).pipe(Effect.catchTag("SnapshotRestorePendingMarkerIoError", mapMarkerIoError("write-restore-pending")));
-};
-const rewriteRestorePendingMarker = (runtimeRoot, doc, stillPending) => writePendingMarker(runtimeRoot, rewritePendingMarkerContainers(doc, stillPending)).pipe(Effect.catchTag("SnapshotRestorePendingMarkerIoError", mapMarkerIoError("write-restore-pending")));
-const clearRestorePendingMarker = (runtimeRoot) => removePendingMarker(runtimeRoot).pipe(Effect.catchTag("SnapshotRestorePendingMarkerIoError", mapMarkerIoError("clear-restore-pending")));
-const readRestorePendingMarker = (runtimeRoot) => Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
-	const path = pendingMarkerPath(runtimeRoot);
-	if (!(yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false))))) return null;
-	return yield* decodeUnknown(RestorePendingDocumentSchema, yield* parseJsonText(yield* fs.readFileString(path).pipe(Effect.catch(failPhase("read-restore-pending", `read ${RESTORE_PENDING_FILE_NAME}`))), {
-		source: path,
-		mkError: (issue) => new RestorePhaseError({
-			phase: "read-restore-pending",
-			detail: `${RESTORE_PENDING_FILE_NAME} is not valid JSON`,
-			cause: issue.cause
-		})
-	}), {
-		source: path,
-		mkError: (issue) => new RestorePhaseError({
-			phase: "read-restore-pending",
-			detail: `${RESTORE_PENDING_FILE_NAME} failed schema decode`,
-			cause: issue.cause
-		})
-	});
-});
 const requirePathSegment = (kind, value, plugin) => isSafeSnapshotPathSegment(value) ? Effect.void : failRestore("preflight", `unsafe snapshot ${kind} path segment: ${value}`, plugin);
 const requireReadableNonEmptyFile = (path, phase, detail, plugin) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
@@ -204,8 +152,6 @@ const preflightArtifact = (meta, artifactDir) => Effect.gen(function* () {
 		seenSnapshotTags.set(captured.snapshotTag, captured);
 	}
 	for (const pluginKey of meta.participants) yield* preflightContributionDoc(pluginKey, artifactDir);
-	const statePath = `${artifactDir}/${SnapshotLayout.stateFile}`;
-	if (yield* fs.exists(statePath).pipe(Effect.catch(() => Effect.succeed(false)))) yield* readSnapshotStateDocument(statePath).pipe(Effect.catchTag("SnapshotStateDocumentError", failStateDocument("read-state", "expand-state")));
 	if (meta.hostTreeIncluded) {
 		const tarPath = `${artifactDir}/${SnapshotLayout.hostTreeTar}`;
 		yield* requireReadableNonEmptyFile(tarPath, "untar-host-tree", "host-tree tar is required");
@@ -216,7 +162,7 @@ const preflightArtifact = (meta, artifactDir) => Effect.gen(function* () {
 			cause
 		})))).pipe(Effect.catch(failPhase("untar-host-tree", `host-tree tar entry validation failed`)));
 	}
-}).pipe(Effect.withSpan("orchestrator.snapshot.restore.preflight"));
+});
 const loadImageBundle = (tarPath, artifactDir, runtime, expectedSnapshotTags) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const fullTarPath = `${artifactDir}/${tarPath}`;
@@ -236,7 +182,7 @@ const loadImageBundle = (tarPath, artifactDir, runtime, expectedSnapshotTags) =>
 		refsByTag.set(ref.tag, ref);
 	}
 	return refsByTag;
-}).pipe(Effect.withSpan("orchestrator.snapshot.restore.load-image-bundle"));
+});
 const expectedSnapshotTagsByBundle = (containers) => {
 	const byBundle = /* @__PURE__ */ new Map();
 	for (const captured of containers) {
@@ -259,22 +205,24 @@ const stageLoadedImage = (captured, loadedRef, runtime, registerStagedImage) =>
 	yield* registerStagedImage(stagedImage);
 	yield* runtime.tagImage(loadedRef, stagedImageTag, { removeSourceAfterTag: true }).pipe(Effect.catch(failPhase("retag-image", `tag restored image ${captured.snapshotTag} as staging ref ${stagedImageTag} failed`, captured.plugin)));
 	return stagedImage;
-}).pipe(Effect.withSpan("orchestrator.snapshot.restore.stage-image"));
+});
 const cleanupRestoreStagingImages = (runtime, images) => Effect.forEach(images, (image) => runtime.removeImage(image.stagedRef).pipe(Effect.catch((cause) => Effect.logWarning(`remove restore staging image ${image.stagedImageTag} failed during restore cleanup: ${String(cause)}`))), { concurrency: "unbounded" }).pipe(Effect.asVoid);
-/** Promote each staged image to its recorded name, rewriting the
-*  on-disk pending marker after each successful tag. If the loop
-*  fails mid-way the marker reflects exactly which images are still
-*  pending (the failed entry + every entry not yet attempted), so
-*  the supervise-startup `recoverPendingRestore` only has to retry
-*  the remaining set — no scanning Docker for "which targets exist
-*  already?" required. */
-const promoteStagedImages = (images, runtime, runtimeStackRoot, pendingDoc) => Effect.gen(function* () {
-	for (let i = 0; i < images.length; i += 1) {
-		const image = images[i];
+/** Promote each staged image to its recorded TARGET name. The target
+*  name is the original image name the supervisor used for the
+*  container, so leaving the staged image at that name lets the next
+*  boot's image-match adoption (`decideRunAction`) find it locally and
+*  `docker run` it — no scanner, no on-disk marker. A mid-loop failure
+*  promotes a prefix of the images; the inner staging-cleanup scope
+*  prunes the un-promoted staging refs, and a re-run of restore re-stages
+*  and re-promotes from the snapshot artifact. */
+const promoteStagedImages = (images, runtime) => Effect.gen(function* () {
+	for (const image of images) {
+		const oldDigest = yield* runtime.inspectImageDigest(image.captured.imageName).pipe(Effect.catch(() => Effect.succeed(null)));
 		yield* runtime.tagImage(image.stagedRef, image.captured.imageName, { removeSourceAfterTag: true }).pipe(Effect.catch(failPhase("retag-image", `tag staged image ${image.stagedImageTag} as ${image.captured.imageName} failed`, image.captured.plugin)));
-		if (pendingDoc !== null) yield* rewriteRestorePendingMarker(runtimeStackRoot, pendingDoc, images.slice(i + 1).map(stagedImageToPendingEntry));
+		const newDigest = yield* runtime.inspectImageDigest(image.captured.imageName).pipe(Effect.catch(() => Effect.succeed(null)));
+		if (oldDigest !== null && oldDigest !== newDigest) yield* runtime.removeImage({ digest: oldDigest }).pipe(Effect.catch((cause) => Effect.logWarning(`GC of superseded image layer ${oldDigest} for ${image.captured.imageName} failed (best-effort): ${String(cause)}`)));
 	}
-}).pipe(Effect.withSpan("orchestrator.snapshot.restore.promote-images"));
+});
 const restoreHostTree = (artifactDir, target) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const tarPath = `${artifactDir}/${SnapshotLayout.hostTreeTar}`;
@@ -289,150 +237,227 @@ const restoreHostTree = (artifactDir, target) => Effect.gen(function* () {
 		cause
 	})));
 	yield* Effect.scoped(untarHostTree(tarStream, { target })).pipe(Effect.catch(failPhase("untar-host-tree", `untar ${tarPath} to ${target} failed`)));
-}).pipe(Effect.withSpan("orchestrator.snapshot.restore.host-tree"));
+});
 const LIVE_RESTORE_PRESERVED_PATHS = [
-	{
-		relativePath: SNAPSHOTS_DIR_NAME,
-		kind: "directory"
-	},
-	{
-		relativePath: COMMAND_CHANNEL_COMMANDS_FILE_NAME,
-		kind: "file"
-	},
-	{
-		relativePath: COMMAND_CHANNEL_EVENTS_FILE_NAME,
-		kind: "file"
-	},
-	{
-		relativePath: "roster.json",
-		kind: "file"
-	},
-	{
-		relativePath: "container-claims.json",
-		kind: "file"
-	},
-	{
-		relativePath: "snapshot.reservation",
-		kind: "file"
-	},
-	...DEPLOY_CACHE_NAMESPACES.map((namespace) => ({
-		relativePath: `${CACHE_DIR_NAME}/${namespace}`,
-		kind: "directory",
-		overwrite: false
-	}))
+	{ relativePath: SNAPSHOTS_DIR_NAME },
+	{ relativePath: COMMAND_CHANNEL_COMMANDS_FILE_NAME },
+	{ relativePath: COMMAND_CHANNEL_EVENTS_FILE_NAME },
+	{ relativePath: "roster.json" }
 ];
+/** The deploy-cache subtree relPaths (`cache/<ns>`) the snapshot RECORDS as
+*  captured in its metadata. Capture tars a namespace only if it existed on disk
+*  (`missingTolerance: 'fine'`) and writes `meta.subtrees` AFTER a successful
+*  tar, so a relPath here means "this snapshot intended to carry this cache
+*  namespace". A disabled-plugin namespace (e.g. `cache/deepbook` in a
+*  deepbook-less stack) is simply absent from the list, so the preflight never
+*  over-requires it. */
+const recordedDeployCacheRelPaths = (meta) => {
+	const expected = new Set(deployCacheSubtreeRelPaths(CACHE_DIR_NAME));
+	const recorded = [];
+	for (const subtree of meta.subtrees) if (expected.has(subtree.relPath)) recorded.push(subtree.relPath);
+	return recorded;
+};
+/** Stream the host-tree tar and collect which of `expectedRelPaths` physically
+*  appear as an entry prefix. An entry path `cache/<ns>/<chain>/<hash>.json`
+*  (or the bare `cache/<ns>/` directory) marks `cache/<ns>` present. Read-only:
+*  bodies are skipped, never buffered. */
+const scanHostTreeCacheRelPaths = (artifactDir, expectedRelPaths) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const tarPath = `${artifactDir}/${SnapshotLayout.hostTreeTar}`;
+	const present = /* @__PURE__ */ new Set();
+	const state = makeTarReaderState();
+	const matchEntry = (entryPath) => {
+		for (const rel of expectedRelPaths) {
+			if (present.has(rel)) continue;
+			if (entryPath === rel || entryPath.startsWith(`${rel}/`)) present.add(rel);
+		}
+	};
+	const hooks = {
+		onEntry: (entry) => {
+			matchEntry(entry.path);
+			return present.size === expectedRelPaths.length ? stopScan() : skipEntry();
+		},
+		onExtendedError: (detail) => new RestorePhaseError({
+			phase: "cache-missing",
+			detail
+		})
+	};
+	const tarStream = fs.stream(tarPath).pipe(Stream.mapError((cause) => new RestorePhaseError({
+		phase: "cache-missing",
+		detail: `read host-tree tar failed at ${tarPath}`,
+		cause
+	})), Stream.takeWhile(() => !state.stopped));
+	yield* Stream.runForEach(tarStream, (chunk) => {
+		const error = processTarChunk(state, chunk, hooks);
+		return error === null ? Effect.void : Effect.fail(error);
+	});
+	const finalError = finishTarReader(state, (detail) => new RestorePhaseError({
+		phase: "cache-missing",
+		detail
+	}));
+	if (finalError !== null) return yield* Effect.fail(finalError);
+	return present;
+});
 /**
-* Run the full restore. Bracketed-atomic via `stageAndSwap` at the
-* runtime-root level — external watchers never observe a half-restored
-* tree.
+* The SNAPSHOT's host-tree `cache/<DEPLOY_CACHE_NAMESPACES>` is the SOLE source
+* of the on-chain deploy/mint ids on restore (capture tars `cache/<ns>` into the
+* artifact; restore untars it and does NOT preserve-from-live — see
+* LIVE_RESTORE_PRESERVED_PATHS). So the cache check is against the SNAPSHOT, not
+* the live stack — which is exactly what makes a CROSS-MACHINE restore work: a
+* fresh runner has an empty live cache, and the snapshot supplies the ids.
 *
-* Order:
-*   1. Read meta.json (refuse if absent / corrupt — no mutation).
-*   2. Run identity-guard against runtime metadata and merged plugin
-*      contributions (refuse on any disagreement — no mutation).
-*   3. Pre-restore hooks (per-plugin validation; soft errors).
-*   4. Stage:
-*      - Untar host-tree into staging.
-*      - Copy state.json into staging.
-*      - Re-read contribution docs.
-*      - Load image bundles and stage verified snapshot tags.
-*      - Write a restore-pending marker into the staged root.
-*   5. Atomic swap staging → runtime root, preserving live command /
-*      event channel files and other explicit runtime-control files.
-*   6. Promote staged images to recorded refs, then remove captured
-*      managed containers by label. If this fails, the pending marker
-*      remains in the restored root for diagnosis/recovery.
-*   7. Post-restore hooks.
+* Refuse (fail-closed, BEFORE any mutation, matching the identity-guard posture)
+* if the snapshot's cache is NOT self-contained: every deploy-cache namespace
+* the metadata RECORDS as captured must be physically present in the host-tree
+* tar. A partial loss (metadata claims `cache/<ns>` but the tar lacks it — a
+* corrupted/tampered artifact) would let the post-restore boot re-deploy that
+* namespace with FRESH ids and orphan its pre-snapshot objects. Requiring ALL
+* recorded namespaces (not just ANY one) is the FIX over the prior "any one dir
+* present" check, which passed a partial cache and re-minted the rest.
 *
-* The caller is responsible for `acquireReservation`; restore supplies
-* the runtime-control publish lock to `stageAndSwap`.
+* A snapshot that records NO deploy-cache subtrees (a genuine pre-deploy /
+* empty-stack capture) has nothing to verify and passes — there are no minted
+* ids to lose. The matrix's hard-reset phase asserts the loud re-deploy on a
+* post-restore live-cache wipe.
+*/
+const requireSnapshotDeployCache = (meta, artifactDir) => Effect.gen(function* () {
+	const recorded = recordedDeployCacheRelPaths(meta);
+	if (recorded.length === 0) return;
+	if (!meta.hostTreeIncluded) return yield* failRestore("cache-missing", `snapshot metadata records deploy-cache subtrees (${recorded.join(", ")}) but the artifact carries no host-tree tar. The snapshot's cache is the SOLE source of the on-chain deploy/mint ids restore reuses; restoring without it would let the next boot re-deploy with FRESH ids and orphan every pre-snapshot object. Refusing.`);
+	const present = yield* scanHostTreeCacheRelPaths(artifactDir, recorded);
+	const missing = recorded.filter((rel) => !present.has(rel));
+	if (missing.length > 0) return yield* failRestore("cache-missing", `snapshot host-tree is missing deploy-cache namespaces it recorded as captured (${missing.join(", ")}). The snapshot's cache is the SOLE source of the on-chain deploy/mint ids restore reuses; a partial cache would let the next boot re-deploy the missing namespaces with FRESH ids and orphan their pre-snapshot objects. Refusing.`);
+});
+const graphInputMismatchDetail = (snapshotGraphInputId, currentGraphInputId) => `snapshot graph input id ${snapshotGraphInputId} does not match current graph input id ${currentGraphInputId}; restoring may create inconsistent state`;
+const checkGraphInputCompatibility = (meta, current, policy) => {
+	if (current === void 0) return Effect.void;
+	if (meta.graphInput.graphInputId === current.graphInputId) return Effect.void;
+	const detail = graphInputMismatchDetail(meta.graphInput.graphInputId, current.graphInputId);
+	if (policy === "block") return Effect.fail(new RestorePhaseError({
+		phase: "graph-input-mismatch",
+		detail
+	}));
+	return Effect.logWarning(detail);
+};
+/**
+* Run the full restore. Routed through the unified reconcile as an
+* ORDERED 4-step body — restore is NOT a single converge target
+* but a destructive ordered pair around an fs swap:
+*
+*   step0  — PRECONDITION: identity-guard, FAIL-CLOSED BEFORE ANY MUTATION.
+*            The runtime-identity guard + merged plugin-contribution guard
+*            complete BEFORE the first mutation (the docker load/tag inside
+*            the swap-tree build). On mismatch the sweep / load / tag spies
+*            stay EMPTY — zero mutations (restore.test `:214/:263`). Keep
+*            the pure meta read → guard → only then mutate ordering.
+*   step1  — fsPlan `swap-tree(untar)`: a single-op `ReconcileFsPlan` run
+*            through `executeFsPlan`, which publishes the new tree via the
+*            UNCHANGED `stageAndSwap`. The build untars the host-tree +
+*            loads/stages the committed image bundle into staging; the
+*            atomic swap preserves the RESTORE preserve list
+*            (`LIVE_RESTORE_PRESERVED_PATHS` — per-namespace live cache +
+*            control files, a restore-direction constant, NOT wipe's
+*            wholesale predicate). Promote staged
+*            images to their captured TARGET names is the swap step's
+*            docker tail.
+*   step2 R1 — HARD container removal (target = absent, label scope,
+*            policy-independent, unconditional, claim-bypassing) via
+*            `removeManagedContainers`. STRICTLY before R2. Never expressed
+*            as flip-image-and-let-decideRunAction-recreate (guardrail
+*            §3.6).
+*   step2 R2 — CONVERGE (recreate-from-fresh): NOT in `runRestore`. R1
+*            removed the containers, so the NEXT acquire (the live
+*            supervisor's `doSelectiveRestart`, itself routed through
+*            `reconcileGraph`, or the offline CLI's next-boot acquire) sees
+*            facts:null → fresh → creates from the RESTORED images. Verb is
+*            recreate-from-fresh, NOT adopt.
+*
+* Bracketed-atomic at the runtime-root level — external watchers never
+* observe a half-restored tree. The caller holds `stack.lock` for the
+* bounded snapshot window; restore supplies the runtime-control publish lock
+* to the swap-tree op.
 */
 const runRestore = (inputs) => Effect.gen(function* () {
-	yield* Effect.annotateCurrentSpan({
-		"devstack.snapshot.phase": "restore",
-		"devstack.snapshot.artifact": inputs.artifactDir
-	});
 	const meta = yield* readMeta(inputs.artifactDir, inputs.snapshotId);
 	yield* verifyIntegrity(inputs.artifactDir);
+	yield* checkGraphInputCompatibility(meta, inputs.currentGraphInput, inputs.graphInputMismatchPolicy);
 	yield* runRuntimeIdentityGuard({
 		app: meta.app,
 		stack: meta.stack,
 		network: meta.network
 	}, inputs.runtimeIdentity);
-	const liveContributions = [];
-	for (const participant of inputs.participants) {
-		const slice = yield* participant.liveIdentity;
-		liveContributions.push({
-			plugin: participant.plugin,
-			slice
-		});
+	if (inputs.participants.length === 0) yield* requireIdentity(meta.identity, "snapshot");
+	else {
+		const liveContributions = [];
+		for (const participant of inputs.participants) {
+			const slice = yield* participant.liveIdentity;
+			liveContributions.push({
+				plugin: participant.plugin,
+				slice
+			});
+		}
+		const live = yield* mergeContributions(liveContributions);
+		yield* runIdentityGuard(meta.identity, live);
 	}
-	const live = yield* mergeContributions(liveContributions);
-	yield* runIdentityGuard(meta.identity, live);
+	yield* requireSnapshotDeployCache(meta, inputs.artifactDir);
 	for (const participant of inputs.participants) if (participant.preRestore) yield* participant.preRestore.pipe(Effect.catch(failPhase("pre-restore-hook", `preRestore failed`, participant.plugin)));
 	yield* preflightArtifact(meta, inputs.artifactDir);
 	yield* Effect.scoped(Effect.gen(function* () {
 		const stagedImages = [];
 		let recoveryHandoffComplete = false;
 		yield* Effect.addFinalizer((exit) => Exit.isFailure(exit) && !recoveryHandoffComplete ? cleanupRestoreStagingImages(inputs.runtime, stagedImages) : Effect.void);
-		yield* stageAndSwap({
+		const swapBuild = Effect.gen(function* () {
+			if (meta.hostTreeIncluded) yield* restoreHostTree(inputs.artifactDir, inputs.runtimeStagingPath);
+			const fs = yield* FileSystem.FileSystem;
+			for (const pluginKey of meta.participants) {
+				const path = `${inputs.artifactDir}/${contributionPath(pluginKey)}`;
+				if (!(yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false))))) return yield* Effect.fail(new RestorePhaseError({
+					phase: "read-contribution",
+					plugin: pluginKey,
+					detail: `contribution doc absent at ${path}`
+				}));
+			}
+			const expectedTagsByBundle = expectedSnapshotTagsByBundle(meta.containers);
+			const loadedRefsBySnapshotTag = /* @__PURE__ */ new Map();
+			for (const [tarPath, expectedTags] of expectedTagsByBundle) {
+				const loadedRefs = yield* loadImageBundle(tarPath, inputs.artifactDir, inputs.runtime, expectedTags);
+				for (const [tag, ref] of loadedRefs) loadedRefsBySnapshotTag.set(tag, ref);
+			}
+			for (const captured of meta.containers) {
+				const loadedRef = loadedRefsBySnapshotTag.get(captured.snapshotTag);
+				if (loadedRef === void 0) return yield* failRestore("load-image", `container image bundle did not return loaded ref for ${captured.snapshotTag}`, captured.plugin);
+				yield* stageLoadedImage(captured, loadedRef, inputs.runtime, (image) => Effect.sync(() => {
+					stagedImages.push(image);
+				}));
+			}
+			yield* writeRestoreSentinel(inputs.runtimeStagingPath, {
+				snapshotId: inputs.snapshotId,
+				artifactDir: inputs.artifactDir
+			});
+			return stagedImages;
+		});
+		yield* executeFsPlan({ ops: [{
+			op: "swap-tree",
 			targetPath: inputs.runtimeStackRoot,
 			stagingPath: inputs.runtimeStagingPath,
 			backupPath: inputs.runtimeBackupPath,
+			buildEffect: swapBuild,
 			preserveFromTarget: LIVE_RESTORE_PRESERVED_PATHS,
 			publishLockPath: runtimeControlLockPathForStackRoot(inputs.runtimeStackRoot),
-			build: Effect.gen(function* () {
-				if (meta.hostTreeIncluded) yield* restoreHostTree(inputs.artifactDir, inputs.runtimeStagingPath);
-				const fs = yield* FileSystem.FileSystem;
-				const srcState = `${inputs.artifactDir}/${SnapshotLayout.stateFile}`;
-				if (yield* fs.exists(srcState).pipe(Effect.catch(() => Effect.succeed(false)))) {
-					const stateDoc = yield* readSnapshotStateDocument(srcState).pipe(Effect.catchTag("SnapshotStateDocumentError", failStateDocument("read-state", "expand-state")));
-					yield* writeSnapshotStateDocument(`${inputs.runtimeStagingPath}/${SnapshotLayout.stateFile}`, stateDoc).pipe(Effect.catchTag("SnapshotStateDocumentError", failStateDocument("expand-state", "expand-state")));
-				}
-				for (const pluginKey of meta.participants) {
-					const path = `${inputs.artifactDir}/${contributionPath(pluginKey)}`;
-					if (!(yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false))))) return yield* Effect.fail(new RestorePhaseError({
-						phase: "read-contribution",
-						plugin: pluginKey,
-						detail: `contribution doc absent at ${path}`
-					}));
-				}
-				const expectedTagsByBundle = expectedSnapshotTagsByBundle(meta.containers);
-				const loadedRefsBySnapshotTag = /* @__PURE__ */ new Map();
-				for (const [tarPath, expectedTags] of expectedTagsByBundle) {
-					const loadedRefs = yield* loadImageBundle(tarPath, inputs.artifactDir, inputs.runtime, expectedTags);
-					for (const [tag, ref] of loadedRefs) loadedRefsBySnapshotTag.set(tag, ref);
-				}
-				for (const captured of meta.containers) {
-					const loadedRef = loadedRefsBySnapshotTag.get(captured.snapshotTag);
-					if (loadedRef === void 0) return yield* failRestore("load-image", `container image bundle did not return loaded ref for ${captured.snapshotTag}`, captured.plugin);
-					yield* stageLoadedImage(captured, loadedRef, inputs.runtime, (image) => Effect.sync(() => {
-						stagedImages.push(image);
-					}));
-				}
-				yield* writeRestorePendingMarker({
-					runtimeRoot: inputs.runtimeStagingPath,
-					meta,
-					artifactDir: inputs.artifactDir,
-					stagedImages
-				});
-				return stagedImages;
-			})
-		});
-		if (stagedImages.length > 0) {
-			const pendingDocAfterSwap = yield* readRestorePendingMarker(inputs.runtimeStackRoot);
-			yield* Effect.uninterruptible(Effect.gen(function* () {
-				yield* promoteStagedImages(stagedImages, inputs.runtime, inputs.runtimeStackRoot, pendingDocAfterSwap);
-				yield* removeCapturedContainers(meta, inputs.runtime, inputs.runtimeIdentity);
-				yield* clearRestorePendingMarker(inputs.runtimeStackRoot);
-				recoveryHandoffComplete = true;
-			}));
-		} else recoveryHandoffComplete = true;
+			onSwapError: (cause) => Effect.fail(cause)
+		}] });
+		if (stagedImages.length > 0) yield* Effect.uninterruptible(Effect.gen(function* () {
+			yield* promoteStagedImages(stagedImages, inputs.runtime);
+			yield* removeCapturedContainers(meta, inputs.runtime, inputs.runtimeIdentity);
+			recoveryHandoffComplete = true;
+		}));
+		else recoveryHandoffComplete = true;
+		yield* clearRestoreSentinel(inputs.runtimeStackRoot);
 	}));
 	for (const participant of inputs.participants) if (participant.postRestore) yield* participant.postRestore.pipe(Effect.catch(failPhase("post-restore-hook", `postRestore failed`, participant.plugin)));
 	return meta;
-}).pipe(Effect.withSpan("orchestrator.snapshot.restore"));
+});
 //#endregion
-export { RestorePhaseError, runRestore };
+export { RestorePhaseError, graphInputMismatchDetail, runRestore };
 
 //# sourceMappingURL=restore.mjs.map