@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/orchestrators/snapshot/pending-marker.mjs

@@ -0,0 +1,99 @@
+import { versionedDocSchema } from "../../substrate/versioned-doc-schema.mjs";
+import { atomicWriteFile } from "../../substrate/runtime/atomic-write.mjs";
+import { Effect, FileSystem, Schema } from "effect";
+const RESTORE_PENDING_FILE_NAME = "snapshot.restore-pending.json";
+const RestorePendingContainerSchema = Schema.Struct({
+	plugin: Schema.String,
+	role: Schema.String,
+	targetImageName: Schema.String,
+	stagedImageTag: Schema.String,
+	/** Content-addressed image identity (e.g. `sha256:...`). The
+	*  scanner uses this as the third-and-final recovery source when
+	*  both `targetImageName` and `stagedImageTag` have been removed
+	*  from the daemon (e.g. operator `docker system prune` between
+	*  crash and restart). Digests survive prune because they ARE the
+	*  image — Docker can re-tag from any digest still backed by a
+	*  pinned layer. */
+	digest: Schema.String
+});
+/** v2 marker variant — current shape. New variants are added by
+*  appending another `versionedDocSchema(N, ...)` arm to the Union
+*  below; consumers switch on `version` after decode. */
+const RestorePendingDocumentV2Schema = versionedDocSchema(2, {
+	snapshotId: Schema.String,
+	artifactDir: Schema.String,
+	app: Schema.String,
+	stack: Schema.String,
+	network: Schema.String,
+	containers: Schema.Array(RestorePendingContainerSchema)
+});
+/** Discriminated union of every supported marker version. Today only
+*  v2 is on disk; the Union shape exists so a v3 migration is a
+*  one-line `Schema.Union(...v2, ...v3)` extension here plus a new
+*  `case` in the recovery scanner. Stale pre-v2 markers fail decode
+*  cleanly — the scanner translates that into a "leave on disk for
+*  operator review" warning rather than a fatal error. */
+const RestorePendingDocumentSchema = Schema.Union([RestorePendingDocumentV2Schema]);
+/** Path the marker lives at, relative to a runtime stack root or
+*  staged-tree root. */
+const pendingMarkerPath = (root) => `${root}/${RESTORE_PENDING_FILE_NAME}`;
+/** Failure shape for marker IO. The scanner / restore both map this
+*  onto their own typed channels. */
+var RestorePendingMarkerIoError = class extends Schema.TaggedErrorClass()("SnapshotRestorePendingMarkerIoError", {
+	op: Schema.Literals([
+		"read",
+		"write",
+		"remove",
+		"decode"
+	]),
+	path: Schema.String,
+	detail: Schema.String,
+	cause: Schema.optional(Schema.Defect)
+}) {};
+/** Write or rewrite the marker. The serialized payload is one trailing
+*  newline larger than `JSON.stringify(doc, null, 2)`. */
+const writePendingMarker = (root, doc) => Effect.gen(function* () {
+	const path = pendingMarkerPath(root);
+	yield* atomicWriteFile(path, new TextEncoder().encode(`${JSON.stringify(doc, null, 2)}\n`)).pipe(Effect.catch((cause) => Effect.fail(new RestorePendingMarkerIoError({
+		op: "write",
+		path,
+		detail: `write ${RESTORE_PENDING_FILE_NAME} failed`,
+		cause
+	}))));
+});
+/** Build a marker document from the snapshot metadata + outstanding
+*  per-image entries. Caller decides what's outstanding. */
+const makePendingMarkerDocument = (args) => ({
+	version: 2,
+	snapshotId: args.meta.id,
+	artifactDir: args.artifactDir,
+	app: args.meta.app,
+	stack: args.meta.stack,
+	network: args.meta.network,
+	containers: args.containers
+});
+/** Rewrite an existing marker, replacing the `containers` list.
+*  The recovery scanner uses this to whittle the outstanding entry
+*  list down as it retags each image — the next supervise (or the
+*  next loop iteration after a transient daemon hiccup) sees an
+*  up-to-date marker without re-deriving identity from `meta.json`. */
+const rewritePendingMarkerContainers = (doc, containers) => ({
+	...doc,
+	containers
+});
+/** Remove the marker. Idempotent — `force: true` swallows "already
+*  gone". Other IO failures surface as `RestorePendingMarkerIoError`. */
+const removePendingMarker = (root) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = pendingMarkerPath(root);
+	yield* fs.remove(path, { force: true }).pipe(Effect.catch((cause) => Effect.fail(new RestorePendingMarkerIoError({
+		op: "remove",
+		path,
+		detail: `remove ${RESTORE_PENDING_FILE_NAME} failed`,
+		cause
+	}))));
+});
+//#endregion
+export { RESTORE_PENDING_FILE_NAME, RestorePendingDocumentSchema, RestorePendingMarkerIoError, makePendingMarkerDocument, pendingMarkerPath, removePendingMarker, rewritePendingMarkerContainers, writePendingMarker };
+
+//# sourceMappingURL=pending-marker.mjs.map

