@mysten-incubation/devstack 0.1.0 → 0.2.0

package/dist/orchestrators/snapshot/image-bundle-tags.mjs

@@ -1,3 +1,4 @@
+import { captureEntry, isSafeArchivePath, makeTarReaderState, processTarChunk, skipEntry, stopScan } from "../../substrate/runtime/tar/reader.mjs";
 import { isRestorableContainerImageName } from "./descriptor.mjs";
 import { Effect, FileSystem, Schema, Stream } from "effect";
 //#region src/orchestrators/snapshot/image-bundle-tags.ts
@@ -9,110 +10,37 @@ const failScan = (detail, cause) => new ImageBundleTagScanError({
 	detail,
 	...cause === void 0 ? {} : { cause }
 });
-const TAR_BLOCK_SIZE = 512;
 const MAX_DOCKER_SAVE_MANIFEST_BYTES = 1024 * 1024;
-const bytesToString = (bytes) => {
-	const nul = bytes.indexOf(0);
-	const end = nul === -1 ? bytes.length : nul;
-	return Buffer.from(bytes.subarray(0, end)).toString("utf8");
-};
-const concatBytes = (a, b) => {
-	if (a.length === 0) return b;
-	if (b.length === 0) return a;
-	const out = new Uint8Array(a.length + b.length);
-	out.set(a, 0);
-	out.set(b, a.length);
-	return out;
-};
-const consumeBytes = (buffer, count) => buffer.subarray(count);
-const isZeroBlock = (block) => block.every((byte) => byte === 0);
-const parseTarSize = (header) => {
-	const raw = bytesToString(header.subarray(124, 136)).trim();
-	if (raw === "") return 0;
-	if (!/^[0-7]+$/.test(raw)) return null;
-	const parsed = Number.parseInt(raw, 8);
-	return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
-};
-const tarPathFromHeader = (header) => {
-	const name = bytesToString(header.subarray(0, 100));
-	const prefix = bytesToString(header.subarray(345, 500));
-	return prefix === "" ? name : `${prefix}/${name}`;
-};
 const normalizedTarEntryPath = (path) => {
 	let normalized = path;
 	while (normalized.startsWith("./")) normalized = normalized.slice(2);
 	return normalized;
 };
