@mysten-incubation/devstack 0.1.0 → 0.2.0

package/dist/orchestrators/snapshot/capture.mjs

@@ -1,30 +1,34 @@
 import { tarHostTree } from "../../substrate/runtime/host-tree-tar/index.mjs";
-import { DEPLOY_CACHE_NAMESPACES, SnapshotLayout, containerImagesBundlePath, contributionPath, isRestorableContainerImageName, isSafeSnapshotPathSegment } from "./descriptor.mjs";
+import { SnapshotLayout, containerImagesBundlePath, contributionPath, deployCacheSubtreeRelPaths, isRestorableContainerImageName, isSafeSnapshotPathSegment } from "./descriptor.mjs";
 import { makePhaseFailer } from "./phase-error.mjs";
 import { CACHE_DIR_NAME } from "./wipe.mjs";
 import { readImageBundleTags, verifyImageBundleTags } from "./image-bundle-tags.mjs";
 import { writeArtifactIntegrity } from "./integrity.mjs";
 import { mergeContributions, requireIdentity } from "./identity-guard.mjs";
-import { readSnapshotStateDocument, writeSnapshotStateDocument } from "./state-document.mjs";
-import { Effect, Exit, FileSystem, Schema, Stream } from "effect";
+import { Duration, Effect, Exit, FileSystem, Schema, Stream } from "effect";
 //#region src/orchestrators/snapshot/capture.ts
+/** Synthetic "plugin" key for the orchestrator-owned deploy-cache subtrees.
+*  The cache is per-stack runtime state (not plugin-declared), so the capture
+*  orchestrator injects `cache/<ns>` subtrees under this key rather than
+*  attributing them to any one plugin. Distinct from any real plugin name (the
+*  `__…__` sentinel shape), so it cannot collide with a participant. */
+const DEPLOY_CACHE_SUBTREE_PLUGIN = "__deploy-cache__";
 /** Tagged failure during one capture step. `phase` discriminates so
 *  the user-facing message names the failing step. */
 var CapturePhaseError = class extends Schema.TaggedErrorClass()("SnapshotCapturePhaseError", {
 	phase: Schema.Literals([
 		"enumerate-containers",
-		"quiesce",
-		"pause",
+		"stop",
 		"commit",
 		"save-images",
 		"tar-subtree",
 		"tar-host-tree",
-		"read-state",
-		"write-state",
 		"write-contribution",
 		"write-meta",
 		"write-integrity",
-		"unpause"
+		"retag-image",
+		"remove-container",
+		"resume"
 	]),
 	plugin: Schema.optional(Schema.String),
 	detail: Schema.String,
@@ -41,12 +45,12 @@ const validateSnapshotPathSegment = (kind, value, phase, plugin) => isSafeSnapsh
 	plugin,
 	detail: `unsafe snapshot ${kind} path segment: ${value}`
 }));