package/dist/orchestrators/snapshot/pending-marker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-marker.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/pending-marker.ts"],"sourcesContent":["// Restore-pending marker — shared schema + IO between `restore.ts`\n// (writer/clearer) and `recover-pending.ts` (reader/recoverer).\n//\n// Recovery contract:\n//\n//   The marker is written into the snapshot's staged tree BEFORE the\n//   atomic stage-and-swap publish, then survives the swap into the\n//   restored runtime root. After publish, `runRestore` runs the\n//   Docker handoff (promote staged tags → recorded names, remove\n//   captured managed containers) under `Effect.uninterruptible`. If\n//   the process is hard-killed mid-handoff — or any step fails after\n//   K of N images promoted — the marker stays on disk and lists which\n//   `(targetImageName ← stagedImageTag, digest)` operations remain\n//   pending. The digest is the loaded image's content-addressed\n//   identity; the scanner falls back to it when the staging tag has\n//   been pruned from the daemon between crash and restart.\n//\n//   On the next supervise startup, `recoverPendingRestore` reads the\n//   marker, retries each pending entry's `tagImage`, removes the\n//   marker only when every entry verifies, and is idempotent: a\n//   marker present with zero outstanding entries is treated as\n//   already-recovered and cleared in one call.\n//\n//   The marker is updated AFTER EACH successful image promote in the\n//   happy path (see `restore.ts:promoteStagedImages`) so the\n//   recovery scanner only has to address the entries still listed —\n//   it never has to know which of the original N images was the one\n//   that failed.\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport { atomicWriteFile } from '../../substrate/runtime/atomic-write.ts';\nimport { versionedDocSchema } from '../../substrate/versioned-doc-schema.ts';\nimport type { SnapshotMetadata } from './descriptor.ts';\n\nexport const SNAPSHOT_RESTORE_PENDING_VERSION = 2 as const;\nexport const RESTORE_PENDING_FILE_NAME = 'snapshot.restore-pending.json' as const;\n\nexport const RestorePendingContainerSchema = Schema.Struct({\n\tplugin: Schema.String,\n\trole: Schema.String,\n\ttargetImageName: Schema.String,\n\tstagedImageTag: Schema.String,\n\t/** Content-addressed image identity (e.g. `sha256:...`). The\n\t *  scanner uses this as the third-and-final recovery source when\n\t *  both `targetImageName` and `stagedImageTag` have been removed\n\t *  from the daemon (e.g. operator `docker system prune` between\n\t *  crash and restart). Digests survive prune because they ARE the\n\t *  image — Docker can re-tag from any digest still backed by a\n\t *  pinned layer. */\n\tdigest: Schema.String,\n});\nexport type RestorePendingContainer = Schema.Schema.Type<typeof RestorePendingContainerSchema>;\n\nconst RestorePendingDocumentV2Payload = {\n\tsnapshotId: Schema.String,\n\tartifactDir: Schema.String,\n\tapp: Schema.String,\n\tstack: Schema.String,\n\tnetwork: Schema.String,\n\tcontainers: Schema.Array(RestorePendingContainerSchema),\n} as const;\n\n/** v2 marker variant — current shape. New variants are added by\n *  appending another `versionedDocSchema(N, ...)` arm to the Union\n *  below; consumers switch on `version` after decode. */\nexport const RestorePendingDocumentV2Schema = versionedDocSchema(\n\tSNAPSHOT_RESTORE_PENDING_VERSION,\n\tRestorePendingDocumentV2Payload,\n);\nexport type RestorePendingDocumentV2 = Schema.Schema.Type<typeof RestorePendingDocumentV2Schema>;\n\n/** Discriminated union of every supported marker version. Today only\n *  v2 is on disk; the Union shape exists so a v3 migration is a\n *  one-line `Schema.Union(...v2, ...v3)` extension here plus a new\n *  `case` in the recovery scanner. Stale pre-v2 markers fail decode\n *  cleanly — the scanner translates that into a \"leave on disk for\n *  operator review\" warning rather than a fatal error. */\nexport const RestorePendingDocumentSchema = Schema.Union([RestorePendingDocumentV2Schema]);\nexport type RestorePendingDocument = Schema.Schema.Type<typeof RestorePendingDocumentSchema>;\n\n/** Path the marker lives at, relative to a runtime stack root or\n *  staged-tree root. */\nexport const pendingMarkerPath = (root: string): string =>\n\t`${root}/${RESTORE_PENDING_FILE_NAME}`;\n\n/** Failure shape for marker IO. The scanner / restore both map this\n *  onto their own typed channels. */\nexport class RestorePendingMarkerIoError extends Schema.TaggedErrorClass<RestorePendingMarkerIoError>()(\n\t'SnapshotRestorePendingMarkerIoError',\n\t{\n\t\top: Schema.Literals(['read', 'write', 'remove', 'decode']),\n\t\tpath: Schema.String,\n\t\tdetail: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n/** Write or rewrite the marker. The serialized payload is one trailing\n *  newline larger than `JSON.stringify(doc, null, 2)`. */\nexport const writePendingMarker = (\n\troot: string,\n\tdoc: RestorePendingDocument,\n): Effect.Effect<void, RestorePendingMarkerIoError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst path = pendingMarkerPath(root);\n\t\t// The marker is durable cross-process state on the LIVE runtime\n\t\t// root (recovery scanner reads it on the next supervise). Route\n\t\t// through the canonical atomic primitive (STYLE_GUIDE §17) so a\n\t\t// crashed mid-rewrite never leaves the scanner a half-written /\n\t\t// undecodable marker. `atomicWriteFile` (not `atomicWriteJson`)\n\t\t// preserves the exact `JSON.stringify(…, 2)` + trailing-newline\n\t\t// byte shape this writer has always produced.\n\t\tconst bytes = new TextEncoder().encode(`${JSON.stringify(doc, null, 2)}\\n`);\n\t\tyield* atomicWriteFile(path, bytes).pipe(\n\t\t\tEffect.catch(\n\t\t\t\t(cause): Effect.Effect<never, RestorePendingMarkerIoError> =>\n\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\tnew RestorePendingMarkerIoError({\n\t\t\t\t\t\t\top: 'write',\n\t\t\t\t\t\t\tpath,\n\t\t\t\t\t\t\tdetail: `write ${RESTORE_PENDING_FILE_NAME} failed`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\t});\n\n/** Build a marker document from the snapshot metadata + outstanding\n *  per-image entries. Caller decides what's outstanding. */\nexport const makePendingMarkerDocument = (args: {\n\treadonly meta: SnapshotMetadata;\n\treadonly artifactDir: string;\n\treadonly containers: ReadonlyArray<RestorePendingContainer>;\n}): RestorePendingDocument => ({\n\tversion: SNAPSHOT_RESTORE_PENDING_VERSION,\n\tsnapshotId: args.meta.id,\n\tartifactDir: args.artifactDir,\n\tapp: args.meta.app,\n\tstack: args.meta.stack,\n\tnetwork: args.meta.network,\n\tcontainers: args.containers,\n});\n\n/** Rewrite an existing marker, replacing the `containers` list.\n *  The recovery scanner uses this to whittle the outstanding entry\n *  list down as it retags each image — the next supervise (or the\n *  next loop iteration after a transient daemon hiccup) sees an\n *  up-to-date marker without re-deriving identity from `meta.json`. */\nexport const rewritePendingMarkerContainers = (\n\tdoc: RestorePendingDocument,\n\tcontainers: ReadonlyArray<RestorePendingContainer>,\n): RestorePendingDocument => ({\n\t...doc,\n\tcontainers,\n});\n\n/** Remove the marker. Idempotent — `force: true` swallows \"already\n *  gone\". Other IO failures surface as `RestorePendingMarkerIoError`. */\nexport const removePendingMarker = (\n\troot: string,\n): Effect.Effect<void, RestorePendingMarkerIoError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst path = pendingMarkerPath(root);\n\t\tyield* fs.remove(path, { force: true }).pipe(\n\t\t\tEffect.catch(\n\t\t\t\t(cause): Effect.Effect<never, RestorePendingMarkerIoError> =>\n\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\tnew RestorePendingMarkerIoError({\n\t\t\t\t\t\t\top: 'remove',\n\t\t\t\t\t\t\tpath,\n\t\t\t\t\t\t\tdetail: `remove ${RESTORE_PENDING_FILE_NAME} failed`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\t});\n"],"mappings":";;;AAoCA,MAAa,4BAA4B;AAEzC,MAAa,gCAAgC,OAAO,OAAO;CAC1D,QAAQ,OAAO;CACf,MAAM,OAAO;CACb,iBAAiB,OAAO;CACxB,gBAAgB,OAAO;;;;;;;;CAQvB,QAAQ,OAAO;CACf,CAAC;;;;AAeF,MAAa,iCAAiC,mBAAA,GAE7C;CAbA,YAAY,OAAO;CACnB,aAAa,OAAO;CACpB,KAAK,OAAO;CACZ,OAAO,OAAO;CACd,SAAS,OAAO;CAChB,YAAY,OAAO,MAAM,8BAA8B;CAQvD,CACA;;;;;;;AASD,MAAa,+BAA+B,OAAO,MAAM,CAAC,+BAA+B,CAAC;;;AAK1F,MAAa,qBAAqB,SACjC,GAAG,KAAK,GAAG;;;AAIZ,IAAa,8BAAb,cAAiD,OAAO,kBAA+C,CACtG,uCACA;CACC,IAAI,OAAO,SAAS;EAAC;EAAQ;EAAS;EAAU;EAAS,CAAC;CAC1D,MAAM,OAAO;CACb,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CACD,CAAC;;;AAIF,MAAa,sBACZ,MACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,kBAAkB,KAAK;AASpC,QAAO,gBAAgB,MADT,IAAI,aAAa,CAAC,OAAO,GAAG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC,IACrC,CAAC,CAAC,KACnC,OAAO,OACL,UACA,OAAO,KACN,IAAI,4BAA4B;EAC/B,IAAI;EACJ;EACA,QAAQ,SAAS,0BAA0B;EAC3C;EACA,CAAC,CACF,CACF,CACD;EACA;;;AAIH,MAAa,6BAA6B,UAIX;CAC9B,SAAA;CACA,YAAY,KAAK,KAAK;CACtB,aAAa,KAAK;CAClB,KAAK,KAAK,KAAK;CACf,OAAO,KAAK,KAAK;CACjB,SAAS,KAAK,KAAK;CACnB,YAAY,KAAK;CACjB;;;;;;AAOD,MAAa,kCACZ,KACA,gBAC6B;CAC7B,GAAG;CACH;CACA;;;AAID,MAAa,uBACZ,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,OAAO,kBAAkB,KAAK;AACpC,QAAO,GAAG,OAAO,MAAM,EAAE,OAAO,MAAM,CAAC,CAAC,KACvC,OAAO,OACL,UACA,OAAO,KACN,IAAI,4BAA4B;EAC/B,IAAI;EACJ;EACA,QAAQ,UAAU,0BAA0B;EAC5C;EACA,CAAC,CACF,CACF,CACD;EACA"}