-const processDockerSaveMetadataChunk = (state, chunk) => {
-	state.buffer = concatBytes(state.buffer, chunk);
-	while (state.buffer.length > 0) {
-		if (state.content !== null) {
-			const content = state.content;
-			const remaining = content.paddedSize - content.totalBytesRead;
-			const take = Math.min(remaining, state.buffer.length);
-			const contentTake = Math.max(0, Math.min(take, content.size - content.contentBytesRead));
-			if (contentTake > 0) content.chunks.push(state.buffer.subarray(0, contentTake));
-			state.content = {
-				...content,
-				contentBytesRead: content.contentBytesRead + contentTake,
-				totalBytesRead: content.totalBytesRead + take
-			};
-			state.buffer = consumeBytes(state.buffer, take);
-			if (state.content.totalBytesRead === state.content.paddedSize) {
-				const completed = state.content;
-				state.content = null;
-				const entryBytes = completed.chunks.length === 1 ? completed.chunks[0] : Buffer.concat(completed.chunks.map((entry) => Buffer.from(entry)));
-				if (completed.entry === "manifest.json") {
-					state.manifestBytes = entryBytes;
-					return { done: true };
-				}
-				state.indexBytes = entryBytes;
+const onMetadataEntry = (state, entry) => {
+	if (!isSafeArchivePath(entry.path)) return failScan(`docker save bundle has unsafe tar entry path: ${entry.path}`);
+	if ((entry.typeflag === "1" || entry.typeflag === "2") && !isSafeArchivePath(entry.linkPath)) return failScan(`docker save bundle has unsafe tar link target: ${entry.linkPath}`);
+	const entryPath = normalizedTarEntryPath(entry.path);
+	if (entryPath === "manifest.json" || entryPath === "index.json") {
+		if (entry.size > MAX_DOCKER_SAVE_MANIFEST_BYTES) return failScan(`docker save ${entryPath} is too large`);
+		if (entry.size === 0) {
+			if (entryPath === "manifest.json") {
+				state.manifestBytes = new Uint8Array(0);
+				state.done = true;
+				return stopScan();
 			}
-			continue;
-		}
-		if (state.skipRemaining > 0) {
-			const take = Math.min(state.skipRemaining, state.buffer.length);
-			state.skipRemaining -= take;
-			state.buffer = consumeBytes(state.buffer, take);
-			continue;
+			state.indexBytes = new Uint8Array(0);
+			return skipEntry();
 		}
-		if (state.buffer.length < TAR_BLOCK_SIZE) return { done: false };
-		const header = state.buffer.subarray(0, TAR_BLOCK_SIZE);
-		state.buffer = consumeBytes(state.buffer, TAR_BLOCK_SIZE);
-		if (isZeroBlock(header)) continue;
-		const size = parseTarSize(header);
-		if (size === null) return {
-			done: false,
-			error: failScan("docker save bundle has invalid tar size")
-		};
-		const paddedSize = Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;
-		const entryPath = normalizedTarEntryPath(tarPathFromHeader(header));
-		if (entryPath === "manifest.json" || entryPath === "index.json") {
-			if (size > MAX_DOCKER_SAVE_MANIFEST_BYTES) return {
-				done: false,
-				error: failScan(`docker save ${entryPath} is too large`)
-			};
-			if (size === 0) {
-				if (entryPath === "manifest.json") {
-					state.manifestBytes = new Uint8Array(0);
-					return { done: true };
-				}
-				state.indexBytes = new Uint8Array(0);
-				continue;
-			}
-			state.content = {
-				entry: entryPath,
-				size,
-				paddedSize,
-				chunks: [],
-				contentBytesRead: 0,
-				totalBytesRead: 0
-			};
-			continue;
-		}
-		state.skipRemaining = paddedSize;
+		return captureEntry();
 	}
-	return { done: false };
+	return skipEntry();
+};
+const onMetadataContent = (state, entry, body) => {
+	if (normalizedTarEntryPath(entry.path) === "manifest.json") {
+		state.manifestBytes = body;
+		state.done = true;
+	} else state.indexBytes = body;
+	return null;
 };
 const parseDockerSaveManifestTags = (bytes, tarPath) => Effect.gen(function* () {
 	const raw = yield* Effect.try({
@@ -172,16 +100,19 @@ const parseOciImageLayoutIndexTags = (bytes, tarPath) => Effect.gen(function* ()
 const readImageBundleTags = (fullTarPath, tarPath) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const state = {
-		buffer: new Uint8Array(0),
-		skipRemaining: 0,
 		manifestBytes: null,
 		indexBytes: null,
-		content: null
+		done: false
 	};
+	const reader = makeTarReaderState();
 	yield* fs.stream(fullTarPath).pipe(Stream.takeUntilEffect((chunk) => {
-		const result = processDockerSaveMetadataChunk(state, chunk);
-		if (result.error !== void 0) return Effect.fail(result.error);
-		return Effect.succeed(result.done);
+		const error = processTarChunk(reader, chunk, {
+			onEntry: (entry) => onMetadataEntry(state, entry),
+			onContent: (entry, body) => onMetadataContent(state, entry, body),
+			onExtendedError: (detail) => failScan(`docker save bundle ${detail}`)
+		});
+		if (error !== null) return Effect.fail(error);
+		return Effect.succeed(state.done);
 	}), Stream.runDrain, Effect.catch((cause) => cause instanceof ImageBundleTagScanError ? Effect.fail(cause) : Effect.fail(failScan(`read docker save metadata from ${fullTarPath} failed`, cause))));
 	if (state.manifestBytes !== null) return yield* parseDockerSaveManifestTags(state.manifestBytes, tarPath);
 	if (state.indexBytes !== null) return yield* parseOciImageLayoutIndexTags(state.indexBytes, tarPath);

package/dist/orchestrators/snapshot/image-bundle-tags.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"image-bundle-tags.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/image-bundle-tags.ts"],"sourcesContent":["import { Effect, FileSystem, Schema, Stream } from 'effect';\n\nimport { isRestorableContainerImageName } from './descriptor.ts';\n\nexport class ImageBundleTagScanError extends Schema.TaggedErrorClass<ImageBundleTagScanError>()(\n\t'SnapshotImageBundleTagScanError',\n\t{\n\t\tdetail: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\nconst failScan = (detail: string, cause?: unknown): ImageBundleTagScanError =>\n\tnew ImageBundleTagScanError({\n\t\tdetail,\n\t\t...(cause === undefined ? {} : { cause }),\n\t});\n\nconst TAR_BLOCK_SIZE = 512;\nconst MAX_DOCKER_SAVE_MANIFEST_BYTES = 1024 * 1024;\n\nconst bytesToString = (bytes: Uint8Array): string => {\n\tconst nul = bytes.indexOf(0);\n\tconst end = nul === -1 ? bytes.length : nul;\n\treturn Buffer.from(bytes.subarray(0, end)).toString('utf8');\n};\n\nconst concatBytes = (a: Uint8Array, b: Uint8Array): Uint8Array => {\n\tif (a.length === 0) return b;\n\tif (b.length === 0) return a;\n\tconst out = new Uint8Array(a.length + b.length);\n\tout.set(a, 0);\n\tout.set(b, a.length);\n\treturn out;\n};\n\nconst consumeBytes = (buffer: Uint8Array, count: number): Uint8Array => buffer.subarray(count);\n\nconst isZeroBlock = (block: Uint8Array): boolean => block.every((byte) => byte === 0);\n\nconst parseTarSize = (header: Uint8Array): number | null => {\n\tconst raw = bytesToString(header.subarray(124, 136)).trim();\n\tif (raw === '') return 0;\n\tif (!/^[0-7]+$/.test(raw)) return null;\n\tconst parsed = Number.parseInt(raw, 8);\n\treturn Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;\n};\n\nconst tarPathFromHeader = (header: Uint8Array): string => {\n\tconst name = bytesToString(header.subarray(0, 100));\n\tconst prefix = bytesToString(header.subarray(345, 500));\n\treturn prefix === '' ? name : `${prefix}/${name}`;\n};\n\nconst normalizedTarEntryPath = (path: string): string => {\n\tlet normalized = path;\n\twhile (normalized.startsWith('./')) normalized = normalized.slice(2);\n\treturn normalized;\n};\n\ntype ImageBundleMetadataEntry = 'manifest.json' | 'index.json';\n\ninterface DockerSaveMetadataTarState {\n\tbuffer: Uint8Array;\n\tskipRemaining: number;\n\tmanifestBytes: Uint8Array | null;\n\tindexBytes: Uint8Array | null;\n\tcontent: {\n\t\treadonly entry: ImageBundleMetadataEntry;\n\t\treadonly size: number;\n\t\treadonly paddedSize: number;\n\t\treadonly chunks: Array<Uint8Array>;\n\t\treadonly contentBytesRead: number;\n\t\treadonly totalBytesRead: number;\n\t} | null;\n}\n\nconst processDockerSaveMetadataChunk = (\n\tstate: DockerSaveMetadataTarState,\n\tchunk: Uint8Array,\n): { readonly done: boolean; readonly error?: ImageBundleTagScanError } => {\n\tstate.buffer = concatBytes(state.buffer, chunk);\n\twhile (state.buffer.length > 0) {\n\t\tif (state.content !== null) {\n\t\t\tconst content = state.content;\n\t\t\tconst remaining = content.paddedSize - content.totalBytesRead;\n\t\t\tconst take = Math.min(remaining, state.buffer.length);\n\t\t\tconst contentTake = Math.max(0, Math.min(take, content.size - content.contentBytesRead));\n\t\t\tif (contentTake > 0) {\n\t\t\t\tcontent.chunks.push(state.buffer.subarray(0, contentTake));\n\t\t\t}\n\t\t\tstate.content = {\n\t\t\t\t...content,\n\t\t\t\tcontentBytesRead: content.contentBytesRead + contentTake,\n\t\t\t\ttotalBytesRead: content.totalBytesRead + take,\n\t\t\t};\n\t\t\tstate.buffer = consumeBytes(state.buffer, take);\n\t\t\tif (state.content.totalBytesRead === state.content.paddedSize) {\n\t\t\t\tconst completed = state.content;\n\t\t\t\tstate.content = null;\n\t\t\t\tconst entryBytes =\n\t\t\t\t\tcompleted.chunks.length === 1\n\t\t\t\t\t\t? completed.chunks[0]!\n\t\t\t\t\t\t: Buffer.concat(completed.chunks.map((entry) => Buffer.from(entry)));\n\t\t\t\tif (completed.entry === 'manifest.json') {\n\t\t\t\t\tstate.manifestBytes = entryBytes;\n\t\t\t\t\treturn { done: true };\n\t\t\t\t}\n\t\t\t\tstate.indexBytes = entryBytes;\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (state.skipRemaining > 0) {\n\t\t\tconst take = Math.min(state.skipRemaining, state.buffer.length);\n\t\t\tstate.skipRemaining -= take;\n\t\t\tstate.buffer = consumeBytes(state.buffer, take);\n\t\t\tcontinue;\n\t\t}\n\t\tif (state.buffer.length < TAR_BLOCK_SIZE) return { done: false };\n\t\tconst header = state.buffer.subarray(0, TAR_BLOCK_SIZE);\n\t\tstate.buffer = consumeBytes(state.buffer, TAR_BLOCK_SIZE);\n\t\tif (isZeroBlock(header)) continue;\n\t\tconst size = parseTarSize(header);\n\t\tif (size === null) {\n\t\t\treturn { done: false, error: failScan('docker save bundle has invalid tar size') };\n\t\t}\n\t\tconst paddedSize = Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;\n\t\tconst entryPath = normalizedTarEntryPath(tarPathFromHeader(header));\n\t\tif (entryPath === 'manifest.json' || entryPath === 'index.json') {\n\t\t\tif (size > MAX_DOCKER_SAVE_MANIFEST_BYTES) {\n\t\t\t\treturn {\n\t\t\t\t\tdone: false,\n\t\t\t\t\terror: failScan(`docker save ${entryPath} is too large`),\n\t\t\t\t};\n\t\t\t}\n\t\t\tif (size === 0) {\n\t\t\t\tif (entryPath === 'manifest.json') {\n\t\t\t\t\tstate.manifestBytes = new Uint8Array(0);\n\t\t\t\t\treturn { done: true };\n\t\t\t\t}\n\t\t\t\tstate.indexBytes = new Uint8Array(0);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tstate.content = {\n\t\t\t\tentry: entryPath,\n\t\t\t\tsize,\n\t\t\t\tpaddedSize,\n\t\t\t\tchunks: [],\n\t\t\t\tcontentBytesRead: 0,\n\t\t\t\ttotalBytesRead: 0,\n\t\t\t};\n\t\t\tcontinue;\n\t\t}\n\t\tstate.skipRemaining = paddedSize;\n\t}\n\treturn { done: false };\n};\n\nconst parseDockerSaveManifestTags = (\n\tbytes: Uint8Array,\n\ttarPath: string,\n): Effect.Effect<ReadonlySet<string>, ImageBundleTagScanError> =>\n\tEffect.gen(function* () {\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => JSON.parse(Buffer.from(bytes).toString('utf8')) as unknown,\n\t\t\tcatch: (cause) =>\n\t\t\t\tfailScan(`docker save manifest.json in ${tarPath} is not valid JSON`, cause),\n\t\t});\n\t\tif (!Array.isArray(raw)) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tfailScan(`docker save manifest.json in ${tarPath} is not an array`),\n\t\t\t);\n\t\t}\n\t\tconst tags = new Set<string>();\n\t\tfor (const [index, entry] of raw.entries()) {\n\t\t\tif (typeof entry !== 'object' || entry === null) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tfailScan(`docker save manifest entry ${index} in ${tarPath} is not an object`),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst repoTags = (entry as { readonly RepoTags?: unknown }).RepoTags;\n\t\t\tif (repoTags === undefined || repoTags === null) continue;\n\t\t\tif (!Array.isArray(repoTags)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tfailScan(`docker save manifest entry ${index} in ${tarPath} has non-array RepoTags`),\n\t\t\t\t);\n\t\t\t}\n\t\t\tfor (const tag of repoTags) {\n\t\t\t\tif (typeof tag !== 'string' || !isRestorableContainerImageName(tag)) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tfailScan(\n\t\t\t\t\t\t\t`docker save manifest entry ${index} in ${tarPath} has invalid RepoTag ${String(\n\t\t\t\t\t\t\t\ttag,\n\t\t\t\t\t\t\t)}`,\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tif (tags.has(tag)) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tfailScan(`docker save manifest in ${tarPath} repeats RepoTag ${tag}`),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\ttags.add(tag);\n\t\t\t}\n\t\t}\n\t\treturn tags;\n\t});\n\nconst normalizeOciImageName = (value: string): string | null => {\n\tconst dockerLibraryPrefix = 'docker.io/library/';\n\tif (value.startsWith(dockerLibraryPrefix)) {\n\t\tconst localName = value.slice(dockerLibraryPrefix.length);\n\t\tif (localName.startsWith('devstack-snapshot:') && isRestorableContainerImageName(localName)) {\n\t\t\treturn localName;\n\t\t}\n\t\treturn null;\n\t}\n\tif (value.startsWith('devstack-snapshot:') && isRestorableContainerImageName(value)) {\n\t\treturn value;\n\t}\n\treturn null;\n};\n\nconst parseOciImageLayoutIndexTags = (\n\tbytes: Uint8Array,\n\ttarPath: string,\n): Effect.Effect<ReadonlySet<string>, ImageBundleTagScanError> =>\n\tEffect.gen(function* () {\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => JSON.parse(Buffer.from(bytes).toString('utf8')) as unknown,\n\t\t\tcatch: (cause) => failScan(`docker save index.json in ${tarPath} is not valid JSON`, cause),\n\t\t});\n\t\tif (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {\n\t\t\treturn yield* Effect.fail(failScan(`docker save index.json in ${tarPath} is not an object`));\n\t\t}\n\t\tconst manifests = (raw as { readonly manifests?: unknown }).manifests;\n\t\tif (!Array.isArray(manifests)) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tfailScan(`docker save index.json in ${tarPath} has non-array manifests`),\n\t\t\t);\n\t\t}\n\t\tconst tags = new Set<string>();\n\t\tfor (const [index, entry] of manifests.entries()) {\n\t\t\tif (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tfailScan(`docker save index manifest ${index} in ${tarPath} is not an object`),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst annotations = (entry as { readonly annotations?: unknown }).annotations;\n\t\t\tif (annotations === undefined || annotations === null) continue;\n\t\t\tif (typeof annotations !== 'object' || Array.isArray(annotations)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tfailScan(`docker save index manifest ${index} in ${tarPath} has invalid annotations`),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst imageName = (annotations as { readonly ['io.containerd.image.name']?: unknown })[\n\t\t\t\t'io.containerd.image.name'\n\t\t\t];\n\t\t\tconst refName = (annotations as { readonly ['org.opencontainers.image.ref.name']?: unknown })[\n\t\t\t\t'org.opencontainers.image.ref.name'\n\t\t\t];\n\t\t\tfor (const value of [imageName, refName]) {\n\t\t\t\tif (typeof value !== 'string') continue;\n\t\t\t\tconst tag = normalizeOciImageName(value);\n\t\t\t\tif (tag === null) continue;\n\t\t\t\tif (tags.has(tag)) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tfailScan(`docker save index in ${tarPath} repeats RepoTag ${tag}`),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\ttags.add(tag);\n\t\t\t}\n\t\t}\n\t\treturn tags;\n\t});\n\nexport const readImageBundleTags = (\n\tfullTarPath: string,\n\ttarPath: string,\n): Effect.Effect<ReadonlySet<string>, ImageBundleTagScanError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst state: DockerSaveMetadataTarState = {\n\t\t\tbuffer: new Uint8Array(0),\n\t\t\tskipRemaining: 0,\n\t\t\tmanifestBytes: null,\n\t\t\tindexBytes: null,\n\t\t\tcontent: null,\n\t\t};\n\t\tyield* fs.stream(fullTarPath).pipe(\n\t\t\tStream.takeUntilEffect((chunk) => {\n\t\t\t\tconst result = processDockerSaveMetadataChunk(state, chunk);\n\t\t\t\tif (result.error !== undefined) return Effect.fail(result.error);\n\t\t\t\treturn Effect.succeed(result.done);\n\t\t\t}),\n\t\t\tStream.runDrain,\n\t\t\tEffect.catch((cause) =>\n\t\t\t\tcause instanceof ImageBundleTagScanError\n\t\t\t\t\t? Effect.fail(cause)\n\t\t\t\t\t: Effect.fail(failScan(`read docker save metadata from ${fullTarPath} failed`, cause)),\n\t\t\t),\n\t\t);\n\t\tif (state.manifestBytes !== null) {\n\t\t\treturn yield* parseDockerSaveManifestTags(state.manifestBytes, tarPath);\n\t\t}\n\t\tif (state.indexBytes !== null) {\n\t\t\treturn yield* parseOciImageLayoutIndexTags(state.indexBytes, tarPath);\n\t\t}\n\t\treturn yield* Effect.fail(\n\t\t\tfailScan(`docker save bundle ${tarPath} does not contain manifest.json or index.json`),\n\t\t);\n\t});\n\nexport const verifyImageBundleTags = (\n\ttarPath: string,\n\tactualTags: ReadonlySet<string>,\n\texpectedSnapshotTags: ReadonlyArray<string>,\n): Effect.Effect<void, ImageBundleTagScanError> => {\n\tconst expected = new Set<string>();\n\tconst repeatedExpected: string[] = [];\n\tfor (const tag of expectedSnapshotTags) {\n\t\tif (expected.has(tag)) {\n\t\t\trepeatedExpected.push(tag);\n\t\t} else {\n\t\t\texpected.add(tag);\n\t\t}\n\t}\n\tif (repeatedExpected.length > 0) {\n\t\treturn Effect.fail(\n\t\t\tfailScan(\n\t\t\t\t`docker save bundle ${tarPath} expected duplicate snapshot tags: ${repeatedExpected.join(\n\t\t\t\t\t', ',\n\t\t\t\t)}`,\n\t\t\t),\n\t\t);\n\t}\n\tconst missing = [...expected].filter((tag) => !actualTags.has(tag));\n\tconst unexpected = [...actualTags].filter((tag) => !expected.has(tag));\n\tif (missing.length === 0 && unexpected.length === 0) return Effect.void;\n\tconst parts: string[] = [];\n\tif (missing.length > 0) parts.push(`missing: ${missing.join(', ')}`);\n\tif (unexpected.length > 0) parts.push(`unexpected: ${unexpected.join(', ')}`);\n\treturn Effect.fail(\n\t\tfailScan(\n\t\t\t`docker save bundle ${tarPath} tags do not match snapshot metadata (${parts.join('; ')})`,\n\t\t),\n\t);\n};\n"],"mappings":"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"}
+{"version":3,"file":"image-bundle-tags.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/image-bundle-tags.ts"],"sourcesContent":["import { Effect, FileSystem, Schema, Stream } from 'effect';\n\nimport {\n\tcaptureEntry,\n\tisSafeArchivePath,\n\tmakeTarReaderState,\n\tprocessTarChunk,\n\tskipEntry,\n\tstopScan,\n\ttype TarEntry,\n\ttype TarEntryDirective,\n} from '../../substrate/runtime/tar/reader.ts';\nimport { isRestorableContainerImageName } from './descriptor.ts';\n\nexport class ImageBundleTagScanError extends Schema.TaggedErrorClass<ImageBundleTagScanError>()(\n\t'SnapshotImageBundleTagScanError',\n\t{\n\t\tdetail: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\nconst failScan = (detail: string, cause?: unknown): ImageBundleTagScanError =>\n\tnew ImageBundleTagScanError({\n\t\tdetail,\n\t\t...(cause === undefined ? {} : { cause }),\n\t});\n\nconst MAX_DOCKER_SAVE_MANIFEST_BYTES = 1024 * 1024;\n\nconst normalizedTarEntryPath = (path: string): string => {\n\tlet normalized = path;\n\twhile (normalized.startsWith('./')) normalized = normalized.slice(2);\n\treturn normalized;\n};\n\n// Metadata-only scan state. The shared tar reader owns the block\n// discipline + pax/gnu handling; this state just collects the two\n// metadata entries we care about and a `done` flag so the stream drain\n// can short-circuit once manifest.json lands.\ninterface DockerSaveMetadataState {\n\tmanifestBytes: Uint8Array | null;\n\tindexBytes: Uint8Array | null;\n\tdone: boolean;\n}\n\n// Per-entry directive for the Docker-save / OCI-layout metadata scan.\n// Docker `save` bundles are a TRUSTED-extraction path: this scanner only\n// reads manifest.json / index.json metadata and never writes any file to\n// disk, so it does NOT untar bodies. `isSafeArchivePath` is applied for\n// defense-in-depth (a malicious linkpath / escaping entry path is\n// rejected) without tightening acceptance of valid OCI bundles — only\n// the manifest/index entries are captured; all other members (layer\n// blobs, configs) are skipped as before.\nconst onMetadataEntry = (\n\tstate: DockerSaveMetadataState,\n\tentry: TarEntry,\n): TarEntryDirective | ImageBundleTagScanError => {\n\tif (!isSafeArchivePath(entry.path)) {\n\t\treturn failScan(`docker save bundle has unsafe tar entry path: ${entry.path}`);\n\t}\n\tif ((entry.typeflag === '1' || entry.typeflag === '2') && !isSafeArchivePath(entry.linkPath)) {\n\t\treturn failScan(`docker save bundle has unsafe tar link target: ${entry.linkPath}`);\n\t}\n\tconst entryPath = normalizedTarEntryPath(entry.path);\n\tif (entryPath === 'manifest.json' || entryPath === 'index.json') {\n\t\tif (entry.size > MAX_DOCKER_SAVE_MANIFEST_BYTES) {\n\t\t\treturn failScan(`docker save ${entryPath} is too large`);\n\t\t}\n\t\tif (entry.size === 0) {\n\t\t\tif (entryPath === 'manifest.json') {\n\t\t\t\tstate.manifestBytes = new Uint8Array(0);\n\t\t\t\tstate.done = true;\n\t\t\t\treturn stopScan();\n\t\t\t}\n\t\t\tstate.indexBytes = new Uint8Array(0);\n\t\t\treturn skipEntry();\n\t\t}\n\t\treturn captureEntry();\n\t}\n\treturn skipEntry();\n};\n\nconst onMetadataContent = (\n\tstate: DockerSaveMetadataState,\n\tentry: TarEntry,\n\tbody: Uint8Array,\n): null => {\n\tconst entryPath = normalizedTarEntryPath(entry.path);\n\tif (entryPath === 'manifest.json') {\n\t\tstate.manifestBytes = body;\n\t\tstate.done = true;\n\t} else {\n\t\tstate.indexBytes = body;\n\t}\n\treturn null;\n};\n\nconst parseDockerSaveManifestTags = (\n\tbytes: Uint8Array,\n\ttarPath: string,\n): Effect.Effect<ReadonlySet<string>, ImageBundleTagScanError> =>\n\tEffect.gen(function* () {\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => JSON.parse(Buffer.from(bytes).toString('utf8')) as unknown,\n\t\t\tcatch: (cause) =>\n\t\t\t\tfailScan(`docker save manifest.json in ${tarPath} is not valid JSON`, cause),\n\t\t});\n\t\tif (!Array.isArray(raw)) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tfailScan(`docker save manifest.json in ${tarPath} is not an array`),\n\t\t\t);\n\t\t}\n\t\tconst tags = new Set<string>();\n\t\tfor (const [index, entry] of raw.entries()) {\n\t\t\tif (typeof entry !== 'object' || entry === null) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tfailScan(`docker save manifest entry ${index} in ${tarPath} is not an object`),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst repoTags = (entry as { readonly RepoTags?: unknown }).RepoTags;\n\t\t\tif (repoTags === undefined || repoTags === null) continue;\n\t\t\tif (!Array.isArray(repoTags)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tfailScan(`docker save manifest entry ${index} in ${tarPath} has non-array RepoTags`),\n\t\t\t\t);\n\t\t\t}\n\t\t\tfor (const tag of repoTags) {\n\t\t\t\tif (typeof tag !== 'string' || !isRestorableContainerImageName(tag)) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tfailScan(\n\t\t\t\t\t\t\t`docker save manifest entry ${index} in ${tarPath} has invalid RepoTag ${String(\n\t\t\t\t\t\t\t\ttag,\n\t\t\t\t\t\t\t)}`,\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tif (tags.has(tag)) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tfailScan(`docker save manifest in ${tarPath} repeats RepoTag ${tag}`),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\ttags.add(tag);\n\t\t\t}\n\t\t}\n\t\treturn tags;\n\t});\n\nconst normalizeOciImageName = (value: string): string | null => {\n\tconst dockerLibraryPrefix = 'docker.io/library/';\n\tif (value.startsWith(dockerLibraryPrefix)) {\n\t\tconst localName = value.slice(dockerLibraryPrefix.length);\n\t\tif (localName.startsWith('devstack-snapshot:') && isRestorableContainerImageName(localName)) {\n\t\t\treturn localName;\n\t\t}\n\t\treturn null;\n\t}\n\tif (value.startsWith('devstack-snapshot:') && isRestorableContainerImageName(value)) {\n\t\treturn value;\n\t}\n\treturn null;\n};\n\nconst parseOciImageLayoutIndexTags = (\n\tbytes: Uint8Array,\n\ttarPath: string,\n): Effect.Effect<ReadonlySet<string>, ImageBundleTagScanError> =>\n\tEffect.gen(function* () {\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => JSON.parse(Buffer.from(bytes).toString('utf8')) as unknown,\n\t\t\tcatch: (cause) => failScan(`docker save index.json in ${tarPath} is not valid JSON`, cause),\n\t\t});\n\t\tif (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {\n\t\t\treturn yield* Effect.fail(failScan(`docker save index.json in ${tarPath} is not an object`));\n\t\t}\n\t\tconst manifests = (raw as { readonly manifests?: unknown }).manifests;\n\t\tif (!Array.isArray(manifests)) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tfailScan(`docker save index.json in ${tarPath} has non-array manifests`),\n\t\t\t);\n\t\t}\n\t\tconst tags = new Set<string>();\n\t\tfor (const [index, entry] of manifests.entries()) {\n\t\t\tif (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tfailScan(`docker save index manifest ${index} in ${tarPath} is not an object`),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst annotations = (entry as { readonly annotations?: unknown }).annotations;\n\t\t\tif (annotations === undefined || annotations === null) continue;\n\t\t\tif (typeof annotations !== 'object' || Array.isArray(annotations)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tfailScan(`docker save index manifest ${index} in ${tarPath} has invalid annotations`),\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst imageName = (annotations as { readonly ['io.containerd.image.name']?: unknown })[\n\t\t\t\t'io.containerd.image.name'\n\t\t\t];\n\t\t\tconst refName = (annotations as { readonly ['org.opencontainers.image.ref.name']?: unknown })[\n\t\t\t\t'org.opencontainers.image.ref.name'\n\t\t\t];\n\t\t\tfor (const value of [imageName, refName]) {\n\t\t\t\tif (typeof value !== 'string') continue;\n\t\t\t\tconst tag = normalizeOciImageName(value);\n\t\t\t\tif (tag === null) continue;\n\t\t\t\tif (tags.has(tag)) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tfailScan(`docker save index in ${tarPath} repeats RepoTag ${tag}`),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\ttags.add(tag);\n\t\t\t}\n\t\t}\n\t\treturn tags;\n\t});\n\nexport const readImageBundleTags = (\n\tfullTarPath: string,\n\ttarPath: string,\n): Effect.Effect<ReadonlySet<string>, ImageBundleTagScanError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst state: DockerSaveMetadataState = {\n\t\t\tmanifestBytes: null,\n\t\t\tindexBytes: null,\n\t\t\tdone: false,\n\t\t};\n\t\tconst reader = makeTarReaderState();\n\t\tyield* fs.stream(fullTarPath).pipe(\n\t\t\tStream.takeUntilEffect((chunk) => {\n\t\t\t\tconst error = processTarChunk(reader, chunk, {\n\t\t\t\t\tonEntry: (entry) => onMetadataEntry(state, entry),\n\t\t\t\t\tonContent: (entry, body) => onMetadataContent(state, entry, body),\n\t\t\t\t\tonExtendedError: (detail) => failScan(`docker save bundle ${detail}`),\n\t\t\t\t});\n\t\t\t\tif (error !== null) return Effect.fail(error);\n\t\t\t\treturn Effect.succeed(state.done);\n\t\t\t}),\n\t\t\tStream.runDrain,\n\t\t\tEffect.catch((cause) =>\n\t\t\t\tcause instanceof ImageBundleTagScanError\n\t\t\t\t\t? Effect.fail(cause)\n\t\t\t\t\t: Effect.fail(failScan(`read docker save metadata from ${fullTarPath} failed`, cause)),\n\t\t\t),\n\t\t);\n\t\tif (state.manifestBytes !== null) {\n\t\t\treturn yield* parseDockerSaveManifestTags(state.manifestBytes, tarPath);\n\t\t}\n\t\tif (state.indexBytes !== null) {\n\t\t\treturn yield* parseOciImageLayoutIndexTags(state.indexBytes, tarPath);\n\t\t}\n\t\treturn yield* Effect.fail(\n\t\t\tfailScan(`docker save bundle ${tarPath} does not contain manifest.json or index.json`),\n\t\t);\n\t});\n\nexport const verifyImageBundleTags = (\n\ttarPath: string,\n\tactualTags: ReadonlySet<string>,\n\texpectedSnapshotTags: ReadonlyArray<string>,\n): Effect.Effect<void, ImageBundleTagScanError> => {\n\tconst expected = new Set<string>();\n\tconst repeatedExpected: string[] = [];\n\tfor (const tag of expectedSnapshotTags) {\n\t\tif (expected.has(tag)) {\n\t\t\trepeatedExpected.push(tag);\n\t\t} else {\n\t\t\texpected.add(tag);\n\t\t}\n\t}\n\tif (repeatedExpected.length > 0) {\n\t\treturn Effect.fail(\n\t\t\tfailScan(\n\t\t\t\t`docker save bundle ${tarPath} expected duplicate snapshot tags: ${repeatedExpected.join(\n\t\t\t\t\t', ',\n\t\t\t\t)}`,\n\t\t\t),\n\t\t);\n\t}\n\tconst missing = [...expected].filter((tag) => !actualTags.has(tag));\n\tconst unexpected = [...actualTags].filter((tag) => !expected.has(tag));\n\tif (missing.length === 0 && unexpected.length === 0) return Effect.void;\n\tconst parts: string[] = [];\n\tif (missing.length > 0) parts.push(`missing: ${missing.join(', ')}`);\n\tif (unexpected.length > 0) parts.push(`unexpected: ${unexpected.join(', ')}`);\n\treturn Effect.fail(\n\t\tfailScan(\n\t\t\t`docker save bundle ${tarPath} tags do not match snapshot metadata (${parts.join('; ')})`,\n\t\t),\n\t);\n};\n"],"mappings":"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"}

package/dist/orchestrators/snapshot/index.mjs

@@ -2,12 +2,9 @@ import "./descriptor.mjs";
 import "./wipe.mjs";
 import "./integrity.mjs";
 import "./identity-guard.mjs";
-import "./state-document.mjs";
 import "./capture.mjs";
 import "./prune.mjs";
-import "./pending-marker.mjs";
-import "./recover-pending.mjs";
+import "./interrupted-restore.mjs";
 import "./restore.mjs";
 import "./service.mjs";
-import "./capture-command.mjs";
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"integrity.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/integrity.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\n\nimport { Effect, FileSystem, Schema, Stream } from 'effect';\n\nimport { decodeUnknown, parseJsonText } from '../../substrate/runtime/runtime-decode.ts';\nimport {\n\tIntegrityFileSchema,\n\tSNAPSHOT_INTEGRITY_VERSION,\n\tSnapshotLayout,\n\tisSafeSnapshotRelativePath,\n\ttype IntegrityFile,\n} from './descriptor.ts';\n\nconst SHA256_HEX = /^[a-f0-9]{64}$/;\n\n/** Tagged failure raised by snapshot integrity helpers. `kind`\n *  discriminates the failure class so downstream phase classifiers can\n *  branch by tag, not by message substring. */\nexport class SnapshotIntegrityError extends Schema.TaggedErrorClass<SnapshotIntegrityError>()(\n\t'SnapshotIntegrityError',\n\t{\n\t\t/**\n\t\t * - `'missing'` — `integrity.json` file absent.\n\t\t * - `'corrupt'` — present but unparseable / schema-decode failure.\n\t\t * - `'mismatch'` — present, parses, but a file's hash does not\n\t\t *   match its recorded value (or the file list disagrees).\n\t\t * - `'walk-failed'` — directory walk failure (filesystem error\n\t\t *   during enumeration, hashing, or write of the integrity doc).\n\t\t */\n\t\tkind: Schema.Literals(['missing', 'corrupt', 'mismatch', 'walk-failed']),\n\t\tdetail: Schema.String,\n\t\tpath: Schema.optional(Schema.String),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\nconst failWalk = (\n\tdetail: string,\n\tpath?: string,\n\tcause?: unknown,\n): Effect.Effect<never, SnapshotIntegrityError> =>\n\tEffect.fail(new SnapshotIntegrityError({ kind: 'walk-failed', detail, path, cause }));\n\nconst failCorrupt = (\n\tdetail: string,\n\tpath?: string,\n\tcause?: unknown,\n): Effect.Effect<never, SnapshotIntegrityError> =>\n\tEffect.fail(new SnapshotIntegrityError({ kind: 'corrupt', detail, path, cause }));\n\nconst failMismatch = (\n\tdetail: string,\n\tpath?: string,\n): Effect.Effect<never, SnapshotIntegrityError> =>\n\tEffect.fail(new SnapshotIntegrityError({ kind: 'mismatch', detail, path }));\n\nconst hashFile = (\n\tpath: string,\n): Effect.Effect<string, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst hash = createHash('sha256');\n\t\tyield* Stream.runForEach(fs.stream(path), (chunk) =>\n\t\t\tEffect.sync(() => {\n\t\t\t\thash.update(chunk);\n\t\t\t}),\n\t\t).pipe(Effect.catch((cause) => failWalk(`hash ${path} failed`, path, cause)));\n\t\treturn hash.digest('hex');\n\t});\n\nconst collectArtifactFiles = (\n\troot: string,\n): Effect.Effect<ReadonlyArray<string>, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst files: string[] = [];\n\t\tconst walk = (dir: string, prefix: string): Effect.Effect<void, SnapshotIntegrityError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst names = yield* fs\n\t\t\t\t\t.readDirectory(dir)\n\t\t\t\t\t.pipe(Effect.catch((cause) => failWalk(`readDirectory(${dir}) failed`, dir, cause)));\n\t\t\t\tfor (const name of names) {\n\t\t\t\t\tconst relPath = prefix === '' ? name : `${prefix}/${name}`;\n\t\t\t\t\tif (!isSafeSnapshotRelativePath(relPath)) {\n\t\t\t\t\t\treturn yield* failWalk(`unsafe artifact relative path: ${relPath}`, relPath);\n\t\t\t\t\t}\n\t\t\t\t\tconst absPath = `${dir}/${name}`;\n\t\t\t\t\tconst stat = yield* fs\n\t\t\t\t\t\t.stat(absPath)\n\t\t\t\t\t\t.pipe(Effect.catch((cause) => failWalk(`stat(${absPath}) failed`, absPath, cause)));\n\t\t\t\t\tif (stat.type === 'Directory') {\n\t\t\t\t\t\tyield* walk(absPath, relPath);\n\t\t\t\t\t} else if (stat.type === 'File') {\n\t\t\t\t\t\tif (relPath !== SnapshotLayout.integrityFile) {\n\t\t\t\t\t\t\tfiles.push(relPath);\n\t\t\t\t\t\t}\n\t\t\t\t\t} else {\n\t\t\t\t\t\treturn yield* failWalk(\n\t\t\t\t\t\t\t`snapshot artifact path is not a regular file: ${relPath}`,\n\t\t\t\t\t\t\tabsPath,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\tyield* walk(root, '');\n\t\treturn files.sort((a, b) => a.localeCompare(b));\n\t});\n\nexport const computeArtifactIntegrity = (\n\troot: string,\n): Effect.Effect<IntegrityFile, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst hashes: Record<string, string> = {};\n\t\tfor (const relPath of yield* collectArtifactFiles(root)) {\n\t\t\thashes[relPath] = yield* hashFile(`${root}/${relPath}`);\n\t\t}\n\t\treturn { version: SNAPSHOT_INTEGRITY_VERSION, hashes };\n\t});\n\nexport const writeArtifactIntegrity = (\n\troot: string,\n): Effect.Effect<IntegrityFile, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst integrity = yield* computeArtifactIntegrity(root);\n\t\tconst path = `${root}/${SnapshotLayout.integrityFile}`;\n\t\tyield* fs\n\t\t\t.writeFileString(path, JSON.stringify(integrity, null, 2))\n\t\t\t.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tfailWalk(`write ${SnapshotLayout.integrityFile} failed`, path, cause),\n\t\t\t\t),\n\t\t\t);\n\t\treturn integrity;\n\t});\n\nconst readIntegrity = (\n\troot: string,\n): Effect.Effect<IntegrityFile, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst path = `${root}/${SnapshotLayout.integrityFile}`;\n\t\tconst exists = yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false)));\n\t\tif (!exists) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew SnapshotIntegrityError({\n\t\t\t\t\tkind: 'missing',\n\t\t\t\t\tdetail: `snapshot integrity file absent at ${path}`,\n\t\t\t\t\tpath,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst text = yield* fs\n\t\t\t.readFileString(path)\n\t\t\t.pipe(Effect.catch((cause) => failWalk(`read ${path} failed`, path, cause)));\n\t\tconst raw = yield* parseJsonText(text, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) =>\n\t\t\t\tnew SnapshotIntegrityError({\n\t\t\t\t\tkind: 'corrupt',\n\t\t\t\t\tdetail: `${path} is not valid JSON`,\n\t\t\t\t\tpath,\n\t\t\t\t\tcause: issue.cause,\n\t\t\t\t}),\n\t\t});\n\t\tconst decoded = yield* decodeUnknown(IntegrityFileSchema, raw, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) =>\n\t\t\t\tnew SnapshotIntegrityError({\n\t\t\t\t\tkind: 'corrupt',\n\t\t\t\t\tdetail: `${path} failed schema decode`,\n\t\t\t\t\tpath,\n\t\t\t\t\tcause: issue.cause,\n\t\t\t\t}),\n\t\t});\n\t\tfor (const [relPath, digest] of Object.entries(decoded.hashes)) {\n\t\t\tif (!isSafeSnapshotRelativePath(relPath) || relPath === SnapshotLayout.integrityFile) {\n\t\t\t\treturn yield* failCorrupt(`unsafe integrity path: ${relPath}`, path);\n\t\t\t}\n\t\t\tif (!SHA256_HEX.test(digest)) {\n\t\t\t\treturn yield* failCorrupt(`invalid sha256 digest for ${relPath}`, path);\n\t\t\t}\n\t\t}\n\t\treturn decoded;\n\t});\n\nexport const verifyArtifactIntegrity = (\n\troot: string,\n): Effect.Effect<void, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst expected = yield* readIntegrity(root);\n\t\tconst actual = yield* computeArtifactIntegrity(root);\n\t\tconst expectedPaths = Object.keys(expected.hashes).sort((a, b) => a.localeCompare(b));\n\t\tconst actualPaths = Object.keys(actual.hashes).sort((a, b) => a.localeCompare(b));\n\t\tif (expectedPaths.join('\\n') !== actualPaths.join('\\n')) {\n\t\t\treturn yield* failMismatch('snapshot integrity file list does not match artifact contents');\n\t\t}\n\t\tfor (const relPath of expectedPaths) {\n\t\t\tif (expected.hashes[relPath] !== actual.hashes[relPath]) {\n\t\t\t\treturn yield* failMismatch(`snapshot integrity mismatch for ${relPath}`, relPath);\n\t\t\t}\n\t\t}\n\t});\n"],"mappings":"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"}
+{"version":3,"file":"integrity.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/integrity.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\n\nimport { Effect, FileSystem, Schema, Stream } from 'effect';\n\nimport { decodeUnknown, parseJsonText } from '../../substrate/runtime/runtime-decode.ts';\nimport {\n\tIntegrityFileSchema,\n\tSNAPSHOT_INTEGRITY_VERSION,\n\tSnapshotLayout,\n\tisSafeSnapshotRelativePath,\n\ttype IntegrityFile,\n} from './descriptor.ts';\n\nconst SHA256_HEX = /^[a-f0-9]{64}$/;\n\n/** Tagged failure raised by snapshot integrity helpers. `kind`\n *  discriminates the failure class so downstream phase classifiers can\n *  branch by tag, not by message substring. */\nexport class SnapshotIntegrityError extends Schema.TaggedErrorClass<SnapshotIntegrityError>()(\n\t'SnapshotIntegrityError',\n\t{\n\t\t/**\n\t\t * - `'missing'` — `integrity.json` file absent.\n\t\t * - `'corrupt'` — present but unparseable / schema-decode failure.\n\t\t * - `'mismatch'` — present, parses, but a file's hash does not\n\t\t *   match its recorded value (or the file list disagrees).\n\t\t * - `'walk-failed'` — directory walk failure (filesystem error\n\t\t *   during enumeration, hashing, or write of the integrity doc).\n\t\t */\n\t\tkind: Schema.Literals(['missing', 'corrupt', 'mismatch', 'walk-failed']),\n\t\tdetail: Schema.String,\n\t\tpath: Schema.optional(Schema.String),\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\nconst failWalk = (\n\tdetail: string,\n\tpath?: string,\n\tcause?: unknown,\n): Effect.Effect<never, SnapshotIntegrityError> =>\n\tEffect.fail(new SnapshotIntegrityError({ kind: 'walk-failed', detail, path, cause }));\n\nconst failCorrupt = (\n\tdetail: string,\n\tpath?: string,\n\tcause?: unknown,\n): Effect.Effect<never, SnapshotIntegrityError> =>\n\tEffect.fail(new SnapshotIntegrityError({ kind: 'corrupt', detail, path, cause }));\n\nconst failMismatch = (\n\tdetail: string,\n\tpath?: string,\n): Effect.Effect<never, SnapshotIntegrityError> =>\n\tEffect.fail(new SnapshotIntegrityError({ kind: 'mismatch', detail, path }));\n\nconst hashFile = (\n\tpath: string,\n): Effect.Effect<string, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst hash = createHash('sha256');\n\t\tyield* Stream.runForEach(fs.stream(path), (chunk) =>\n\t\t\tEffect.sync(() => {\n\t\t\t\thash.update(chunk);\n\t\t\t}),\n\t\t).pipe(Effect.catch((cause) => failWalk(`hash ${path} failed`, path, cause)));\n\t\treturn hash.digest('hex');\n\t});\n\nconst collectArtifactFiles = (\n\troot: string,\n): Effect.Effect<ReadonlyArray<string>, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst files: string[] = [];\n\t\tconst walk = (dir: string, prefix: string): Effect.Effect<void, SnapshotIntegrityError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst names = yield* fs\n\t\t\t\t\t.readDirectory(dir)\n\t\t\t\t\t.pipe(Effect.catch((cause) => failWalk(`readDirectory(${dir}) failed`, dir, cause)));\n\t\t\t\tfor (const name of names) {\n\t\t\t\t\tconst relPath = prefix === '' ? name : `${prefix}/${name}`;\n\t\t\t\t\tif (!isSafeSnapshotRelativePath(relPath)) {\n\t\t\t\t\t\treturn yield* failWalk(`unsafe artifact relative path: ${relPath}`, relPath);\n\t\t\t\t\t}\n\t\t\t\t\tconst absPath = `${dir}/${name}`;\n\t\t\t\t\tconst stat = yield* fs\n\t\t\t\t\t\t.stat(absPath)\n\t\t\t\t\t\t.pipe(Effect.catch((cause) => failWalk(`stat(${absPath}) failed`, absPath, cause)));\n\t\t\t\t\tif (stat.type === 'Directory') {\n\t\t\t\t\t\tyield* walk(absPath, relPath);\n\t\t\t\t\t} else if (stat.type === 'File') {\n\t\t\t\t\t\tif (relPath !== SnapshotLayout.integrityFile) {\n\t\t\t\t\t\t\tfiles.push(relPath);\n\t\t\t\t\t\t}\n\t\t\t\t\t} else {\n\t\t\t\t\t\treturn yield* failWalk(\n\t\t\t\t\t\t\t`snapshot artifact path is not a regular file: ${relPath}`,\n\t\t\t\t\t\t\tabsPath,\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\tyield* walk(root, '');\n\t\treturn files.sort((a, b) => a.localeCompare(b));\n\t});\n\nexport const computeArtifactIntegrity = (\n\troot: string,\n): Effect.Effect<IntegrityFile, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst hashes: Record<string, string> = {};\n\t\tfor (const relPath of yield* collectArtifactFiles(root)) {\n\t\t\thashes[relPath] = yield* hashFile(`${root}/${relPath}`);\n\t\t}\n\t\treturn { version: SNAPSHOT_INTEGRITY_VERSION, hashes };\n\t});\n\nexport const writeArtifactIntegrity = (\n\troot: string,\n): Effect.Effect<IntegrityFile, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst integrity = yield* computeArtifactIntegrity(root);\n\t\tconst path = `${root}/${SnapshotLayout.integrityFile}`;\n\t\tyield* fs\n\t\t\t.writeFileString(path, JSON.stringify(integrity, null, 2))\n\t\t\t.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tfailWalk(`write ${SnapshotLayout.integrityFile} failed`, path, cause),\n\t\t\t\t),\n\t\t\t);\n\t\treturn integrity;\n\t});\n\nconst readIntegrity = (\n\troot: string,\n): Effect.Effect<IntegrityFile, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst path = `${root}/${SnapshotLayout.integrityFile}`;\n\t\tconst exists = yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false)));\n\t\tif (!exists) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew SnapshotIntegrityError({\n\t\t\t\t\tkind: 'missing',\n\t\t\t\t\tdetail: `snapshot integrity file absent at ${path}`,\n\t\t\t\t\tpath,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst text = yield* fs\n\t\t\t.readFileString(path)\n\t\t\t.pipe(Effect.catch((cause) => failWalk(`read ${path} failed`, path, cause)));\n\t\tconst raw = yield* parseJsonText(text, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) =>\n\t\t\t\tnew SnapshotIntegrityError({\n\t\t\t\t\tkind: 'corrupt',\n\t\t\t\t\tdetail: `${path} is not valid JSON`,\n\t\t\t\t\tpath,\n\t\t\t\t\tcause: issue.cause,\n\t\t\t\t}),\n\t\t});\n\t\tconst decoded = yield* decodeUnknown(IntegrityFileSchema, raw, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) =>\n\t\t\t\tnew SnapshotIntegrityError({\n\t\t\t\t\tkind: 'corrupt',\n\t\t\t\t\tdetail: `${path} failed schema decode`,\n\t\t\t\t\tpath,\n\t\t\t\t\tcause: issue.cause,\n\t\t\t\t}),\n\t\t});\n\t\tfor (const [relPath, digest] of Object.entries(decoded.hashes)) {\n\t\t\tif (!isSafeSnapshotRelativePath(relPath) || relPath === SnapshotLayout.integrityFile) {\n\t\t\t\treturn yield* failCorrupt(`unsafe integrity path: ${relPath}`, path);\n\t\t\t}\n\t\t\tif (!SHA256_HEX.test(digest)) {\n\t\t\t\treturn yield* failCorrupt(`invalid sha256 digest for ${relPath}`, path);\n\t\t\t}\n\t\t}\n\t\treturn decoded;\n\t});\n\nexport const verifyArtifactIntegrity = (\n\troot: string,\n): Effect.Effect<void, SnapshotIntegrityError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst expected = yield* readIntegrity(root);\n\t\tconst actual = yield* computeArtifactIntegrity(root);\n\t\tconst expectedPaths = Object.keys(expected.hashes).sort((a, b) => a.localeCompare(b));\n\t\tconst actualPaths = Object.keys(actual.hashes).sort((a, b) => a.localeCompare(b));\n\t\tif (expectedPaths.join('\\n') !== actualPaths.join('\\n')) {\n\t\t\treturn yield* failMismatch('snapshot integrity file list does not match artifact contents');\n\t\t}\n\t\tfor (const relPath of expectedPaths) {\n\t\t\tif (expected.hashes[relPath] !== actual.hashes[relPath]) {\n\t\t\t\treturn yield* failMismatch(`snapshot integrity mismatch for ${relPath}`, relPath);\n\t\t\t}\n\t\t}\n\t});\n"],"mappings":"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"}

package/dist/orchestrators/snapshot/interrupted-restore.mjs

@@ -0,0 +1,116 @@
+import { decodeUnknown, parseJsonText } from "../../substrate/runtime/runtime-decode.mjs";
+import { versionedDocSchema } from "../../substrate/versioned-doc-schema.mjs";
+import { parseSnapshotId } from "./descriptor.mjs";
+import { Effect, FileSystem, Schema } from "effect";
+//#region src/orchestrators/snapshot/interrupted-restore.ts
+/** Fixed hidden filename for the interrupted-restore sentinel. Written at
+*  the ROOT of the staged tree (and therefore at the root of the live
+*  runtime stack root after the swap lands). Hidden + dotted so it never
+*  collides with a plugin's runtime subtree and is visually distinct from
+*  the operator's content. */
+const RESTORE_SENTINEL_FILE_NAME = ".devstack-restore-in-progress.json";
+/** The interrupted-restore sentinel record. Carries exactly what
+*  re-running the restore needs: the snapshot id (the orchestrator
+*  derives the artifact dir from it) plus the resolved artifact dir as a
+*  cross-check / diagnostic (the snapshots subtree rides the same atomic
+*  swap, so the artifact at this path is preserved across the restore). */
+const RestoreSentinelSchema = versionedDocSchema(1, {
+	snapshotId: Schema.String,
+	artifactDir: Schema.String
+});
+const sentinelPath = (root) => `${root}/${RESTORE_SENTINEL_FILE_NAME}`;
+/** Write the sentinel JSON into the STAGED tree root at the fixed hidden
+*  path so it rides the atomic stage-and-swap into the live runtime root.
+*  Called from `runRestore` immediately before `executeFsPlan` publishes
+*  the swap. Encode validates the payload against the schema (the
+*  `version` discriminator is supplied here). */
+const writeRestoreSentinel = (stagedRoot, payload) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const doc = {
+		version: 1,
+		snapshotId: payload.snapshotId,
+		artifactDir: payload.artifactDir
+	};
+	yield* fs.writeFileString(sentinelPath(stagedRoot), JSON.stringify(doc)).pipe(Effect.catch((cause) => Effect.logWarning(`restore sentinel write failed at ${sentinelPath(stagedRoot)} — a hard kill mid-promotion would be unrecoverable for snapshot ${payload.snapshotId}: ${String(cause)}`)));
+});
+/** Read the sentinel from the LIVE runtime root. Returns `null` when the
+*  sentinel is absent (the common case — no interrupted restore) or
+*  present-but-unparseable (logged, then treated as absent so a corrupt
+*  breadcrumb cannot wedge boot; the operator can recover manually). */
+const readRestoreSentinel = (liveRoot) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = sentinelPath(liveRoot);
+	if (!(yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false))))) return null;
+	const readExit = yield* Effect.exit(fs.readFileString(path));
+	if (readExit._tag === "Failure") {
+		yield* Effect.logWarning(`restore sentinel read failed at ${path}; treating as absent (no auto-recovery)`);
+		return null;
+	}
+	const decodeExit = yield* Effect.exit(parseJsonText(readExit.value, {
+		source: path,
+		mkError: (issue) => issue
+	}).pipe(Effect.flatMap((raw) => decodeUnknown(RestoreSentinelSchema, raw, {
+		source: path,
+		mkError: (issue) => issue
+	}))));
+	if (decodeExit._tag === "Failure") {
+		yield* Effect.logWarning(`restore sentinel at ${path} is unparseable; treating as absent (no auto-recovery)`);
+		return null;
+	}
+	return decodeExit.value;
+});
+/** Remove the sentinel from the LIVE runtime root. Idempotent
+*  (`force: true`) — a missing sentinel is a no-op. Called on the restore
+*  success path the instant the promotion+removal handoff completes, and
+*  again after a successful auto-recovery re-run. */
+const clearRestoreSentinel = (liveRoot) => Effect.gen(function* () {
+	yield* (yield* FileSystem.FileSystem).remove(sentinelPath(liveRoot), { force: true }).pipe(Effect.ignore);
+});
+/**
+* Boot-time auto-recovery for a restore interrupted by a hard kill /
+* power-loss between the atomic swap and the end of the image-promotion
+* handoff. Reads the sentinel from the live runtime root; when present,
+* logs a clear "resuming interrupted restore <id>" and re-invokes the
+* restore for that snapshot. No-op when the sentinel is absent.
+*
+* Wired at boot BEFORE the first plugin acquire (the `beforeInitialAcquire`
+* hook), so a half-promoted image set is reconciled before any L2 lookup
+* observes the runtime root.
+*
+* ## Loop-safety
+*
+*   - A CLEAN restore cleared the sentinel on its success path, so a clean
+*     boot reads `null` and returns immediately — boot never loops.
+*   - A SUCCESSFUL recovery clears the sentinel after the re-run returns,
+*     so the next boot is clean.
+*   - A STILL-FAILING artifact (re-run fails) DELIBERATELY leaves the
+*     sentinel in place so the next boot retries. The failure is logged
+*     and SWALLOWED — boot continues rather than wedging — but the
+*     sentinel persists as the durable retry breadcrumb. This is the
+*     intended trade: a genuinely corrupt artifact will re-fail every boot
+*     (surfaced by the warning + the restore's own typed phase error in
+*     the logs) rather than silently dropping the recovery intent. An
+*     operator resolves it by repairing/removing the artifact or clearing
+*     the sentinel by hand.
+*/
+const recoverInterruptedRestore = (deps) => Effect.gen(function* () {
+	const sentinel = yield* readRestoreSentinel(deps.liveRoot);
+	if (sentinel === null) return;
+	const snapshotId = parseSnapshotId(sentinel.snapshotId);
+	if (snapshotId === null) {
+		yield* Effect.logWarning(`interrupted-restore sentinel carries an unsafe snapshot id (${sentinel.snapshotId}); clearing it — no auto-recovery possible`);
+		yield* clearRestoreSentinel(deps.liveRoot);
+		return;
+	}
+	yield* Effect.logInfo(`resuming interrupted restore ${snapshotId} (sentinel at ${deps.liveRoot}/${RESTORE_SENTINEL_FILE_NAME})`).pipe(Effect.annotateLogs({ "devstack.snapshot.id": snapshotId }));
+	if ((yield* Effect.exit(deps.restoreSnapshot(snapshotId)))._tag === "Failure") {
+		yield* Effect.logWarning(`interrupted-restore recovery for ${snapshotId} did not complete; leaving sentinel for the next boot to retry. Investigate the snapshot artifact if this recurs.`);
+		return;
+	}
+	yield* clearRestoreSentinel(deps.liveRoot);
+	yield* Effect.logInfo(`interrupted restore ${snapshotId} recovered`).pipe(Effect.annotateLogs({ "devstack.snapshot.id": snapshotId }));
+});
+//#endregion
+export { RESTORE_SENTINEL_FILE_NAME, RestoreSentinelSchema, clearRestoreSentinel, readRestoreSentinel, recoverInterruptedRestore, writeRestoreSentinel };
+
+//# sourceMappingURL=interrupted-restore.mjs.map