-const validateCapturedContainer = (handle, labels, participant) => Effect.gen(function* () {
-	yield* validateSnapshotPathSegment("plugin", labels.plugin, "commit", participant.plugin);
-	yield* validateSnapshotPathSegment("role", labels.role, "commit", participant.plugin);
+const validateCapturedContainer = (handle, labels, plugin) => Effect.gen(function* () {
+	yield* validateSnapshotPathSegment("plugin", labels.plugin, "commit", plugin);
+	yield* validateSnapshotPathSegment("role", labels.role, "commit", plugin);
 	if (!isRestorableContainerImageName(handle.imageName)) return yield* Effect.fail(new CapturePhaseError({
 		phase: "commit",
-		plugin: participant.plugin,
+		plugin,
 		detail: `container ${handle.name} imageName is not a restorable Docker tag destination: ${handle.imageName}`
 	}));
 });
@@ -57,55 +61,40 @@ const detectContainerArtifactCollisions = (planned) => Effect.gen(function* () {
 		const previous = seen.get(key);
 		if (previous !== void 0) return yield* Effect.fail(new CapturePhaseError({
 			phase: "commit",
-			plugin: candidate.participant.plugin,
+			plugin: candidate.plugin,
 			detail: `duplicate managed container snapshot identity ${key} for ${previous.handle.name} and ${candidate.handle.name}`
 		}));
 		seen.set(key, candidate);
 	}
 });
-/**
-* Enumerate a participant's live managed containers, then run its
-* optional app-level quiesce hook. Already-paused, exited, and
-* created containers are committed as-is and are not unpaused by
-* capture finalization.
-*
-* Architecture § Invariants: "A running container must be paused
-* around the writable-layer commit; the unpause must fire on both
-* success and failure paths (no orphaned paused containers). A
-* stopped container is already quiescent and must not be paused."
-*
-* The default quiescence is `pauseAndCommit`; participants that need
-* an application-level flush (postgres, RocksDB) declare a longer-grace
-* `quiesce` effect on their decl — the orchestrator runs it BEFORE
-* `pauseAndCommit`.
-*/
-const quiesceParticipant = (participant, runtime) => Effect.gen(function* () {
-	const labelTuples = participant.decl.managedContainers ?? [];
+/** Enumerate a participant's live managed containers by its declared
+*  label tuples. `inspectByLabels` matches running AND stopped/created
+*  containers (`docker ps -a`). */
+const enumerateParticipantContainers = (plugin, labelTuples, runtime) => Effect.gen(function* () {
 	const containers = [];
 	for (const tuple of labelTuples) {
-		const matched = yield* runtime.inspectByLabels(tuple).pipe(Effect.catch(failPhase("enumerate-containers", `inspect by labels failed for ${tuple.plugin}/${tuple.role}`, participant.plugin)));
-		for (const handle of matched) if (handle.status === "running") containers.push({
-			handle,
-			labels: tuple,
-			unpauseAfterCapture: true
-		});
-		else if (handle.status === "paused" || handle.status === "exited" || handle.status === "created") containers.push({
+		const matched = yield* runtime.inspectByLabels(tuple).pipe(Effect.catch(failPhase("enumerate-containers", `inspect by labels failed for ${tuple.plugin}/${tuple.role}`, plugin)));
+		for (const handle of matched) containers.push({
 			handle,
-			labels: tuple,
-			unpauseAfterCapture: false
+			labels: tuple
 		});
 	}
-	if (participant.decl.quiesce) yield* participant.decl.quiesce.pipe(Effect.scoped, Effect.ignore);
 	return containers;
-}).pipe(Effect.withSpan("orchestrator.snapshot.capture.quiesce"));
-/** Commit one container's writable layer to a temporary snapshot image tag. */
-const commitContainerToImage = (handle, labels, runtime, participant, registerCommittedRef) => Effect.gen(function* () {
-	const imageRef = yield* runtime.pauseAndCommit(handle).pipe(Effect.catch(failPhase("commit", `pauseAndCommit failed for ${handle.name}`, participant.plugin)));
+});
+/** Commit one STOPPED container's writable layer to a temporary snapshot
+*  image tag. The container has already been gracefully stopped (RocksDB
+*  flushed), so this commits the faithful flushed layer. */
+const commitStoppedContainer = (handle, labels, runtime, plugin, registerCommittedRef) => Effect.gen(function* () {
+	const stoppedHandle = {
+		...handle,
+		status: "exited"
+	};
+	const imageRef = yield* runtime.pauseAndCommit(stoppedHandle).pipe(Effect.catch(failPhase("commit", `commit failed for ${handle.name}`, plugin)));
 	const snapshotTag = imageRef.tag;
 	yield* registerCommittedRef(imageRef);
 	if (!isRestorableContainerImageName(snapshotTag)) return yield* Effect.fail(new CapturePhaseError({
 		phase: "commit",
-		plugin: participant.plugin,
+		plugin,
 		detail: `committed image for ${handle.name} did not receive a restorable snapshot tag`
 	}));
 	return {
@@ -118,16 +107,16 @@ const commitContainerToImage = (handle, labels, runtime, participant, registerCo
 		},
 		imageRef
 	};
-}).pipe(Effect.withSpan("orchestrator.snapshot.capture.commit"));
+});
 const saveCommittedImages = (committed, stagingDir, runtime) => Effect.gen(function* () {
 	if (committed.length === 0) return;
 	const fs = yield* FileSystem.FileSystem;
 	const tarPath = containerImagesBundlePath();
 	const tarDest = `${stagingDir}/${tarPath}`;
 	yield* fs.makeDirectory(`${stagingDir}/${SnapshotLayout.containersDir}`, { recursive: true }).pipe(Effect.catch(failPhase("save-images", `mkdir containers dir failed`)));
-	yield* Stream.run(runtime.saveImages(committed.map((entry) => entry.imageRef), { removeAfterSave: true }), fs.sink(tarDest)).pipe(Effect.catch(failPhase("save-images", `save ${committed.length} committed container images to ${tarDest} failed`)));
+	yield* Stream.run(runtime.saveImages(committed.map((entry) => entry.imageRef), { removeAfterSave: false }), fs.sink(tarDest)).pipe(Effect.catch(failPhase("save-images", `save ${committed.length} committed container images to ${tarDest} failed`)));
 	yield* verifyImageBundleTags(tarPath, yield* readImageBundleTags(tarDest, tarPath).pipe(Effect.catch(failImageBundleTagScan)), committed.map((entry) => entry.captured.snapshotTag)).pipe(Effect.catch(failImageBundleTagScan));
-}).pipe(Effect.withSpan("orchestrator.snapshot.capture.save-images"));
+});
 const cleanupCommittedRefs = (runtime, refs) => Effect.forEach(refs, (ref) => runtime.removeImage(ref).pipe(Effect.catch((cause) => Effect.logWarning(`remove committed snapshot image ${ref.tag} failed during capture cleanup: ${String(cause)}`))), { concurrency: "unbounded" }).pipe(Effect.asVoid);
 const isSafeSubtreePath = (relPath) => relPath !== "" && relPath !== "." && !relPath.startsWith("/") && !relPath.split(/[\\/]+/).includes("..");
 /** Resolve declared subtrees against the live stack root. Missing
@@ -162,203 +151,190 @@ const writeHostTreeTar = (stackRoot, subtrees, tarDest) => Effect.gen(function*
 		relPaths: subtrees.map((s) => s.relPath)
 	});
 	yield* Stream.run(archive, fs.sink(tarDest)).pipe(Effect.catch(failPhase("tar-host-tree", `tar host-tree (${subtrees.length} subtrees) to ${tarDest} failed`)));
-}).pipe(Effect.withSpan("orchestrator.snapshot.capture.tar-host-tree"));
+});
+/**
+* PRE-STOP gather. Runs while every plugin is still acquired/live:
+*
+*   - Run each participant's `captureIdentity` / `captureContribution`
+*     Effects to concrete values (they read live resolved plugin state).
+*   - Snapshot each participant's `managedContainers` label tuples and
+*     declared `subtrees` as plain data.
+*   - Merge the identity slices with the SAME `mergeContributions`
+*     predicate the restore-side guard uses (so intra-capture conflicts
+*     fail HERE, at the capture site, before any stop).
+*   - `requireIdentity` (fail-closed) HERE so an empty/conflicting
+*     identity short-circuits BEFORE the bounce stops anything.
+*
+* The returned `GatheredCapture` holds no live registry handles; it
+* survives the stop + recreate.
+*/
+const gatherCaptureParticipants = (participants) => Effect.gen(function* () {
+	const identityContributions = [];
+	const gathered = [];
+	const participantKeys = [];
+	for (const participant of participants) {
+		const identitySlice = yield* participant.captureIdentity;
+		const opaqueState = yield* participant.captureContribution;
+		identityContributions.push({
+			plugin: participant.plugin,
+			slice: identitySlice
+		});
+		gathered.push({
+			plugin: participant.plugin,
+			labelTuples: participant.decl.managedContainers ?? [],
+			identitySlice,
+			opaqueState
+		});
+		participantKeys.push(participant.plugin);
+	}
+	const identityMerged = yield* mergeContributions(identityContributions);
+	yield* requireIdentity(identityMerged, "snapshot");
+	const pluginSubtrees = participants.flatMap((p) => p.decl.subtrees.map((relPath) => ({
+		plugin: p.plugin,
+		relPath,
+		missingTolerance: p.decl.missingTolerance,
+		secretMaterial: p.decl.secretMaterial ?? false
+	})));
+	return {
+		participants: gathered,
+		identityMerged,
+		declaredSubtrees: [...deployCacheSubtreeRelPaths(CACHE_DIR_NAME).map((relPath) => ({
+			plugin: DEPLOY_CACHE_SUBTREE_PLUGIN,
+			relPath,
+			missingTolerance: "fine",
+			secretMaterial: false
+		})), ...pluginSubtrees],
+		participantKeys
+	};
+});
+/** Default graceful-stop grace — mirrors the walrus storage-node grace so
+*  RocksDB flushes before the commit captures the writable layer. */
+const DEFAULT_CAPTURE_STOP_GRACE_SECONDS = 20;
 /**
-* Populate `stagingDir` with a complete snapshot artifact.
+* Populate `stagingDir` with a complete snapshot artifact via the bounce:
+* gather (live) → graceful-stop (flush) → commit + tar + meta → retag
+* committed images onto original names + hard-rm stopped containers →
+* resume (recreate + wait-write-ready).
 *
 * Discipline:
 *   - Iterate participants — no service names appear.
-*   - Pause-around-commit with always-unpause via `addFinalizer`.
-*   - Mode bits preserved by the host-tree tar primitive.
+*   - Identity gathered + fail-closed BEFORE any stop.
+*   - Graceful stop (NOT pause) so RocksDB/WAL flush — the committed image
+*     is faithful.
 *   - meta.json is written LAST so a crashed save leaves the artifact
-*     invisible to the catalog (architecture § "Partial saves are inert").
+*     invisible to the catalog.
+*   - Resume is recreate-from-image (injected), NEVER `docker start`.
 *
-* Caller wraps this in `stageAndSwap` + `acquireReservation` + the
-* stack lock.
+* Caller wraps the staging build in `stageAndSwap` (the publish) — but the
+* retag/hard-rm/resume tail runs AFTER the swap so a publish failure leaves
+* the live stack untouched (only stopped, recoverable by the next boot).
 */
 const runCapture = (inputs) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
-	yield* Effect.annotateCurrentSpan({
-		"devstack.snapshot.phase": "capture",
-		"devstack.snapshot.id": inputs.snapshotId
-	});
-	const report = (progress) => inputs.onProgress?.(progress) ?? Effect.void;
+	const grace = Duration.seconds(inputs.stopGraceSeconds ?? DEFAULT_CAPTURE_STOP_GRACE_SECONDS);
+	const gathered = yield* gatherCaptureParticipants(inputs.participants);
 	return yield* Effect.scoped(Effect.gen(function* () {
 		const capturedContainers = [];
-		const pauseIntended = [];
-		const pauseConfirmed = [];
-		yield* Effect.addFinalizer(() => Effect.gen(function* () {
-			if (pauseIntended.length > 0) yield* report({
-				phase: "resuming",
-				detail: `unpausing ${pauseIntended.length} container${pauseIntended.length === 1 ? "" : "s"}`,
-				pausedContainers: pauseConfirmed.length,
-				totalContainers: pauseIntended.length
-			});
-			yield* Effect.forEach(pauseIntended, (handle) => inputs.runtime.unpause(handle).pipe(Effect.catch((cause) => Effect.logWarning(`unpause(${handle.name}) failed during snapshot capture: ${String(cause)}`))), { concurrency: "unbounded" });
-		}).pipe(Effect.asVoid));
-		const plannedContainers = [];
 		const committedRefs = [];
 		yield* Effect.addFinalizer((exit) => Exit.isFailure(exit) ? cleanupCommittedRefs(inputs.runtime, committedRefs) : Effect.void);
-		yield* report({
-			phase: "quiescing",
-			detail: `checking ${inputs.participants.length} snapshot participant${inputs.participants.length === 1 ? "" : "s"}`
-		});
-		for (const participant of inputs.participants) {
-			const containers = yield* quiesceParticipant(participant, inputs.runtime);
-			for (const { handle, labels, unpauseAfterCapture } of containers) {
-				yield* validateCapturedContainer(handle, labels, participant);
+		const plannedContainers = [];
+		for (const g of gathered.participants) {
+			const containers = yield* enumerateParticipantContainers(g.plugin, g.labelTuples, inputs.runtime);
+			for (const { handle, labels } of containers) {
+				yield* validateCapturedContainer(handle, labels, g.plugin);
 				plannedContainers.push({
 					handle,
 					labels,
-					unpauseAfterCapture,
-					participant
+					plugin: g.plugin
 				});
 			}
 		}
 		yield* detectContainerArtifactCollisions(plannedContainers);
-		const runningContainers = plannedContainers.filter((entry) => entry.unpauseAfterCapture);
-		if (runningContainers.length > 0) yield* report({
-			phase: "pausing",
-			detail: `pausing ${runningContainers.length} running container${runningContainers.length === 1 ? "" : "s"}`,
-			pausedContainers: 0,
-			totalContainers: runningContainers.length
-		});
-		const readyContainers = [];
-		for (const entry of plannedContainers) {
-			const { handle, unpauseAfterCapture } = entry;
-			if (unpauseAfterCapture) {
-				pauseIntended.push(handle);
-				yield* inputs.runtime.pause(handle).pipe(Effect.catch(failPhase("pause", `pause failed for ${handle.name}`, entry.participant.plugin)));
-				pauseConfirmed.push(handle);
-			}
-			readyContainers.push({
-				...entry,
-				commitHandle: unpauseAfterCapture ? {
-					...handle,
-					status: "paused"
-				} : handle
-			});
-		}
-		if (runningContainers.length > 0) yield* report({
-			phase: "paused",
-			detail: `stack paused for snapshot (${pauseConfirmed.length}/${runningContainers.length} containers)`,
-			pausedContainers: pauseConfirmed.length,
-			totalContainers: runningContainers.length
+		yield* Effect.forEach(plannedContainers, (entry) => inputs.runtime.stop(entry.handle, grace).pipe(Effect.catch(failPhase("stop", `graceful stop failed for ${entry.handle.name}`, entry.plugin))), {
+			concurrency: "unbounded",
+			discard: true
 		});
 		const committedContainers = [];
-		if (readyContainers.length > 0) yield* report({
-			phase: "capturing-containers",
-			detail: `committing ${readyContainers.length} container${readyContainers.length === 1 ? "" : "s"}`,
-			pausedContainers: pauseConfirmed.length,
-			totalContainers: runningContainers.length
-		});
-		for (const { commitHandle, labels, participant } of readyContainers) {
-			const committed = yield* commitContainerToImage(commitHandle, labels, inputs.runtime, participant, (ref) => Effect.sync(() => {
+		for (const { handle, labels, plugin } of plannedContainers) {
+			const committed = yield* commitStoppedContainer(handle, labels, inputs.runtime, plugin, (ref) => Effect.sync(() => {
 				committedRefs.push(ref);
 			}));
 			committedContainers.push(committed);
 			capturedContainers.push(committed.captured);
 		}
-		if (committedContainers.length > 0) yield* report({
-			phase: "saving-images",
-			detail: `saving ${committedContainers.length} committed image${committedContainers.length === 1 ? "" : "s"}`,
-			pausedContainers: pauseConfirmed.length,
-			totalContainers: runningContainers.length
-		});
 		yield* saveCommittedImages(committedContainers, inputs.stagingDir, inputs.runtime);
-		const subtrees = yield* resolveCapturedSubtrees([...inputs.participants.flatMap((p) => p.decl.subtrees.map((relPath) => ({
-			plugin: p.plugin,
-			relPath,
-			missingTolerance: p.decl.missingTolerance,
-			secretMaterial: p.decl.secretMaterial ?? false
-		}))), ...DEPLOY_CACHE_NAMESPACES.map((ns) => ({
-			plugin: "snapshot/deploy-cache",
-			relPath: `${CACHE_DIR_NAME}/${ns}`,
-			missingTolerance: "fine",
-			secretMaterial: false
-		}))], inputs.runtimeStackRoot);
+		const subtrees = yield* resolveCapturedSubtrees(gathered.declaredSubtrees, inputs.runtimeStackRoot);
 		const hostTreeIncluded = subtrees.length > 0;
-		if (hostTreeIncluded) {
-			yield* report({
-				phase: "capturing-host-tree",
-				detail: `archiving ${subtrees.length} host subtree${subtrees.length === 1 ? "" : "s"}`,
-				pausedContainers: pauseConfirmed.length,
-				totalContainers: runningContainers.length
-			});
-			yield* writeHostTreeTar(inputs.runtimeStackRoot, subtrees, `${inputs.stagingDir}/${SnapshotLayout.hostTreeTar}`);
-		}
-		if (yield* fs.exists(inputs.stateFilePath).pipe(Effect.catch(() => Effect.succeed(false)))) {
-			yield* report({
-				phase: "saving-state",
-				detail: "copying runtime state",
-				pausedContainers: pauseConfirmed.length,
-				totalContainers: runningContainers.length
-			});
-			const stateDoc = yield* readSnapshotStateDocument(inputs.stateFilePath).pipe(Effect.catch(failPhase("read-state", `state.json failed schema validation`)));
-			yield* writeSnapshotStateDocument(`${inputs.stagingDir}/${SnapshotLayout.stateFile}`, stateDoc).pipe(Effect.catch(failPhase("write-state", `write state.json failed`)));
-		}
-		yield* report({
-			phase: "saving-contributions",
-			detail: `writing ${inputs.participants.length} contribution document${inputs.participants.length === 1 ? "" : "s"}`,
-			pausedContainers: pauseConfirmed.length,
-			totalContainers: runningContainers.length
-		});
+		if (hostTreeIncluded) yield* writeHostTreeTar(inputs.runtimeStackRoot, subtrees, `${inputs.stagingDir}/${SnapshotLayout.hostTreeTar}`);
 		yield* fs.makeDirectory(`${inputs.stagingDir}/${SnapshotLayout.contributionsDir}`, { recursive: true }).pipe(Effect.catch(failPhase("write-contribution", `mkdir contributions dir failed`)));
-		const identityContributions = [];
-		const stateByParticipant = /* @__PURE__ */ new Map();
-		const participantKeys = [];
-		for (const participant of inputs.participants) {
-			const identity = yield* participant.captureIdentity;
-			identityContributions.push({
-				plugin: participant.plugin,
-				slice: identity
-			});
-			const state = yield* participant.captureContribution;
-			stateByParticipant.set(participant.plugin, state);
-		}
-		const identityMerged = yield* mergeContributions(identityContributions);
-		for (const participant of inputs.participants) {
-			const identity = identityContributions.find((c) => c.plugin === participant.plugin)?.slice ?? {};
-			const state = stateByParticipant.get(participant.plugin);
+		for (const g of gathered.participants) {
 			const doc = {
 				version: 1,
-				plugin: participant.plugin,
-				identity,
-				...state === void 0 ? {} : { opaqueState: {
+				plugin: g.plugin,
+				identity: g.identitySlice,
+				...g.opaqueState === void 0 ? {} : { opaqueState: {
 					encoding: "json",
-					value: state
+					value: g.opaqueState
 				} }
 			};
-			yield* fs.writeFileString(`${inputs.stagingDir}/${contributionPath(participant.plugin)}`, JSON.stringify(doc, null, 2)).pipe(Effect.catch(failPhase("write-contribution", `write contribution doc failed`, participant.plugin)));
-			participantKeys.push(participant.plugin);
+			yield* fs.writeFileString(`${inputs.stagingDir}/${contributionPath(g.plugin)}`, JSON.stringify(doc, null, 2)).pipe(Effect.catch(failPhase("write-contribution", `write contribution doc failed`, g.plugin)));
 		}
-		yield* requireIdentity(identityMerged, "snapshot");
-		yield* report({
-			phase: "writing-metadata",
-			detail: "finalizing snapshot artifact",
-			pausedContainers: pauseConfirmed.length,
-			totalContainers: runningContainers.length
-		});
 		const meta = {
-			version: 3,
+			version: 4,
 			id: inputs.snapshotId,
 			label: inputs.label,
 			createdAt: Date.now(),
 			app: inputs.app,
 			stack: inputs.stack,
 			network: inputs.network,
+			graphInput: inputs.graphInput,
 			hostTreeIncluded,
 			subtrees,
 			containers: capturedContainers,
-			identity: identityMerged,
-			participants: participantKeys
+			identity: gathered.identityMerged,
+			participants: [...gathered.participantKeys]
 		};
 		yield* fs.writeFileString(`${inputs.stagingDir}/${SnapshotLayout.metaFile}`, JSON.stringify(meta, null, 2)).pipe(Effect.catch(failPhase("write-meta", `write meta.json failed`)));
 		yield* writeArtifactIntegrity(inputs.stagingDir).pipe(Effect.catch(failPhase("write-integrity", `write integrity.json failed`)));
 		return meta;
 	}));
-}).pipe(Effect.withSpan("orchestrator.snapshot.capture"));
+});
+/**
+* The post-publish bounce tail: retag each committed image onto its
+* container's ORIGINAL image name (so the resume's recreate-from-image
+* boots the node on its just-committed, flushed layer), hard-rm the stopped
+* containers, then run the injected resume (recreate + wait-write-ready).
+*
+* Runs AFTER `stageAndSwap` publishes the artifact, so a publish failure
+* never reaches here — the live stack is only stopped (recoverable). The
+* retag aliases the original image name onto the committed layer; restore
+* uses the SAME retag-to-original-name mechanism with its loaded bundle, so
+* capture and restore resume identically (recreate-from-fresh off an image
+* whose name now resolves to the snapshot layer).
+*
+* This is NEVER expressed as `docker start` — walrus storage nodes EXIT on
+* `docker start` after a graceful stop; the resume's recreate is a fresh
+* `docker run` that re-syncs and the write-ready ready-gate blocks on.
+*/
+const resumeAfterCapture = (meta, inputs) => Effect.gen(function* () {
+	for (const captured of meta.containers) {
+		const oldDigest = yield* inputs.runtime.inspectImageDigest(captured.imageName).pipe(Effect.catch(() => Effect.succeed(null)));
+		yield* inputs.runtime.tagImage({
+			digest: captured.snapshotTag,
+			tag: captured.snapshotTag
+		}, captured.imageName, { removeSourceAfterTag: true }).pipe(Effect.catch(failPhase("retag-image", `tag committed image ${captured.snapshotTag} as ${captured.imageName} failed`, captured.plugin)));
+		const newDigest = yield* inputs.runtime.inspectImageDigest(captured.imageName).pipe(Effect.catch(() => Effect.succeed(null)));
+		if (oldDigest !== null && oldDigest !== newDigest) yield* inputs.runtime.removeImage({ digest: oldDigest }).pipe(Effect.catch((cause) => Effect.logWarning(`GC of superseded image layer ${oldDigest} for ${captured.imageName} failed (best-effort): ${String(cause)}`)));
+	}
+	for (const captured of meta.containers) yield* inputs.runtime.removeManagedContainers({
+		app: inputs.app,
+		stack: inputs.stack,
+		plugin: captured.plugin,
+		role: captured.role
+	}).pipe(Effect.catch(failPhase("remove-container", `remove managed containers for ${captured.plugin}/${captured.role} failed`, captured.plugin)));
+	if (inputs.resume !== void 0) yield* inputs.resume.pipe(Effect.catch(failPhase("resume", `stack resume after capture failed`)));
+});
 //#endregion
-export { CapturePhaseError, runCapture };
+export { CapturePhaseError, resumeAfterCapture, runCapture };
 
 //# sourceMappingURL=capture.mjs.map