package/dist/orchestrators/snapshot/phase-error.mjs

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+//#region src/orchestrators/snapshot/phase-error.ts
+/**
+* Build an orchestrator's curried error-failer from its phase-tagged
+* error constructor.
+*
+* `makePhaseFailer(XPhaseError)` returns
+* `(phase, detail, plugin?) => (cause) => Effect.fail(new XPhaseError(...))`.
+*
+* The `plugin` argument is forwarded only when defined, so call sites
+* for the plugin-less classes (`PrunePhaseError`, `WipePhaseError`)
+* produce the exact same constructor payload as before.
+*/
+const makePhaseFailer = (ErrorClass) => (phase, detail, plugin) => (cause) => Effect.fail(new ErrorClass({
+	phase,
+	detail,
+	cause,
+	...plugin === void 0 ? {} : { plugin }
+}));
+//#endregion
+export { makePhaseFailer };
+
+//# sourceMappingURL=phase-error.mjs.map

package/dist/orchestrators/snapshot/phase-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-error.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/phase-error.ts"],"sourcesContent":["// Shared phase-error failer factory.\n//\n// The four snapshot orchestrators (capture / restore / prune / wipe)\n// each define a phase-tagged error class and the SAME curried failer\n// shape over it:\n//\n//   (phase, detail, plugin?) => (cause: unknown) => Effect.fail(\n//     new XPhaseError({ phase, detail, cause, ...(plugin ? { plugin } : {}) }))\n//\n// The error CLASSES differ (distinct `_tag`s, distinct `phase`\n// literal unions, and only capture/restore carry an optional\n// `plugin`), so the factory is parameterized on the constructor.\n// `makePhaseFailer(ErrorClass)` returns that orchestrator's curried\n// failer; each call site keeps byte-identical behavior.\n//\n// The sibling `lifecycle-prune/errors.ts` failer is intentionally NOT\n// built on this — it is a single-curry-level `(phase) => (cause) =>\n// new LifecyclePruneError(...)` that returns a plain error (not an\n// `Effect.fail`), takes a typed `DockerRuntimeError`, and synthesizes\n// its own `detail`. Different model; left alone.\n\nimport { Effect } from 'effect';\n\n/** Fields the factory needs to construct any of the snapshot phase\n *  errors. `plugin` is optional and only consumed by the error classes\n *  that declare it (capture / restore); the prune / wipe classes ignore\n *  it (the factory never passes a key for those call sites). */\ninterface PhaseErrorFields<Phase extends string> {\n\treadonly phase: Phase;\n\treadonly detail: string;\n\treadonly cause?: unknown;\n\treadonly plugin?: string;\n}\n\n/**\n * Build an orchestrator's curried error-failer from its phase-tagged\n * error constructor.\n *\n * `makePhaseFailer(XPhaseError)` returns\n * `(phase, detail, plugin?) => (cause) => Effect.fail(new XPhaseError(...))`.\n *\n * The `plugin` argument is forwarded only when defined, so call sites\n * for the plugin-less classes (`PrunePhaseError`, `WipePhaseError`)\n * produce the exact same constructor payload as before.\n */\nexport const makePhaseFailer =\n\t<Phase extends string, E>(ErrorClass: new (fields: PhaseErrorFields<Phase>) => E) =>\n\t(\n\t\tphase: Phase,\n\t\tdetail: string,\n\t\tplugin?: string,\n\t): ((cause: unknown) => Effect.Effect<never, E>) =>\n\t(cause) =>\n\t\tEffect.fail(\n\t\t\tnew ErrorClass({ phase, detail, cause, ...(plugin === undefined ? {} : { plugin }) }),\n\t\t);\n"],"mappings":";;;;;;;;;;;;;AA6CA,MAAa,mBACc,gBAEzB,OACA,QACA,YAEA,UACA,OAAO,KACN,IAAI,WAAW;CAAE;CAAO;CAAQ;CAAO,GAAI,WAAW,KAAA,IAAY,EAAE,GAAG,EAAE,QAAQ;CAAG,CAAC,CACrF"}

package/dist/orchestrators/snapshot/prune.mjs

@@ -1,4 +1,7 @@
+import { decodeJsonText } from "../../substrate/runtime/runtime-decode.mjs";
+import { SNAPSHOT_IMAGE_ROLE } from "../../runtime/docker/container.mjs";
 import { SnapshotMetadataSchema } from "./descriptor.mjs";
+import { makePhaseFailer } from "./phase-error.mjs";
 import { SNAPSHOTS_DIR_NAME } from "./wipe.mjs";
 import { Effect, FileSystem, Schema } from "effect";
 //#region src/orchestrators/snapshot/prune.ts
@@ -6,51 +9,31 @@ var PrunePhaseError = class extends Schema.TaggedErrorClass()("SnapshotPrunePhas
 	phase: Schema.Literals([
 		"enumerate-catalog",
 		"read-meta",
-		"classify",
 		"sweep-images",
 		"sweep-directories"
 	]),
 	detail: Schema.String,
 	cause: Schema.optional(Schema.Defect)
 }) {};
-const failPhase = (phase, detail) => (cause) => Effect.fail(new PrunePhaseError({
-	phase,
-	detail,
-	cause
-}));
+const failPhase = makePhaseFailer(PrunePhaseError);
 const readMetaOpt = (dir) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = `${dir}/meta.json`;
 	if (!(yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false))))) return null;
-	const text = yield* fs.readFileString(path).pipe(Effect.catch(failPhase("read-meta", `read ${path} failed`)));
-	const raw = yield* Effect.try({
-		try: () => JSON.parse(text),
-		catch: () => null
+	return yield* decodeJsonText(SnapshotMetadataSchema, yield* fs.readFileString(path).pipe(Effect.catch(failPhase("read-meta", `read ${path} failed`))), {
+		source: path,
+		mkError: () => null
 	}).pipe(Effect.catch(() => Effect.succeed(null)));
-	if (raw === null) return null;
-	return yield* Schema.decodeUnknownEffect(SnapshotMetadataSchema)(raw).pipe(Effect.catch(() => Effect.succeed(null)));
-});
-/** Build the hints document a classifier consumes. Snapshot prune is
-*  age- + identity-based by default; plugin-specific hints flow
-*  through `pluginHints`. */
-const hintsFor = (meta) => ({
-	heartbeatAt: meta.createdAt,
-	claimPid: null,
-	claimStartTime: null,
-	pluginHints: {
-		snapshotId: meta.id,
-		identity: meta.identity,
-		participants: meta.participants
-	}
 });
 /**
-* Walk the snapshot catalog, dispatch each artifact's hints through
-* the contributed classifiers, and reap anything classified
-* `abandoned`. Concurrent sweeps over the same catalog are not
-* supported (caller holds `snapshot.reservation` or `stack.lock`).
+* Walk the snapshot catalog and reap partial artifacts (entries whose
+* `meta.json` is missing or unparseable). Concurrent sweeps over the
+* same catalog are not supported (caller holds `snapshot.reservation`
+* or `stack.lock`).
 *
-* Also removes managed images via the runtime adapter's label-filtered
-* image cleanup.
+* Also removes committed snapshot byproduct images via the runtime
+* adapter's label-filtered image cleanup, scoped to `role:
+* SNAPSHOT_IMAGE_ROLE` so build images are never touched.
 */
 const runPrune = (inputs) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