package/dist/orchestrators/snapshot/interrupted-restore.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupted-restore.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/interrupted-restore.ts"],"sourcesContent":["// Interrupted-restore sentinel + boot-time auto-recovery.\n//\n// THE GAP this closes:\n//\n//   `runRestore` (restore.ts) does the staged→target image promotion\n//   (`promoteStagedImages`) + captured-container removal inside an\n//   `Effect.uninterruptible` block AFTER the atomic stage-and-swap has\n//   already published the new runtime root. `Effect.uninterruptible`\n//   guards against an Effect-level interrupt — it does NOT survive a\n//   SIGKILL / power-loss. A hard kill mid-promotion therefore leaves the\n//   swap published (new host-tree + control files live) but the images\n//   only PARTIALLY promoted (a prefix re-tagged to their target names,\n//   the rest still at staging tags or gone), and the scope finalizer\n//   never runs to clean up. On the next boot there was previously NO\n//   breadcrumb, so the half-promotion was unrecoverable without manual\n//   `docker tag` surgery.\n//\n// THE FIX (this module):\n//\n//   A typed sentinel is written into the STAGED tree IMMEDIATELY BEFORE\n//   the atomic swap, so publishing the swap atomically publishes the\n//   sentinel too (it rides the same `rename(staging → runtimeStackRoot)`;\n//   see `fs-plan.ts` `runSwapTree` → `stageAndSwap` step 3). On the\n//   success path restore CLEARS the sentinel the instant the\n//   promotion+removal handoff completes. So:\n//\n//     - a CLEAN restore leaves NO sentinel (boot never loops);\n//     - a hard kill BEFORE the swap landed leaves no published sentinel\n//       (the staging tree was discarded), and the live root is untouched\n//       — nothing to recover;\n//     - a hard kill AFTER the swap but mid-promotion leaves the sentinel\n//       LIVE, so the next boot's `recoverInterruptedRestore` re-runs the\n//       restore for that snapshot id.\n//\n//   Recovery is idempotent because the on-disk snapshot artifact is\n//   preserved across restores (it lives under `<stackRoot>/snapshots/`,\n//   which is on the restore preserve list) and survives a `docker system\n//   prune` (re-staging re-loads the image bundle from the artifact tar).\n//   Re-running `runRestore` re-stages, re-promotes, and re-removes from\n//   scratch; a still-failing artifact simply leaves the sentinel in place\n//   for the next boot to retry (documented loop-safety below).\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport { decodeUnknown, parseJsonText } from '../../substrate/runtime/runtime-decode.ts';\nimport { versionedDocSchema } from '../../substrate/versioned-doc-schema.ts';\nimport { parseSnapshotId, type SnapshotId } from './descriptor.ts';\n\n// -----------------------------------------------------------------------------\n// Sentinel layout + schema\n// -----------------------------------------------------------------------------\n\n/** Fixed hidden filename for the interrupted-restore sentinel. Written at\n *  the ROOT of the staged tree (and therefore at the root of the live\n *  runtime stack root after the swap lands). Hidden + dotted so it never\n *  collides with a plugin's runtime subtree and is visually distinct from\n *  the operator's content. */\nexport const RESTORE_SENTINEL_FILE_NAME = '.devstack-restore-in-progress.json';\n\nexport const SNAPSHOT_RESTORE_SENTINEL_VERSION = 1 as const;\n\n/** The interrupted-restore sentinel record. Carries exactly what\n *  re-running the restore needs: the snapshot id (the orchestrator\n *  derives the artifact dir from it) plus the resolved artifact dir as a\n *  cross-check / diagnostic (the snapshots subtree rides the same atomic\n *  swap, so the artifact at this path is preserved across the restore). */\nexport const RestoreSentinelSchema = versionedDocSchema(SNAPSHOT_RESTORE_SENTINEL_VERSION, {\n\tsnapshotId: Schema.String,\n\tartifactDir: Schema.String,\n});\nexport type RestoreSentinel = Schema.Schema.Type<typeof RestoreSentinelSchema>;\n\nconst sentinelPath = (root: string): string => `${root}/${RESTORE_SENTINEL_FILE_NAME}`;\n\n// -----------------------------------------------------------------------------\n// Write / read / clear\n// -----------------------------------------------------------------------------\n\n/** Write the sentinel JSON into the STAGED tree root at the fixed hidden\n *  path so it rides the atomic stage-and-swap into the live runtime root.\n *  Called from `runRestore` immediately before `executeFsPlan` publishes\n *  the swap. Encode validates the payload against the schema (the\n *  `version` discriminator is supplied here). */\nexport const writeRestoreSentinel = (\n\tstagedRoot: string,\n\tpayload: { readonly snapshotId: SnapshotId; readonly artifactDir: string },\n): Effect.Effect<void, never, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst doc: RestoreSentinel = {\n\t\t\tversion: SNAPSHOT_RESTORE_SENTINEL_VERSION,\n\t\t\tsnapshotId: payload.snapshotId,\n\t\t\tartifactDir: payload.artifactDir,\n\t\t};\n\t\t// Best-effort: the sentinel is an OPTIMIZATION for crash recovery, not\n\t\t// a correctness gate on the restore path. A write failure here must NOT\n\t\t// abort the restore (which would be a worse outcome than the gap the\n\t\t// sentinel closes); it just means a hard kill in the tiny window that\n\t\t// follows would be unrecoverable, exactly as before. Log loud and\n\t\t// proceed.\n\t\tyield* fs\n\t\t\t.writeFileString(sentinelPath(stagedRoot), JSON.stringify(doc))\n\t\t\t.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tEffect.logWarning(\n\t\t\t\t\t\t`restore sentinel write failed at ${sentinelPath(stagedRoot)} — a hard kill ` +\n\t\t\t\t\t\t\t`mid-promotion would be unrecoverable for snapshot ${payload.snapshotId}: ${String(cause)}`,\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t});\n\n/** Read the sentinel from the LIVE runtime root. Returns `null` when the\n *  sentinel is absent (the common case — no interrupted restore) or\n *  present-but-unparseable (logged, then treated as absent so a corrupt\n *  breadcrumb cannot wedge boot; the operator can recover manually). */\nexport const readRestoreSentinel = (\n\tliveRoot: string,\n): Effect.Effect<RestoreSentinel | null, never, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst path = sentinelPath(liveRoot);\n\t\tconst exists = yield* fs.exists(path).pipe(Effect.catch(() => Effect.succeed(false)));\n\t\tif (!exists) return null;\n\t\tconst readExit = yield* Effect.exit(fs.readFileString(path));\n\t\tif (readExit._tag === 'Failure') {\n\t\t\tyield* Effect.logWarning(\n\t\t\t\t`restore sentinel read failed at ${path}; treating as absent (no auto-recovery)`,\n\t\t\t);\n\t\t\treturn null;\n\t\t}\n\t\tconst decodeExit = yield* Effect.exit(\n\t\t\tparseJsonText(readExit.value, {\n\t\t\t\tsource: path,\n\t\t\t\tmkError: (issue) => issue,\n\t\t\t}).pipe(\n\t\t\t\tEffect.flatMap((raw) =>\n\t\t\t\t\tdecodeUnknown(RestoreSentinelSchema, raw, { source: path, mkError: (issue) => issue }),\n\t\t\t\t),\n\t\t\t),\n\t\t);\n\t\tif (decodeExit._tag === 'Failure') {\n\t\t\tyield* Effect.logWarning(\n\t\t\t\t`restore sentinel at ${path} is unparseable; treating as absent (no auto-recovery)`,\n\t\t\t);\n\t\t\treturn null;\n\t\t}\n\t\treturn decodeExit.value;\n\t});\n\n/** Remove the sentinel from the LIVE runtime root. Idempotent\n *  (`force: true`) — a missing sentinel is a no-op. Called on the restore\n *  success path the instant the promotion+removal handoff completes, and\n *  again after a successful auto-recovery re-run. */\nexport const clearRestoreSentinel = (\n\tliveRoot: string,\n): Effect.Effect<void, never, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tyield* fs.remove(sentinelPath(liveRoot), { force: true }).pipe(Effect.ignore);\n\t});\n\n// -----------------------------------------------------------------------------\n// Boot-time recovery\n// -----------------------------------------------------------------------------\n\nexport interface RecoverInterruptedRestoreDeps {\n\t/** The LIVE runtime stack root (`StackPathsService.stackRoot`) the\n\t *  sentinel rode into after the interrupted restore's swap. */\n\treadonly liveRoot: string;\n\t/** Re-run the restore for a snapshot id. Wired by the caller to the\n\t *  orchestrator's `restore({ id })`, which owns the `stack.lock`\n\t *  discipline and the participant/runtime deps — re-running it is\n\t *  idempotent (re-stages from the preserved on-disk artifact). The\n\t *  return value is ignored; the recovery only cares whether it\n\t *  succeeded. The `FileSystem` requirement unifies with this module's\n\t *  own (boot provides it once), so the caller can pass the\n\t *  orchestrator's `restore` verb directly. */\n\treadonly restoreSnapshot: (\n\t\tsnapshotId: SnapshotId,\n\t) => Effect.Effect<unknown, unknown, FileSystem.FileSystem>;\n}\n\n/**\n * Boot-time auto-recovery for a restore interrupted by a hard kill /\n * power-loss between the atomic swap and the end of the image-promotion\n * handoff. Reads the sentinel from the live runtime root; when present,\n * logs a clear \"resuming interrupted restore <id>\" and re-invokes the\n * restore for that snapshot. No-op when the sentinel is absent.\n *\n * Wired at boot BEFORE the first plugin acquire (the `beforeInitialAcquire`\n * hook), so a half-promoted image set is reconciled before any L2 lookup\n * observes the runtime root.\n *\n * ## Loop-safety\n *\n *   - A CLEAN restore cleared the sentinel on its success path, so a clean\n *     boot reads `null` and returns immediately — boot never loops.\n *   - A SUCCESSFUL recovery clears the sentinel after the re-run returns,\n *     so the next boot is clean.\n *   - A STILL-FAILING artifact (re-run fails) DELIBERATELY leaves the\n *     sentinel in place so the next boot retries. The failure is logged\n *     and SWALLOWED — boot continues rather than wedging — but the\n *     sentinel persists as the durable retry breadcrumb. This is the\n *     intended trade: a genuinely corrupt artifact will re-fail every boot\n *     (surfaced by the warning + the restore's own typed phase error in\n *     the logs) rather than silently dropping the recovery intent. An\n *     operator resolves it by repairing/removing the artifact or clearing\n *     the sentinel by hand.\n */\nexport const recoverInterruptedRestore = (\n\tdeps: RecoverInterruptedRestoreDeps,\n): Effect.Effect<void, never, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst sentinel = yield* readRestoreSentinel(deps.liveRoot);\n\t\tif (sentinel === null) return;\n\n\t\tconst snapshotId = parseSnapshotId(sentinel.snapshotId);\n\t\tif (snapshotId === null) {\n\t\t\t// A sentinel whose id is unsafe can't drive a restore (the\n\t\t\t// orchestrator would reject it anyway). Clear it so it doesn't\n\t\t\t// re-trigger this branch every boot, and log loud.\n\t\t\tyield* Effect.logWarning(\n\t\t\t\t`interrupted-restore sentinel carries an unsafe snapshot id (${sentinel.snapshotId}); ` +\n\t\t\t\t\t`clearing it — no auto-recovery possible`,\n\t\t\t);\n\t\t\tyield* clearRestoreSentinel(deps.liveRoot);\n\t\t\treturn;\n\t\t}\n\n\t\tyield* Effect.logInfo(\n\t\t\t`resuming interrupted restore ${snapshotId} (sentinel at ${deps.liveRoot}/${RESTORE_SENTINEL_FILE_NAME})`,\n\t\t).pipe(Effect.annotateLogs({ 'devstack.snapshot.id': snapshotId }));\n\n\t\tconst exit = yield* Effect.exit(deps.restoreSnapshot(snapshotId));\n\t\tif (exit._tag === 'Failure') {\n\t\t\t// Leave the sentinel for the next boot's retry (loop-safety doc\n\t\t\t// above). Swallow so boot continues — a failing recovery must not\n\t\t\t// wedge the stack.\n\t\t\tyield* Effect.logWarning(\n\t\t\t\t`interrupted-restore recovery for ${snapshotId} did not complete; leaving sentinel for ` +\n\t\t\t\t\t`the next boot to retry. Investigate the snapshot artifact if this recurs.`,\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\n\t\t// Recovery succeeded — `runRestore` cleared the sentinel on its own\n\t\t// success path, but clear again defensively (idempotent) so a code\n\t\t// path that ever skipped the in-restore clear cannot re-loop.\n\t\tyield* clearRestoreSentinel(deps.liveRoot);\n\t\tyield* Effect.logInfo(`interrupted restore ${snapshotId} recovered`).pipe(\n\t\t\tEffect.annotateLogs({ 'devstack.snapshot.id': snapshotId }),\n\t\t);\n\t});\n"],"mappings":";;;;;;;;;;AAyDA,MAAa,6BAA6B;;;;;;AAS1C,MAAa,wBAAwB,mBAAA,GAAsD;CAC1F,YAAY,OAAO;CACnB,aAAa,OAAO;AACrB,CAAC;AAGD,MAAM,gBAAgB,SAAyB,GAAG,KAAK,GAAG;;;;;;AAW1D,MAAa,wBACZ,YACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,MAAuB;EAC5B,SAAA;EACA,YAAY,QAAQ;EACpB,aAAa,QAAQ;CACtB;CAOA,OAAO,GACL,gBAAgB,aAAa,UAAU,GAAG,KAAK,UAAU,GAAG,CAAC,CAAC,CAC9D,KACA,OAAO,OAAO,UACb,OAAO,WACN,oCAAoC,aAAa,UAAU,EAAE,mEACP,QAAQ,WAAW,IAAI,OAAO,KAAK,GAC1F,CACD,CACD;AACF,CAAC;;;;;AAMF,MAAa,uBACZ,aAEA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,OAAO,aAAa,QAAQ;CAElC,IAAI,EAAC,OADiB,GAAG,OAAO,IAAI,CAAC,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,KAAK,CAAC,CAAC,IACvE,OAAO;CACpB,MAAM,WAAW,OAAO,OAAO,KAAK,GAAG,eAAe,IAAI,CAAC;CAC3D,IAAI,SAAS,SAAS,WAAW;EAChC,OAAO,OAAO,WACb,mCAAmC,KAAK,wCACzC;EACA,OAAO;CACR;CACA,MAAM,aAAa,OAAO,OAAO,KAChC,cAAc,SAAS,OAAO;EAC7B,QAAQ;EACR,UAAU,UAAU;CACrB,CAAC,CAAC,CAAC,KACF,OAAO,SAAS,QACf,cAAc,uBAAuB,KAAK;EAAE,QAAQ;EAAM,UAAU,UAAU;CAAM,CAAC,CACtF,CACD,CACD;CACA,IAAI,WAAW,SAAS,WAAW;EAClC,OAAO,OAAO,WACb,uBAAuB,KAAK,uDAC7B;EACA,OAAO;CACR;CACA,OAAO,WAAW;AACnB,CAAC;;;;;AAMF,MAAa,wBACZ,aAEA,OAAO,IAAI,aAAa;CAEvB,QAAO,OADW,WAAW,WAAA,CACnB,OAAO,aAAa,QAAQ,GAAG,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,MAAM;AAC7E,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDF,MAAa,6BACZ,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,oBAAoB,KAAK,QAAQ;CACzD,IAAI,aAAa,MAAM;CAEvB,MAAM,aAAa,gBAAgB,SAAS,UAAU;CACtD,IAAI,eAAe,MAAM;EAIxB,OAAO,OAAO,WACb,+DAA+D,SAAS,WAAW,2CAEpF;EACA,OAAO,qBAAqB,KAAK,QAAQ;EACzC;CACD;CAEA,OAAO,OAAO,QACb,gCAAgC,WAAW,gBAAgB,KAAK,SAAS,GAAG,2BAA2B,EACxG,CAAC,CAAC,KAAK,OAAO,aAAa,EAAE,wBAAwB,WAAW,CAAC,CAAC;CAGlE,KAAI,OADgB,OAAO,KAAK,KAAK,gBAAgB,UAAU,CAAC,EAAA,CACvD,SAAS,WAAW;EAI5B,OAAO,OAAO,WACb,oCAAoC,WAAW,kHAEhD;EACA;CACD;CAKA,OAAO,qBAAqB,KAAK,QAAQ;CACzC,OAAO,OAAO,QAAQ,uBAAuB,WAAW,WAAW,CAAC,CAAC,KACpE,OAAO,aAAa,EAAE,wBAAwB,WAAW,CAAC,CAC3D;AACD,CAAC"}

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

@@ -1 +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"}
+{"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(phase: Phase, detail: string, plugin?: string): ((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,gBACzB,OAAc,QAAgB,YAC9B,UACA,OAAO,KACN,IAAI,WAAW;CAAE;CAAO;CAAQ;CAAO,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;AAAG,CAAC,CACrF"}

package/dist/orchestrators/snapshot/prune.mjs

@@ -1,6 +1,10 @@
+import { appName, stackName } from "../../substrate/brand.mjs";
 import { decodeJsonText } from "../../substrate/runtime/runtime-decode.mjs";
 import { SNAPSHOT_IMAGE_ROLE } from "../../runtime/docker/container.mjs";
 import { SnapshotMetadataSchema } from "./descriptor.mjs";
+import { labelScope, reconcileSpec } from "../../substrate/runtime/reconcile/spec.mjs";
+import { reconcileLabel } from "../../substrate/runtime/reconcile/label.mjs";
+import "../../substrate/runtime/reconcile/index.mjs";
 import { makePhaseFailer } from "./phase-error.mjs";
 import { SNAPSHOTS_DIR_NAME } from "./wipe.mjs";
 import { Effect, FileSystem, Schema } from "effect";
@@ -28,47 +32,52 @@ const readMetaOpt = (dir) => Effect.gen(function* () {
 /**
 * 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`).
+* same catalog are not supported (caller holds `stack.lock`).
 *
 * 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.
+*
+* Routed through the unified reconcile: a flat LABEL-scope spec narrowed
+* to `role: SNAPSHOT_IMAGE_ROLE`, carrying NO container target (prune
+* mutates no containers — `target: 'running'` is the label-scope no-op
+* container target) and an `fsPlan` of two ops — `reap-meta-missing`
+* (catalog GC) then `reap-images` (byproduct image sweep). Prune never
+* touches the live deploy cache — only the snapshot byproducts (the image
+* GC); the `PruneResult` shape carries `reaped` + `imagesSwept`.
 */
 const runPrune = (inputs) => Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
-	yield* Effect.annotateCurrentSpan({ "devstack.snapshot.phase": "prune" });
 	const catalogDir = `${inputs.stackRoot}/${SNAPSHOTS_DIR_NAME}`;
-	if (!(yield* fs.exists(catalogDir).pipe(Effect.catch(() => Effect.succeed(false))))) return {
-		inspected: 0,
-		reaped: [],
-		imagesSwept: 0
+	const reapMetaMissing = {
+		op: "reap-meta-missing",
+		catalogDir,
+		isMetaMissing: (dir) => readMetaOpt(dir).pipe(Effect.map((meta) => meta === null)),
+		onReaddirError: failPhase("enumerate-catalog", `readdir ${catalogDir} failed`),
+		onRemoveError: failPhase("sweep-directories", `remove catalog entry failed`)
 	};
-	const ids = yield* fs.readDirectory(catalogDir).pipe(Effect.catch(failPhase("enumerate-catalog", `readdir ${catalogDir} failed`)));
-	const reaped = [];
-	for (const id of ids) {
-		const dir = `${catalogDir}/${id}`;
-		if ((yield* readMetaOpt(dir)) === null) {
-			yield* fs.remove(dir, {
-				recursive: true,
-				force: true
-			}).pipe(Effect.catch(failPhase("sweep-directories", `remove ${dir} failed`)));
-			reaped.push({
-				id,
-				classification: "abandoned"
-			});
-		}
-	}
-	const imagesSwept = yield* inputs.runtime.removeManagedImages({
-		...inputs.imageLabelFilter,
-		role: SNAPSHOT_IMAGE_ROLE
-	}).pipe(Effect.catch(failPhase("sweep-images", `image sweep failed`)));
+	const reapImages = {
+		op: "reap-images",
+		onError: failPhase("sweep-images", `image sweep failed`)
+	};
+	const result = yield* reconcileLabel(reconcileSpec({
+		target: "running",
+		scope: labelScope({
+			app: appName(inputs.imageLabelFilter.app),
+			stack: stackName(inputs.imageLabelFilter.stack),
+			role: SNAPSHOT_IMAGE_ROLE
+		}),
+		direction: "drain",
+		fsPlan: { ops: [reapMetaMissing, reapImages] }
+	}), { runtime: inputs.runtime });
 	return {
-		inspected: ids.length,
-		reaped,
-		imagesSwept
+		inspected: result.inspected,
+		reaped: result.reapedIds.map((id) => ({
+			id,
+			classification: "abandoned"
+		})),
+		imagesSwept: result.imagesSwept
 	};
-}).pipe(Effect.withSpan("orchestrator.snapshot.prune"));
+});
 //#endregion
 export { PrunePhaseError, runPrune };