@@ -65,8 +48,7 @@ const runPrune = (inputs) => Effect.gen(function* () {
 	const reaped = [];
 	for (const id of ids) {
 		const dir = `${catalogDir}/${id}`;
-		const meta = yield* readMetaOpt(dir);
-		if (meta === null) {
+		if ((yield* readMetaOpt(dir)) === null) {
 			yield* fs.remove(dir, {
 				recursive: true,
 				force: true
@@ -75,29 +57,12 @@ const runPrune = (inputs) => Effect.gen(function* () {
 				id,
 				classification: "abandoned"
 			});
-			continue;
-		}
-		const hints = hintsFor(meta);
-		let classification = "alive";
-		for (const { decl } of inputs.classifiers) {
-			const c = yield* decl.classify(hints).pipe(Effect.catch(() => Effect.succeed("alive")));
-			if (c !== "alive") {
-				classification = c;
-				break;
-			}
-		}
-		if (classification === "abandoned") {
-			yield* fs.remove(dir, {
-				recursive: true,
-				force: true
-			}).pipe(Effect.catch(failPhase("sweep-directories", `remove ${dir} failed`)));
-			reaped.push({
-				id,
-				classification
-			});
 		}
 	}
-	const imagesSwept = yield* inputs.runtime.removeManagedImages(inputs.imageLabelFilter).pipe(Effect.catch(failPhase("sweep-images", `image sweep failed`)));
+	const imagesSwept = yield* inputs.runtime.removeManagedImages({
+		...inputs.imageLabelFilter,
+		role: SNAPSHOT_IMAGE_ROLE
+	}).pipe(Effect.catch(failPhase("sweep-images", `image sweep failed`)));
 	return {
 		inspected: ids.length,
 		reaped,
@@ -105,6 +70,6 @@ const runPrune = (inputs) => Effect.gen(function* () {
 	};
 }).pipe(Effect.withSpan("orchestrator.snapshot.prune"));
 //#endregion
-export { runPrune };
+export { PrunePhaseError, runPrune };
 
 //# sourceMappingURL=prune.mjs.map

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 / Decision §10: plugins emit `LivenessClassifier`\n// decls; the L3 prune orchestrator dispatches to them with the\n// registry-persisted hints and reaps anything classified `abandoned`.\n//\n// This module is the snapshot-orchestrator-side of prune: sweeping\n// snapshot-byproduct images, snapshot-catalog directories that lost\n// their owning stack, and cache entries whose chainId is no longer\n// referenced anywhere.\n//\n// The substrate-wide registry prune (engine resources / stack\n// roster) is a sibling orchestrator and lives elsewhere; this file\n// is scoped to snapshot adjacent artifacts.\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport type {\n\tLivenessClassification,\n\tLivenessClassifierDecl,\n\tLivenessHints,\n} from '../../contracts/liveness-classifier.ts';\nimport type { ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport { SnapshotMetadataSchema, type SnapshotMetadata } from './descriptor.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'classify',\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 =\n\t(\n\t\tphase: PrunePhaseError['phase'],\n\t\tdetail: string,\n\t): ((cause: unknown) => Effect.Effect<never, PrunePhaseError>) =>\n\t(cause) =>\n\t\tEffect.fail(new PrunePhaseError({ phase, detail, cause }));\n\n// -----------------------------------------------------------------------------\n// Inputs\n// -----------------------------------------------------------------------------\n\n/** Per-classifier dispatch entry — the L3 prune orchestrator hands\n *  the classifier the persisted hints for one snapshot artifact /\n *  cache entry / etc., and the classifier returns `'alive' | 'dormant'\n *  | 'stale' | 'abandoned'`. */\nexport interface ClassifierDispatch {\n\treadonly plugin: string;\n\treadonly decl: LivenessClassifierDecl;\n}\n\nexport interface PruneInputs {\n\t/** Stack root containing the `snapshots/` catalog. */\n\treadonly stackRoot: string;\n\t/** Filter for managed image cleanup. */\n\treadonly imageLabelFilter: { readonly app: string; readonly stack: string };\n\t/** Classifiers contributed by plugins — same set the L3 prune\n\t *  orchestrator dispatches to. Iterated in declaration order; the\n\t *  first non-`alive` classification wins. */\n\treadonly classifiers: ReadonlyArray<ClassifierDispatch>;\n\treadonly runtime: ContainerRuntime;\n}\n\nexport interface PruneResult {\n\treadonly inspected: number;\n\treadonly reaped: ReadonlyArray<{\n\t\treadonly id: string;\n\t\treadonly classification: LivenessClassification;\n\t}>;\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\tconst raw = yield* Effect.try({\n\t\t\ttry: () => JSON.parse(text) as unknown,\n\t\t\tcatch: () => null,\n\t\t}).pipe(Effect.catch(() => Effect.succeed(null)));\n\t\tif (raw === null) return null;\n\t\treturn yield* Schema.decodeUnknownEffect(SnapshotMetadataSchema)(raw).pipe(\n\t\t\tEffect.catch(() => Effect.succeed(null)),\n\t\t);\n\t});\n\n/** Build the hints document a classifier consumes. Snapshot prune is\n *  age- + identity-based by default; plugin-specific hints flow\n *  through `pluginHints`. */\nconst hintsFor = (meta: SnapshotMetadata): LivenessHints => ({\n\theartbeatAt: meta.createdAt,\n\tclaimPid: null,\n\tclaimStartTime: null,\n\tpluginHints: {\n\t\tsnapshotId: meta.id,\n\t\tidentity: meta.identity,\n\t\tparticipants: meta.participants,\n\t},\n});\n\n// -----------------------------------------------------------------------------\n// Top-level prune\n// -----------------------------------------------------------------------------\n\n/**\n * Walk the snapshot catalog, dispatch each artifact's hints through\n * the contributed classifiers, and reap anything classified\n * `abandoned`. Concurrent sweeps over the same catalog are not\n * supported (caller holds `snapshot.reservation` or `stack.lock`).\n *\n * Also removes managed images via the runtime adapter's label-filtered\n * image cleanup.\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: LivenessClassification }> = [];\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) — classify as `abandoned` by\n\t\t\t// convention. The catalog list already hides them; reaping\n\t\t\t// is just freeing the disk slot.\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\tcontinue;\n\t\t\t}\n\t\t\tconst hints = hintsFor(meta);\n\t\t\tlet classification: LivenessClassification = 'alive';\n\t\t\tfor (const { decl } of inputs.classifiers) {\n\t\t\t\tconst c = yield* decl\n\t\t\t\t\t.classify(hints)\n\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed('alive' as LivenessClassification)));\n\t\t\t\tif (c !== 'alive') {\n\t\t\t\t\tclassification = c;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (classification === 'abandoned') {\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 });\n\t\t\t}\n\t\t}\n\n\t\t// Sweep snapshot-byproduct images via the runtime adapter's\n\t\t// label-scoped image cleanup. Architecture § Decision §8 —\n\t\t// committed snapshot images accumulate; the orchestrator GCs\n\t\t// alongside catalog prune.\n\t\tconst imagesSwept = yield* inputs.runtime\n\t\t\t.removeManagedImages(inputs.imageLabelFilter)\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":"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"}
+{"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"}

package/dist/orchestrators/snapshot/recover-pending.d.mts

@@ -0,0 +1 @@
+import { Effect, FileSystem, Schema } from "effect";

package/dist/orchestrators/snapshot/recover-pending.mjs

@@ -0,0 +1,223 @@
+import { decodeUnknown, parseJsonText } from "../../substrate/runtime/runtime-decode.mjs";
+import { RestorePendingDocumentSchema, pendingMarkerPath, removePendingMarker, rewritePendingMarkerContainers, writePendingMarker } from "./pending-marker.mjs";
+import { Effect, FileSystem, Schema } from "effect";
+//#region src/orchestrators/snapshot/recover-pending.ts
+/** Tagged failure surfaced by the recovery scanner. The `kind`
+*  discriminator lets the supervisor decide how to react: a corrupt
+*  marker is investigable but not fatal (the operator can repair the
+*  Docker side manually); a Docker daemon outage is transient. */
+var RestorePendingRecoveryError = class extends Schema.TaggedErrorClass()("SnapshotRestorePendingRecoveryError", {
+	kind: Schema.Literals([
+		"marker-io",
+		"marker-decode",
+		"retag",
+		"rewrite"
+	]),
+	detail: Schema.String,
+	path: Schema.optional(Schema.String),
+	entry: Schema.optional(Schema.Struct({
+		plugin: Schema.String,
+		role: Schema.String,
+		targetImageName: Schema.String,
+		stagedImageTag: Schema.String,
+		digest: Schema.String
+	})),
+	cause: Schema.optional(Schema.Defect)
+}) {};
+const readMarker = (stackRoot) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = pendingMarkerPath(stackRoot);
+	if (!(yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false))))) return { kind: "absent" };
+	const raw = yield* parseJsonText(yield* fs.readFileString(path).pipe(Effect.catch((cause) => Effect.fail(new RestorePendingRecoveryError({
+		kind: "marker-io",
+		path,
+		detail: `read pending marker failed`,
+		cause
+	})))), {
+		source: path,
+		mkError: (issue) => new RestorePendingRecoveryError({
+			kind: "marker-decode",
+			path,
+			detail: `pending marker is not valid JSON`,
+			cause: issue.cause
+		})
+	});
+	const peekedVersion = typeof raw === "object" && raw !== null && "version" in raw ? raw.version : void 0;
+	if (!SUPPORTED_MARKER_VERSIONS.has(peekedVersion)) return {
+		kind: "unsupported-version",
+		version: peekedVersion,
+		path
+	};
+	const decoded = yield* decodeUnknown(RestorePendingDocumentSchema, raw, {
+		source: path,
+		mkError: (issue) => new RestorePendingRecoveryError({
+			kind: "marker-decode",
+			path,
+			detail: `pending marker failed schema decode`,
+			cause: issue.cause
+		})
+	});
+	switch (decoded.version) {
+		case 2: return {
+			kind: "present",
+			doc: decoded
+		};
+	}
+});
+/** Set of versions the Union decoder above accepts. Keep in sync with
+*  the arms of `RestorePendingDocumentSchema` in `pending-marker.ts` —
+*  the peek uses this to distinguish "stale/future marker version" from
+*  "blob shape mismatch within a known version". */
+const SUPPORTED_MARKER_VERSIONS = new Set([2]);
+const rewriteMarker = (stackRoot, doc, stillPending) => writePendingMarker(stackRoot, rewritePendingMarkerContainers(doc, stillPending)).pipe(Effect.catchTag("SnapshotRestorePendingMarkerIoError", (err) => Effect.fail(new RestorePendingRecoveryError({
+	kind: "rewrite",
+	path: err.path,
+	detail: err.detail,
+	cause: err.cause
+}))));
+/** Probe whether the snapshot's EXPECTED image (addressed by its
+*  content digest) is resolvable on the host, and if so (re)point
+*  `targetImageName` at it.
+*
+*  We deliberately do NOT self-tag the target NAME here. A self-tag of
+*  `targetImageName` onto itself succeeds for ANY image that happens to
+*  sit at that name — including a wholly unrelated managed/base/pulled
+*  image that merely collides with the recorded name. In the prune
+*  scenario (source pruned out-of-band) that name-existence check would
+*  false-positive: it drops the marker as "recovered" while the
+*  snapshot's committed image was never promoted, booting the container
+*  from the WRONG image with the marker silently cleared.
+*
+*  Instead we address the marker's `digest` (the loaded image's
+*  content-addressed `{{.Id}}`, written by the restore promote loop).
+*  The contract resolves `tag ?? digest`, so `tagImage({ digest }, …)`
+*  tags the EXPECTED image onto `targetImageName`:
+*
+*    - expected image still resident by digest (a prior recovery
+*      promoted it; the digest survives `docker system prune` while any
+*      pinned layer keeps it accessible) → tag succeeds, the name is
+*      (idempotently) repaired to point at exactly the snapshot image →
+*      genuinely recovered, drop the marker entry;
+*    - expected image genuinely gone (digest absent) → tag fails →
+*      keep the entry pending.
+*
+*  This is strictly stronger than the old name-existence probe: a
+*  colliding unrelated image at `targetImageName` can no longer trigger
+*  a false drop, because the probe never addresses the name as a source
+*  — only the expected content digest can satisfy it. It also closes
+*  the silent-wrong-image hole by leaving `targetImageName` pointing at
+*  the right image when it does succeed.
+*
+*  `true` → expected image promoted/confirmed at the target name;
+*  `false` → expected image absent OR the probe hit a transient daemon
+*  error. The caller treats `false` as still-pending, so a transient
+*  probe failure errs on the safe side (keep the marker, retry next
+*  supervise) rather than dropping it. */
+const targetImageResolves = (entry, runtime) => runtime.tagImage({ digest: entry.digest }, entry.targetImageName).pipe(Effect.as(true), Effect.catch(() => Effect.succeed(false)));
+/** Attempt to re-tag the target image from each known identity in
+*  decreasing-likelihood-of-success order:
+*
+*    1. `stagedImageTag` — what the original promote loop was retagging
+*       from. Survives the simplest crash (no Docker mutation between
+*       crash and restart).
+*    2. `digest` — the loaded image's content-addressed identity.
+*       Survives `docker system prune` because the digest IS the image:
+*       any pinned layer keeps the image accessible by digest even
+*       after every tag pointing at it has been removed.
+*
+*  When BOTH source attempts fail we must NOT blindly report the entry
+*  as still-pending: a fully missing source (both staged tag and digest
+*  gone as *named/tagged* refs) can mean a *previous* recovery already
+*  promoted this entry to `targetImageName` and a stale marker simply
+*  hasn't been rewritten. Collapsing that case into "still pending"
+*  retags forever and never makes progress. So after both attempts fail
+*  we PROBE whether the EXPECTED image is still resolvable BY ITS
+*  CONTENT DIGEST (see `targetImageResolves`) — not by the target name:
+*
+*    - expected image resolves → (re)point `targetImageName` at it and
+*      treat the entry as recovered (drop the marker entry);
+*    - expected image absent    → the snapshot image genuinely vanished
+*      without a completed promote (e.g. a transient daemon error on
+*      both tag attempts, or operator prune of source AND target), so
+*      keep the entry pending for the next supervise.
+*
+*  Probing the digest rather than the name is what makes this safe: it
+*  stops conflating "absent source because already recovered" with
+*  "transient daemon error", AND prevents an unrelated image that
+*  happens to occupy `targetImageName` from masquerading as a completed
+*  recovery (the wrong-image hole a bare name-existence check left open). */
+const tryRecoverEntry = (entry, runtime) => Effect.gen(function* () {
+	if (yield* runtime.tagImage({
+		digest: entry.digest,
+		tag: entry.stagedImageTag
+	}, entry.targetImageName, { removeSourceAfterTag: true }).pipe(Effect.as(true), Effect.catch(() => Effect.succeed(false)))) return true;
+	if (yield* runtime.tagImage({ digest: entry.digest }, entry.targetImageName, { removeSourceAfterTag: true }).pipe(Effect.as(true), Effect.catch(() => Effect.succeed(false)))) return true;
+	return yield* targetImageResolves(entry, runtime);
+});
+/** Read the restore-pending marker for this stack root and retry any
+*  outstanding image promotions. Idempotent. The supervisor calls this
+*  BEFORE any plugin acquire, so a half-promoted snapshot restore is
+*  reconciled before L2 lookups observe the runtime tree.
+*
+*  Returns a typed summary instead of failing on partial recovery —
+*  the supervisor surfaces "marker remains, N entries outstanding"
+*  via the cascade-formatter so the operator can decide whether to
+*  re-restore or repair Docker out of band. Only marker IO/decode
+*  failures escape as `RestorePendingRecoveryError`. */
+const recoverPendingRestore = (stackRoot, runtime) => Effect.gen(function* () {
+	const result = yield* readMarker(stackRoot);
+	if (result.kind === "absent") return {
+		noMarker: true,
+		snapshotId: null,
+		inspected: 0,
+		recovered: 0,
+		stillPending: [],
+		markerCleared: false
+	};
+	if (result.kind === "unsupported-version") {
+		yield* Effect.logWarning(`snapshot restore-pending marker at ${result.path} has unsupported version ${String(result.version)} (expected 2); leaving on disk for operator review`);
+		return {
+			noMarker: true,
+			snapshotId: null,
+			inspected: 0,
+			recovered: 0,
+			stillPending: [],
+			markerCleared: false
+		};
+	}
+	const doc = result.doc;
+	yield* Effect.annotateCurrentSpan({
+		"devstack.snapshot.recovery.snapshotId": doc.snapshotId,
+		"devstack.snapshot.recovery.pending": doc.containers.length
+	});
+	const stillPending = [];
+	let recovered = 0;
+	for (let i = 0; i < doc.containers.length; i += 1) {
+		const entry = doc.containers[i];
+		if (yield* tryRecoverEntry(entry, runtime)) recovered += 1;
+		else stillPending.push(entry);
+		yield* rewriteMarker(stackRoot, doc, [...stillPending, ...doc.containers.slice(i + 1)]);
+	}
+	let markerCleared = false;
+	if (stillPending.length === 0) {
+		yield* removePendingMarker(stackRoot).pipe(Effect.catchTag("SnapshotRestorePendingMarkerIoError", (err) => Effect.fail(new RestorePendingRecoveryError({
+			kind: "marker-io",
+			path: err.path,
+			detail: err.detail,
+			cause: err.cause
+		}))));
+		markerCleared = true;
+	} else yield* rewriteMarker(stackRoot, doc, stillPending);
+	return {
+		noMarker: false,
+		snapshotId: doc.snapshotId,
+		inspected: doc.containers.length,
+		recovered,
+		stillPending,
+		markerCleared
+	};
+}).pipe(Effect.withSpan("orchestrator.snapshot.recover-pending"));
+//#endregion
+export { RestorePendingRecoveryError, recoverPendingRestore };
+
+//# sourceMappingURL=recover-pending.mjs.map

package/dist/orchestrators/snapshot/recover-pending.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover-pending.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/recover-pending.ts"],"sourcesContent":["// Restore-pending recovery scanner.\n//\n// Recovery contract (mirrors the writer in `pending-marker.ts`):\n//\n//   1. The supervise startup hook calls `recoverPendingRestore` before\n//      any plugin acquire fires, so a half-promoted set of images is\n//      reconciled before any L2 lookup observes the runtime root.\n//   2. The scanner reads `${stackRoot}/snapshot.restore-pending.json`.\n//      Absent marker → no recovery needed, return immediately.\n//   3. For each outstanding entry it asks the runtime to tag the\n//      source onto the target name (`removeSourceAfterTag: true`).\n//      The source is resolved by trying, in order: (a) the staging\n//      tag, (b) the digest. The digest fallback covers the case\n//      where Docker has dropped the staging tag too (e.g. operator\n//      `docker system prune` between crash and restart) — the digest\n//      is the image's content-addressed identity and survives prune.\n//      Successful tag → entry recovered; rewrite the marker with the\n//      entry removed. When BOTH source attempts fail the scanner\n//      probes whether the EXPECTED image (addressed by its content\n//      digest) is still resolvable — a prior recovery may have promoted\n//      it and left the digest resident; if so it (re)points\n//      `targetImageName` at that image and treats the entry as\n//      recovered, otherwise it stays pending. The probe addresses the\n//      digest, NOT the target name, so a colliding unrelated image at\n//      `targetImageName` cannot false-positive a drop.\n//   4. When the outstanding list reaches zero, remove the marker.\n//   5. On a genuine per-entry failure (both sources gone AND the\n//      target not yet visible — e.g. a transient daemon error): keep\n//      the entry in the marker so the next supervise retries. The\n//      scanner returns a typed summary so the supervisor can surface\n//      the partial-recovery state without crashing the boot path.\n//\n// Idempotency: a marker with `containers: []` is treated as\n// already-recovered and removed in one call. Re-running the scanner\n// against a marker for an image that has already been tagged by an\n// out-of-band operator is also safe — `tagImage` is idempotent on the\n// happy path and the failure on a missing staged source is treated\n// as \"entry already recovered\" if the target image is now visible.\n//\n// The scanner sits next to `restore.ts` and shares the marker\n// schema/IO with it via `pending-marker.ts`. The supervisor calls in\n// via `SnapshotOrchestratorService.recoverPendingRestore`, so the L1\n// docker layer requirement is satisfied through the existing service\n// composition — no new substrate plumbing.\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport type { ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport { decodeUnknown, parseJsonText } from '../../substrate/runtime/runtime-decode.ts';\nimport {\n\tpendingMarkerPath,\n\tremovePendingMarker,\n\tRestorePendingMarkerIoError,\n\tRestorePendingDocumentSchema,\n\trewritePendingMarkerContainers,\n\tSNAPSHOT_RESTORE_PENDING_VERSION,\n\twritePendingMarker,\n\ttype RestorePendingContainer,\n\ttype RestorePendingDocument,\n} from './pending-marker.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** Tagged failure surfaced by the recovery scanner. The `kind`\n *  discriminator lets the supervisor decide how to react: a corrupt\n *  marker is investigable but not fatal (the operator can repair the\n *  Docker side manually); a Docker daemon outage is transient. */\nexport class RestorePendingRecoveryError extends Schema.TaggedErrorClass<RestorePendingRecoveryError>()(\n\t'SnapshotRestorePendingRecoveryError',\n\t{\n\t\tkind: Schema.Literals(['marker-io', 'marker-decode', 'retag', 'rewrite']),\n\t\tdetail: Schema.String,\n\t\tpath: Schema.optional(Schema.String),\n\t\tentry: Schema.optional(\n\t\t\tSchema.Struct({\n\t\t\t\tplugin: Schema.String,\n\t\t\t\trole: Schema.String,\n\t\t\t\ttargetImageName: Schema.String,\n\t\t\t\tstagedImageTag: Schema.String,\n\t\t\t\tdigest: Schema.String,\n\t\t\t}),\n\t\t),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\n// -----------------------------------------------------------------------------\n// Summary surface\n// -----------------------------------------------------------------------------\n\nexport interface RestorePendingRecoverySummary {\n\t/** True when no marker was present at the runtime root. */\n\treadonly noMarker: boolean;\n\t/** Snapshot id whose restore was interrupted; null when noMarker. */\n\treadonly snapshotId: string | null;\n\t/** Number of pending entries the scanner observed. */\n\treadonly inspected: number;\n\t/** Number of entries successfully retagged. */\n\treadonly recovered: number;\n\t/** Entries still pending after the scanner finished. Empty in the\n\t *  happy path; populated when one or more retags failed. */\n\treadonly stillPending: ReadonlyArray<RestorePendingContainer>;\n\t/** True when the marker was removed (every entry recovered or\n\t *  marker started empty). */\n\treadonly markerCleared: boolean;\n}\n\n// -----------------------------------------------------------------------------\n// Internal helpers\n// -----------------------------------------------------------------------------\n\n/** Result of reading a marker on disk. `unsupported-version` covers\n *  stale pre-v2 markers whose schema can't safely be recovered (the\n *  v1 shape had no `digest` per entry, and digest is the only identity\n *  that survives `docker system prune`); the Union decode fails them\n *  cleanly and the scanner surfaces them as \"leave on disk for\n *  operator review\" rather than as a fatal decode error. */\ntype ReadMarkerResult =\n\t| { readonly kind: 'absent' }\n\t| { readonly kind: 'unsupported-version'; readonly version: unknown; readonly path: string }\n\t| { readonly kind: 'present'; readonly doc: RestorePendingDocument };\n\nconst readMarker = (\n\tstackRoot: string,\n): Effect.Effect<ReadMarkerResult, RestorePendingRecoveryError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst path = pendingMarkerPath(stackRoot);\n\t\tconst exists = yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false)));\n\t\tif (!exists) return { kind: 'absent' } as const;\n\t\tconst text = yield* fs.readFileString(path).pipe(\n\t\t\tEffect.catch(\n\t\t\t\t(cause): Effect.Effect<never, RestorePendingRecoveryError> =>\n\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\tnew RestorePendingRecoveryError({\n\t\t\t\t\t\t\tkind: 'marker-io',\n\t\t\t\t\t\t\tpath,\n\t\t\t\t\t\t\tdetail: `read pending marker failed`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t),\n\t\t);\n\t\tconst raw = yield* parseJsonText(text, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) =>\n\t\t\t\tnew RestorePendingRecoveryError({\n\t\t\t\t\tkind: 'marker-decode',\n\t\t\t\t\tpath,\n\t\t\t\t\tdetail: `pending marker is not valid JSON`,\n\t\t\t\t\tcause: issue.cause,\n\t\t\t\t}),\n\t\t});\n\t\t// The schema is a `Schema.Union` of every supported marker\n\t\t// version (currently just v2). We peek the discriminant before\n\t\t// the full Union decode so a stale pre-v2 (or future-v3)\n\t\t// marker is reported as `unsupported-version` rather than as a\n\t\t// schema-decode failure — the supervisor surfaces them\n\t\t// differently (operator-review vs corrupt-JSON). A blob whose\n\t\t// `version` matches a known arm but whose inner shape is\n\t\t// malformed still surfaces as `marker-decode`. Future v3\n\t\t// migration appends an arm to the Union in `pending-marker.ts`,\n\t\t// adds the literal to `SUPPORTED_MARKER_VERSIONS`, and adds a\n\t\t// matching `case` in the switch below.\n\t\tconst peekedVersion =\n\t\t\ttypeof raw === 'object' && raw !== null && 'version' in raw\n\t\t\t\t? (raw as { readonly version: unknown }).version\n\t\t\t\t: undefined;\n\t\tif (!SUPPORTED_MARKER_VERSIONS.has(peekedVersion as number)) {\n\t\t\treturn {\n\t\t\t\tkind: 'unsupported-version',\n\t\t\t\tversion: peekedVersion,\n\t\t\t\tpath,\n\t\t\t} as const;\n\t\t}\n\t\tconst decoded: RestorePendingDocument = yield* decodeUnknown(\n\t\t\tRestorePendingDocumentSchema,\n\t\t\traw,\n\t\t\t{\n\t\t\t\tsource: path,\n\t\t\t\tmkError: (issue) =>\n\t\t\t\t\tnew RestorePendingRecoveryError({\n\t\t\t\t\t\tkind: 'marker-decode',\n\t\t\t\t\t\tpath,\n\t\t\t\t\t\tdetail: `pending marker failed schema decode`,\n\t\t\t\t\t\tcause: issue.cause,\n\t\t\t\t\t}),\n\t\t\t},\n\t\t);\n\t\t// Today the Union has one arm (v2). A future v3 migration adds a\n\t\t// `case 3:` arm here AND extends `SUPPORTED_MARKER_VERSIONS`; the\n\t\t// unsupported-version branch becomes reachable once the Union\n\t\t// grows. With a single-arm Union, TypeScript narrows `decoded`\n\t\t// to `never` after `case 2`, so this single return is exhaustive.\n\t\tswitch (decoded.version) {\n\t\t\tcase 2:\n\t\t\t\treturn { kind: 'present', doc: decoded } as const;\n\t\t}\n\t});\n\n/** Set of versions the Union decoder above accepts. Keep in sync with\n *  the arms of `RestorePendingDocumentSchema` in `pending-marker.ts` —\n *  the peek uses this to distinguish \"stale/future marker version\" from\n *  \"blob shape mismatch within a known version\". */\nconst SUPPORTED_MARKER_VERSIONS = new Set<number>([SNAPSHOT_RESTORE_PENDING_VERSION]);\n\nconst rewriteMarker = (\n\tstackRoot: string,\n\tdoc: RestorePendingDocument,\n\tstillPending: ReadonlyArray<RestorePendingContainer>,\n): Effect.Effect<void, RestorePendingRecoveryError, FileSystem.FileSystem> =>\n\twritePendingMarker(stackRoot, rewritePendingMarkerContainers(doc, stillPending)).pipe(\n\t\tEffect.catchTag('SnapshotRestorePendingMarkerIoError', (err: RestorePendingMarkerIoError) =>\n\t\t\tEffect.fail(\n\t\t\t\tnew RestorePendingRecoveryError({\n\t\t\t\t\tkind: 'rewrite',\n\t\t\t\t\tpath: err.path,\n\t\t\t\t\tdetail: err.detail,\n\t\t\t\t\tcause: err.cause,\n\t\t\t\t}),\n\t\t\t),\n\t\t),\n\t);\n\n/** Probe whether the snapshot's EXPECTED image (addressed by its\n *  content digest) is resolvable on the host, and if so (re)point\n *  `targetImageName` at it.\n *\n *  We deliberately do NOT self-tag the target NAME here. A self-tag of\n *  `targetImageName` onto itself succeeds for ANY image that happens to\n *  sit at that name — including a wholly unrelated managed/base/pulled\n *  image that merely collides with the recorded name. In the prune\n *  scenario (source pruned out-of-band) that name-existence check would\n *  false-positive: it drops the marker as \"recovered\" while the\n *  snapshot's committed image was never promoted, booting the container\n *  from the WRONG image with the marker silently cleared.\n *\n *  Instead we address the marker's `digest` (the loaded image's\n *  content-addressed `{{.Id}}`, written by the restore promote loop).\n *  The contract resolves `tag ?? digest`, so `tagImage({ digest }, …)`\n *  tags the EXPECTED image onto `targetImageName`:\n *\n *    - expected image still resident by digest (a prior recovery\n *      promoted it; the digest survives `docker system prune` while any\n *      pinned layer keeps it accessible) → tag succeeds, the name is\n *      (idempotently) repaired to point at exactly the snapshot image →\n *      genuinely recovered, drop the marker entry;\n *    - expected image genuinely gone (digest absent) → tag fails →\n *      keep the entry pending.\n *\n *  This is strictly stronger than the old name-existence probe: a\n *  colliding unrelated image at `targetImageName` can no longer trigger\n *  a false drop, because the probe never addresses the name as a source\n *  — only the expected content digest can satisfy it. It also closes\n *  the silent-wrong-image hole by leaving `targetImageName` pointing at\n *  the right image when it does succeed.\n *\n *  `true` → expected image promoted/confirmed at the target name;\n *  `false` → expected image absent OR the probe hit a transient daemon\n *  error. The caller treats `false` as still-pending, so a transient\n *  probe failure errs on the safe side (keep the marker, retry next\n *  supervise) rather than dropping it. */\nconst targetImageResolves = (\n\tentry: RestorePendingContainer,\n\truntime: ContainerRuntime,\n): Effect.Effect<boolean> =>\n\truntime\n\t\t// Address the EXPECTED image by its content digest (NOT the target\n\t\t// name). `{ digest }` with `tag` omitted forces the contract's\n\t\t// `tag ?? digest` resolution onto the digest, so only the snapshot's\n\t\t// committed image can satisfy this — a name collision cannot.\n\t\t.tagImage({ digest: entry.digest }, entry.targetImageName)\n\t\t.pipe(\n\t\t\tEffect.as(true as const),\n\t\t\tEffect.catch(() => Effect.succeed(false as const)),\n\t\t);\n\n/** Attempt to re-tag the target image from each known identity in\n *  decreasing-likelihood-of-success order:\n *\n *    1. `stagedImageTag` — what the original promote loop was retagging\n *       from. Survives the simplest crash (no Docker mutation between\n *       crash and restart).\n *    2. `digest` — the loaded image's content-addressed identity.\n *       Survives `docker system prune` because the digest IS the image:\n *       any pinned layer keeps the image accessible by digest even\n *       after every tag pointing at it has been removed.\n *\n *  When BOTH source attempts fail we must NOT blindly report the entry\n *  as still-pending: a fully missing source (both staged tag and digest\n *  gone as *named/tagged* refs) can mean a *previous* recovery already\n *  promoted this entry to `targetImageName` and a stale marker simply\n *  hasn't been rewritten. Collapsing that case into \"still pending\"\n *  retags forever and never makes progress. So after both attempts fail\n *  we PROBE whether the EXPECTED image is still resolvable BY ITS\n *  CONTENT DIGEST (see `targetImageResolves`) — not by the target name:\n *\n *    - expected image resolves → (re)point `targetImageName` at it and\n *      treat the entry as recovered (drop the marker entry);\n *    - expected image absent    → the snapshot image genuinely vanished\n *      without a completed promote (e.g. a transient daemon error on\n *      both tag attempts, or operator prune of source AND target), so\n *      keep the entry pending for the next supervise.\n *\n *  Probing the digest rather than the name is what makes this safe: it\n *  stops conflating \"absent source because already recovered\" with\n *  \"transient daemon error\", AND prevents an unrelated image that\n *  happens to occupy `targetImageName` from masquerading as a completed\n *  recovery (the wrong-image hole a bare name-existence check left open). */\nconst tryRecoverEntry = (\n\tentry: RestorePendingContainer,\n\truntime: ContainerRuntime,\n): Effect.Effect<boolean> =>\n\tEffect.gen(function* () {\n\t\t// The contract's docker impl resolves `tag ?? digest`, so when\n\t\t// we want to address by digest we MUST pass `tag: undefined`\n\t\t// (omitting the field) — otherwise the staged tag would still\n\t\t// win the resolution race and we'd be re-running attempt #1.\n\t\tconst stagedFirst = yield* runtime\n\t\t\t.tagImage({ digest: entry.digest, tag: entry.stagedImageTag }, entry.targetImageName, {\n\t\t\t\tremoveSourceAfterTag: true,\n\t\t\t})\n\t\t\t.pipe(\n\t\t\t\tEffect.as(true as const),\n\t\t\t\tEffect.catch(() => Effect.succeed(false as const)),\n\t\t\t);\n\t\tif (stagedFirst) return true;\n\t\tconst digestFallback = yield* runtime\n\t\t\t.tagImage({ digest: entry.digest }, entry.targetImageName, { removeSourceAfterTag: true })\n\t\t\t.pipe(\n\t\t\t\tEffect.as(true as const),\n\t\t\t\tEffect.catch(() => Effect.succeed(false as const)),\n\t\t\t);\n\t\tif (digestFallback) return true;\n\t\t// Both source identities failed. Distinguish \"already promoted by\n\t\t// a prior recovery\" (target now visible → recovered) from a\n\t\t// genuine transient/missing-both failure (target absent → keep\n\t\t// pending). See the doc comment above.\n\t\treturn yield* targetImageResolves(entry, runtime);\n\t});\n\n// -----------------------------------------------------------------------------\n// Public entry point\n// -----------------------------------------------------------------------------\n\n/** Read the restore-pending marker for this stack root and retry any\n *  outstanding image promotions. Idempotent. The supervisor calls this\n *  BEFORE any plugin acquire, so a half-promoted snapshot restore is\n *  reconciled before L2 lookups observe the runtime tree.\n *\n *  Returns a typed summary instead of failing on partial recovery —\n *  the supervisor surfaces \"marker remains, N entries outstanding\"\n *  via the cascade-formatter so the operator can decide whether to\n *  re-restore or repair Docker out of band. Only marker IO/decode\n *  failures escape as `RestorePendingRecoveryError`. */\nexport const recoverPendingRestore = (\n\tstackRoot: string,\n\truntime: ContainerRuntime,\n): Effect.Effect<\n\tRestorePendingRecoverySummary,\n\tRestorePendingRecoveryError,\n\tFileSystem.FileSystem\n> =>\n\tEffect.gen(function* () {\n\t\tconst result = yield* readMarker(stackRoot);\n\t\tif (result.kind === 'absent') {\n\t\t\treturn {\n\t\t\t\tnoMarker: true,\n\t\t\t\tsnapshotId: null,\n\t\t\t\tinspected: 0,\n\t\t\t\trecovered: 0,\n\t\t\t\tstillPending: [],\n\t\t\t\tmarkerCleared: false,\n\t\t\t} as const;\n\t\t}\n\t\tif (result.kind === 'unsupported-version') {\n\t\t\t// Pre-upgrade marker — the schema bumped to v2 to add the\n\t\t\t// `digest` field per entry, and a v1 marker without\n\t\t\t// digests can't be safely recovered (digest is the only\n\t\t\t// identity that survives `docker system prune`). Log a\n\t\t\t// warning and leave the marker alone so the operator can\n\t\t\t// inspect / manually clean up. We treat this as\n\t\t\t// \"no recovery needed\" from the supervisor's perspective.\n\t\t\tyield* Effect.logWarning(\n\t\t\t\t`snapshot restore-pending marker at ${result.path} has unsupported version ${String(\n\t\t\t\t\tresult.version,\n\t\t\t\t)} (expected ${SNAPSHOT_RESTORE_PENDING_VERSION}); leaving on disk for operator review`,\n\t\t\t);\n\t\t\treturn {\n\t\t\t\tnoMarker: true,\n\t\t\t\tsnapshotId: null,\n\t\t\t\tinspected: 0,\n\t\t\t\trecovered: 0,\n\t\t\t\tstillPending: [],\n\t\t\t\tmarkerCleared: false,\n\t\t\t} as const;\n\t\t}\n\t\tconst doc = result.doc;\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.snapshot.recovery.snapshotId': doc.snapshotId,\n\t\t\t'devstack.snapshot.recovery.pending': doc.containers.length,\n\t\t});\n\n\t\tconst stillPending: RestorePendingContainer[] = [];\n\t\tlet recovered = 0;\n\t\tfor (let i = 0; i < doc.containers.length; i += 1) {\n\t\t\tconst entry = doc.containers[i]!;\n\t\t\tconst ok = yield* tryRecoverEntry(entry, runtime);\n\t\t\tif (ok) {\n\t\t\t\trecovered += 1;\n\t\t\t} else {\n\t\t\t\tstillPending.push(entry);\n\t\t\t}\n\t\t\t// Rewrite-after-each so a crash mid-recovery doesn't lose\n\t\t\t// the work-so-far. The new marker carries the still-pending\n\t\t\t// entries plus everything we haven't tried yet. Cheap (one\n\t\t\t// write per image, rare path). Unconditional — the rewrite\n\t\t\t// is idempotent and the final-rewrite below (or\n\t\t\t// `removePendingMarker` when nothing remains) covers steady\n\t\t\t// state.\n\t\t\tconst remaining: RestorePendingContainer[] = [\n\t\t\t\t...stillPending,\n\t\t\t\t...doc.containers.slice(i + 1),\n\t\t\t];\n\t\t\tyield* rewriteMarker(stackRoot, doc, remaining);\n\t\t}\n\n\t\tlet markerCleared = false;\n\t\tif (stillPending.length === 0) {\n\t\t\tyield* removePendingMarker(stackRoot).pipe(\n\t\t\t\tEffect.catchTag('SnapshotRestorePendingMarkerIoError', (err: RestorePendingMarkerIoError) =>\n\t\t\t\t\tEffect.fail(\n\t\t\t\t\t\tnew RestorePendingRecoveryError({\n\t\t\t\t\t\t\tkind: 'marker-io',\n\t\t\t\t\t\t\tpath: err.path,\n\t\t\t\t\t\t\tdetail: err.detail,\n\t\t\t\t\t\t\tcause: err.cause,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\t\tmarkerCleared = true;\n\t\t} else {\n\t\t\t// Final rewrite — the per-loop rewrite covers crash-during-\n\t\t\t// recovery, this one covers the steady-state \"we finished\n\t\t\t// the loop and some entries are still pending\".\n\t\t\tyield* rewriteMarker(stackRoot, doc, stillPending);\n\t\t}\n\n\t\treturn {\n\t\t\tnoMarker: false,\n\t\t\tsnapshotId: doc.snapshotId,\n\t\t\tinspected: doc.containers.length,\n\t\t\trecovered,\n\t\t\tstillPending,\n\t\t\tmarkerCleared,\n\t\t} as const;\n\t}).pipe(Effect.withSpan('orchestrator.snapshot.recover-pending'));\n"],"mappings":"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"}