@mysten-incubation/devstack 0.0.0

package/dist/orchestrators/snapshot/identity-guard.mjs

@@ -0,0 +1,132 @@
+import { Effect, Schema } from "effect";
+//#region src/orchestrators/snapshot/identity-guard.ts
+/** Tagged failure: chain identity (or another contributed key) disagrees
+*  between the snapshot and the live stack. No mutation occurred. */
+var IdentityMismatchError = class extends Schema.TaggedErrorClass()("SnapshotIdentityMismatch", {
+	phase: Schema.Literal("identity-guard"),
+	key: Schema.String,
+	snapshotValue: Schema.String,
+	liveValue: Schema.String
+}) {};
+/** Tagged failure: snapshot recorded a key that the live stack did
+*  not contribute. Fail-closed (architecture open question §5
+*  resolution); the alternative is silently restoring across an
+*  unverified seam. */
+var IdentityMissingLiveError = class extends Schema.TaggedErrorClass()("SnapshotIdentityMissingLive", {
+	phase: Schema.Literal("identity-guard"),
+	key: Schema.String,
+	snapshotValue: Schema.String
+}) {};
+/** Tagged failure: live stack contributed a key the snapshot did NOT
+*  record. Fail-closed for the same reason as above — restoring an
+*  older snapshot that pre-dates the contribution is a code-version
+*  mismatch, not a happy path. */
+var IdentityMissingSnapshotError = class extends Schema.TaggedErrorClass()("SnapshotIdentityMissingSnapshot", {
+	phase: Schema.Literal("identity-guard"),
+	key: Schema.String,
+	liveValue: Schema.String
+}) {};
+var IdentityEmptyError = class extends Schema.TaggedErrorClass()("SnapshotIdentityEmpty", {
+	phase: Schema.Literal("identity-guard"),
+	source: Schema.Literals(["snapshot", "live"])
+}) {};
+/** Tagged failure: two plugins contributed the same key with different
+*  values. The orchestrator surfaces this BEFORE running the guard;
+*  same-key contributions from independent plugins should agree (the
+*  same chain identity contributed by sui and a probe-renderer, say). */
+var IdentityContributionConflictError = class extends Schema.TaggedErrorClass()("SnapshotIdentityContributionConflict", {
+	phase: Schema.Literal("identity-guard"),
+	key: Schema.String,
+	conflictingPlugins: Schema.Array(Schema.String),
+	values: Schema.Array(Schema.String)
+}) {};
+/**
+* Merge a list of plugin contributions into one slice. Conflict
+* (same key, different values across plugins) surfaces as a tagged
+* error — the orchestrator refuses to proceed rather than picking a
+* "winner" silently.
+*
+* Architecture § Snapshotable: identity contributions stack — chain
+* is the canonical case but plugins are free to contribute their own
+* (e.g. postgres major version, sui fork checkpoint).
+*/
+const mergeContributions = (contributions) => Effect.gen(function* () {
+	const seen = {};
+	for (const { plugin, slice } of contributions) for (const [key, value] of Object.entries(slice)) seen[key] = [...seen[key] ?? [], {
+		plugin,
+		value
+	}];
+	const merged = {};
+	for (const [key, entries] of Object.entries(seen)) {
+		const distinct = new Set(entries.map((e) => e.value));
+		if (distinct.size > 1) return yield* Effect.fail(new IdentityContributionConflictError({
+			phase: "identity-guard",
+			key,
+			conflictingPlugins: entries.map((e) => e.plugin),
+			values: [...distinct]
+		}));
+		merged[key] = entries[0].value;
+	}
+	return merged;
+});
+const requireIdentity = (identity, source) => Object.keys(identity).length === 0 ? Effect.fail(new IdentityEmptyError({
+	phase: "identity-guard",
+	source
+})) : Effect.void;
+/**
+* Compare the snapshot's recorded identity against the live stack's
+* contributed identity. Fail-closed on every shape:
+*
+*   - snapshot identity is empty                    → IdentityEmptyError
+*   - keys present on both sides, values differ → IdentityMismatchError
+*   - keys present only in the snapshot          → IdentityMissingLiveError
+*   - keys present only in the live stack        → IdentityMissingSnapshotError
+*
+* The architecture's open-question §5 ("require both sides of the
+* comparison rather than fail-open on either-undefined") resolves to
+* fail-closed; this is the implementation.
+*
+* The guard runs BEFORE any destructive mutation. On a successful
+* return there is no I/O effect to roll back.
+*/
+const runIdentityGuard = (snapshotIdentity, liveIdentity) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({ "devstack.snapshot.phase": "identity-guard" });
+	const snapshotKeys = Object.keys(snapshotIdentity);
+	const liveKeys = Object.keys(liveIdentity);
+	yield* requireIdentity(snapshotIdentity, "snapshot");
+	for (const key of snapshotKeys) if (key in liveIdentity) {
+		if (snapshotIdentity[key] !== liveIdentity[key]) return yield* Effect.fail(new IdentityMismatchError({
+			phase: "identity-guard",
+			key,
+			snapshotValue: snapshotIdentity[key],
+			liveValue: liveIdentity[key]
+		}));
+	}
+	for (const key of snapshotKeys) if (!(key in liveIdentity)) return yield* Effect.fail(new IdentityMissingLiveError({
+		phase: "identity-guard",
+		key,
+		snapshotValue: snapshotIdentity[key]
+	}));
+	for (const key of liveKeys) if (!(key in snapshotIdentity)) return yield* Effect.fail(new IdentityMissingSnapshotError({
+		phase: "identity-guard",
+		key,
+		liveValue: liveIdentity[key]
+	}));
+}).pipe(Effect.withSpan("orchestrator.snapshot.identity-guard"));
+const runRuntimeIdentityGuard = (snapshotIdentity, liveIdentity) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({ "devstack.snapshot.phase": "identity-guard" });
+	for (const key of [
+		"app",
+		"stack",
+		"network"
+	]) if (snapshotIdentity[key] !== liveIdentity[key]) return yield* Effect.fail(new IdentityMismatchError({
+		phase: "identity-guard",
+		key,
+		snapshotValue: snapshotIdentity[key],
+		liveValue: liveIdentity[key]
+	}));
+}).pipe(Effect.withSpan("orchestrator.snapshot.runtime-identity-guard"));
+//#endregion
+export { mergeContributions, requireIdentity, runIdentityGuard, runRuntimeIdentityGuard };
+
+//# sourceMappingURL=identity-guard.mjs.map

package/dist/orchestrators/snapshot/identity-guard.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-guard.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/identity-guard.ts"],"sourcesContent":["// Identity guard — fail-closed cross-chain refusal.\n//\n// Architecture § Snapshot:\n//   \"Identity guard. `(app, stack, network)` plus chain identity plus\n//   optional plugin contributions. Fires before any destructive\n//   mutation.\"\n//\n// Architecture § Invariants:\n//   \"Cross-chain refusal. When both the snapshot and the live stack\n//   carry a known chain identity and they disagree, restore must\n//   refuse before any destructive mutation.\"\n//\n// Composition shape: the orchestrator collects an `IdentitySlice`\n// from EACH participating plugin's `preRestore` contribution. The\n// final guard compares the snapshot's stored slice against the live\n// slice key-by-key. A disagreement on ANY key refuses. A key set on\n// one side but not the other is decided by the fail-closed policy:\n// the orchestrator's policy is fail-closed-when-snapshot-set (open\n// question §5 resolution): if the snapshot recorded `chain=X` and the\n// caller did not pass `chain`, the guard refuses with `missing-live`.\n\nimport { Effect, Schema } from 'effect';\n\nimport type { IdentitySlice } from './descriptor.ts';\n\nexport interface SnapshotRuntimeIdentity {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly network: string;\n}\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** Tagged failure: chain identity (or another contributed key) disagrees\n *  between the snapshot and the live stack. No mutation occurred. */\nexport class IdentityMismatchError extends Schema.TaggedErrorClass<IdentityMismatchError>()(\n\t'SnapshotIdentityMismatch',\n\t{\n\t\tphase: Schema.Literal('identity-guard'),\n\t\tkey: Schema.String,\n\t\tsnapshotValue: Schema.String,\n\t\tliveValue: Schema.String,\n\t},\n) {}\n\n/** Tagged failure: snapshot recorded a key that the live stack did\n *  not contribute. Fail-closed (architecture open question §5\n *  resolution); the alternative is silently restoring across an\n *  unverified seam. */\nexport class IdentityMissingLiveError extends Schema.TaggedErrorClass<IdentityMissingLiveError>()(\n\t'SnapshotIdentityMissingLive',\n\t{\n\t\tphase: Schema.Literal('identity-guard'),\n\t\tkey: Schema.String,\n\t\tsnapshotValue: Schema.String,\n\t},\n) {}\n\n/** Tagged failure: live stack contributed a key the snapshot did NOT\n *  record. Fail-closed for the same reason as above — restoring an\n *  older snapshot that pre-dates the contribution is a code-version\n *  mismatch, not a happy path. */\nexport class IdentityMissingSnapshotError extends Schema.TaggedErrorClass<IdentityMissingSnapshotError>()(\n\t'SnapshotIdentityMissingSnapshot',\n\t{\n\t\tphase: Schema.Literal('identity-guard'),\n\t\tkey: Schema.String,\n\t\tliveValue: Schema.String,\n\t},\n) {}\n\nexport class IdentityEmptyError extends Schema.TaggedErrorClass<IdentityEmptyError>()(\n\t'SnapshotIdentityEmpty',\n\t{\n\t\tphase: Schema.Literal('identity-guard'),\n\t\tsource: Schema.Literals(['snapshot', 'live']),\n\t},\n) {}\n\nexport type IdentityGuardError =\n\t| IdentityMismatchError\n\t| IdentityMissingLiveError\n\t| IdentityMissingSnapshotError\n\t| IdentityEmptyError;\n\n// -----------------------------------------------------------------------------\n// Composition — many plugins, one merged slice\n// -----------------------------------------------------------------------------\n\n/** One participant's contribution to the identity slice — produced by\n *  the plugin's `preRestore` hook, schema-decoded by the orchestrator. */\nexport interface IdentityContribution {\n\treadonly plugin: string;\n\treadonly slice: IdentitySlice;\n}\n\n/** Tagged failure: two plugins contributed the same key with different\n *  values. The orchestrator surfaces this BEFORE running the guard;\n *  same-key contributions from independent plugins should agree (the\n *  same chain identity contributed by sui and a probe-renderer, say). */\nexport class IdentityContributionConflictError extends Schema.TaggedErrorClass<IdentityContributionConflictError>()(\n\t'SnapshotIdentityContributionConflict',\n\t{\n\t\tphase: Schema.Literal('identity-guard'),\n\t\tkey: Schema.String,\n\t\tconflictingPlugins: Schema.Array(Schema.String),\n\t\tvalues: Schema.Array(Schema.String),\n\t},\n) {}\n\n/**\n * Merge a list of plugin contributions into one slice. Conflict\n * (same key, different values across plugins) surfaces as a tagged\n * error — the orchestrator refuses to proceed rather than picking a\n * \"winner\" silently.\n *\n * Architecture § Snapshotable: identity contributions stack — chain\n * is the canonical case but plugins are free to contribute their own\n * (e.g. postgres major version, sui fork checkpoint).\n */\nexport const mergeContributions = (\n\tcontributions: ReadonlyArray<IdentityContribution>,\n): Effect.Effect<IdentitySlice, IdentityContributionConflictError> =>\n\tEffect.gen(function* () {\n\t\t// Group by key so the conflict surface lists every offender.\n\t\tconst seen: Record<string, ReadonlyArray<{ plugin: string; value: string }>> = {};\n\t\tfor (const { plugin, slice } of contributions) {\n\t\t\tfor (const [key, value] of Object.entries(slice)) {\n\t\t\t\tconst prior = seen[key] ?? [];\n\t\t\t\tseen[key] = [...prior, { plugin, value }];\n\t\t\t}\n\t\t}\n\t\tconst merged: Record<string, string> = {};\n\t\tfor (const [key, entries] of Object.entries(seen)) {\n\t\t\tconst distinct = new Set(entries.map((e) => e.value));\n\t\t\tif (distinct.size > 1) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew IdentityContributionConflictError({\n\t\t\t\t\t\tphase: 'identity-guard',\n\t\t\t\t\t\tkey,\n\t\t\t\t\t\tconflictingPlugins: entries.map((e) => e.plugin),\n\t\t\t\t\t\tvalues: [...distinct],\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t\t// `distinct.size === 1` guaranteed (every entry contributes one value).\n\t\t\tmerged[key] = entries[0]!.value;\n\t\t}\n\t\treturn merged;\n\t});\n\n// -----------------------------------------------------------------------------\n// The guard itself\n// -----------------------------------------------------------------------------\n\nexport const requireIdentity = (\n\tidentity: IdentitySlice,\n\tsource: IdentityEmptyError['source'],\n): Effect.Effect<void, IdentityEmptyError> =>\n\tObject.keys(identity).length === 0\n\t\t? Effect.fail(new IdentityEmptyError({ phase: 'identity-guard', source }))\n\t\t: Effect.void;\n\n/**\n * Compare the snapshot's recorded identity against the live stack's\n * contributed identity. Fail-closed on every shape:\n *\n *   - snapshot identity is empty                    → IdentityEmptyError\n *   - keys present on both sides, values differ → IdentityMismatchError\n *   - keys present only in the snapshot          → IdentityMissingLiveError\n *   - keys present only in the live stack        → IdentityMissingSnapshotError\n *\n * The architecture's open-question §5 (\"require both sides of the\n * comparison rather than fail-open on either-undefined\") resolves to\n * fail-closed; this is the implementation.\n *\n * The guard runs BEFORE any destructive mutation. On a successful\n * return there is no I/O effect to roll back.\n */\nexport const runIdentityGuard = (\n\tsnapshotIdentity: IdentitySlice,\n\tliveIdentity: IdentitySlice,\n): Effect.Effect<void, IdentityGuardError> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.snapshot.phase': 'identity-guard',\n\t\t});\n\t\tconst snapshotKeys = Object.keys(snapshotIdentity);\n\t\tconst liveKeys = Object.keys(liveIdentity);\n\t\tyield* requireIdentity(snapshotIdentity, 'snapshot');\n\t\t// 1. Keys present on both sides — disagreement is the canonical refuse.\n\t\tfor (const key of snapshotKeys) {\n\t\t\tif (key in liveIdentity) {\n\t\t\t\tif (snapshotIdentity[key] !== liveIdentity[key]) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tnew IdentityMismatchError({\n\t\t\t\t\t\t\tphase: 'identity-guard',\n\t\t\t\t\t\t\tkey,\n\t\t\t\t\t\t\tsnapshotValue: snapshotIdentity[key]!,\n\t\t\t\t\t\t\tliveValue: liveIdentity[key]!,\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}\n\t\t// 2. Snapshot recorded a key live did not contribute. Fail-closed.\n\t\tfor (const key of snapshotKeys) {\n\t\t\tif (!(key in liveIdentity)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew IdentityMissingLiveError({\n\t\t\t\t\t\tphase: 'identity-guard',\n\t\t\t\t\t\tkey,\n\t\t\t\t\t\tsnapshotValue: snapshotIdentity[key]!,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\t// 3. Live contributed a key the snapshot did not record. Fail-closed.\n\t\tfor (const key of liveKeys) {\n\t\t\tif (!(key in snapshotIdentity)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew IdentityMissingSnapshotError({\n\t\t\t\t\t\tphase: 'identity-guard',\n\t\t\t\t\t\tkey,\n\t\t\t\t\t\tliveValue: liveIdentity[key]!,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}).pipe(Effect.withSpan('orchestrator.snapshot.identity-guard'));\n\nexport const runRuntimeIdentityGuard = (\n\tsnapshotIdentity: SnapshotRuntimeIdentity,\n\tliveIdentity: SnapshotRuntimeIdentity,\n): Effect.Effect<void, IdentityMismatchError> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.snapshot.phase': 'identity-guard',\n\t\t});\n\t\tconst keys: ReadonlyArray<keyof SnapshotRuntimeIdentity> = ['app', 'stack', 'network'];\n\t\tfor (const key of keys) {\n\t\t\tif (snapshotIdentity[key] !== liveIdentity[key]) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew IdentityMismatchError({\n\t\t\t\t\t\tphase: 'identity-guard',\n\t\t\t\t\t\tkey,\n\t\t\t\t\t\tsnapshotValue: snapshotIdentity[key],\n\t\t\t\t\t\tliveValue: liveIdentity[key],\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}).pipe(Effect.withSpan('orchestrator.snapshot.runtime-identity-guard'));\n"],"mappings":"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"}

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

@@ -0,0 +1,207 @@
+import { isRestorableContainerImageName } from "./descriptor.mjs";
+import { Effect, FileSystem, Schema, Stream } from "effect";
+//#region src/orchestrators/snapshot/image-bundle-tags.ts
+var ImageBundleTagScanError = class extends Schema.TaggedErrorClass()("SnapshotImageBundleTagScanError", {
+	detail: Schema.String,
+	cause: Schema.optional(Schema.Defect)
+}) {};
+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;
+			}
+			continue;
+		}
+		if (state.skipRemaining > 0) {
+			const take = Math.min(state.skipRemaining, state.buffer.length);
+			state.skipRemaining -= take;
+			state.buffer = consumeBytes(state.buffer, take);
+			continue;
+		}
+		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 { done: false };
+};
+const parseDockerSaveManifestTags = (bytes, tarPath) => Effect.gen(function* () {
+	const raw = yield* Effect.try({
+		try: () => JSON.parse(Buffer.from(bytes).toString("utf8")),
+		catch: (cause) => failScan(`docker save manifest.json in ${tarPath} is not valid JSON`, cause)
+	});
+	if (!Array.isArray(raw)) return yield* Effect.fail(failScan(`docker save manifest.json in ${tarPath} is not an array`));
+	const tags = /* @__PURE__ */ new Set();
+	for (const [index, entry] of raw.entries()) {
+		if (typeof entry !== "object" || entry === null) return yield* Effect.fail(failScan(`docker save manifest entry ${index} in ${tarPath} is not an object`));
+		const repoTags = entry.RepoTags;
+		if (repoTags === void 0 || repoTags === null) continue;
+		if (!Array.isArray(repoTags)) return yield* Effect.fail(failScan(`docker save manifest entry ${index} in ${tarPath} has non-array RepoTags`));
+		for (const tag of repoTags) {
+			if (typeof tag !== "string" || !isRestorableContainerImageName(tag)) return yield* Effect.fail(failScan(`docker save manifest entry ${index} in ${tarPath} has invalid RepoTag ${String(tag)}`));
+			if (tags.has(tag)) return yield* Effect.fail(failScan(`docker save manifest in ${tarPath} repeats RepoTag ${tag}`));
+			tags.add(tag);
+		}
+	}
+	return tags;
+});
+const normalizeOciImageName = (value) => {
+	if (value.startsWith("docker.io/library/")) {
+		const localName = value.slice(18);
+		if (localName.startsWith("devstack-snapshot:") && isRestorableContainerImageName(localName)) return localName;
+		return null;
+	}
+	if (value.startsWith("devstack-snapshot:") && isRestorableContainerImageName(value)) return value;
+	return null;
+};
+const parseOciImageLayoutIndexTags = (bytes, tarPath) => Effect.gen(function* () {
+	const raw = yield* Effect.try({
+		try: () => JSON.parse(Buffer.from(bytes).toString("utf8")),
+		catch: (cause) => failScan(`docker save index.json in ${tarPath} is not valid JSON`, cause)
+	});
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return yield* Effect.fail(failScan(`docker save index.json in ${tarPath} is not an object`));
+	const manifests = raw.manifests;
+	if (!Array.isArray(manifests)) return yield* Effect.fail(failScan(`docker save index.json in ${tarPath} has non-array manifests`));
+	const tags = /* @__PURE__ */ new Set();
+	for (const [index, entry] of manifests.entries()) {
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return yield* Effect.fail(failScan(`docker save index manifest ${index} in ${tarPath} is not an object`));
+		const annotations = entry.annotations;
+		if (annotations === void 0 || annotations === null) continue;
+		if (typeof annotations !== "object" || Array.isArray(annotations)) return yield* Effect.fail(failScan(`docker save index manifest ${index} in ${tarPath} has invalid annotations`));
+		const imageName = annotations["io.containerd.image.name"];
+		const refName = annotations["org.opencontainers.image.ref.name"];
+		for (const value of [imageName, refName]) {
+			if (typeof value !== "string") continue;
+			const tag = normalizeOciImageName(value);
+			if (tag === null) continue;
+			if (tags.has(tag)) return yield* Effect.fail(failScan(`docker save index in ${tarPath} repeats RepoTag ${tag}`));
+			tags.add(tag);
+		}
+	}
+	return tags;
+});
+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
+	};
+	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);
+	}), 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);
+	return yield* Effect.fail(failScan(`docker save bundle ${tarPath} does not contain manifest.json or index.json`));
+});
+const verifyImageBundleTags = (tarPath, actualTags, expectedSnapshotTags) => {
+	const expected = /* @__PURE__ */ new Set();
+	const repeatedExpected = [];
+	for (const tag of expectedSnapshotTags) if (expected.has(tag)) repeatedExpected.push(tag);
+	else expected.add(tag);
+	if (repeatedExpected.length > 0) return Effect.fail(failScan(`docker save bundle ${tarPath} expected duplicate snapshot tags: ${repeatedExpected.join(", ")}`));
+	const missing = [...expected].filter((tag) => !actualTags.has(tag));
+	const unexpected = [...actualTags].filter((tag) => !expected.has(tag));
+	if (missing.length === 0 && unexpected.length === 0) return Effect.void;
+	const parts = [];
+	if (missing.length > 0) parts.push(`missing: ${missing.join(", ")}`);
+	if (unexpected.length > 0) parts.push(`unexpected: ${unexpected.join(", ")}`);
+	return Effect.fail(failScan(`docker save bundle ${tarPath} tags do not match snapshot metadata (${parts.join("; ")})`));
+};
+//#endregion
+export { readImageBundleTags, verifyImageBundleTags };
+
+//# sourceMappingURL=image-bundle-tags.mjs.map

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

@@ -0,0 +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":";;;AAIA,IAAa,0BAAb,cAA6C,OAAO,kBAA2C,CAC9F,mCACA;CACC,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CACD,CAAC;AAEF,MAAM,YAAY,QAAgB,UACjC,IAAI,wBAAwB;CAC3B;CACA,GAAI,UAAU,KAAA,IAAY,EAAE,GAAG,EAAE,OAAO;CACxC,CAAC;AAEH,MAAM,iBAAiB;AACvB,MAAM,iCAAiC,OAAO;AAE9C,MAAM,iBAAiB,UAA8B;CACpD,MAAM,MAAM,MAAM,QAAQ,EAAE;CAC5B,MAAM,MAAM,QAAQ,KAAK,MAAM,SAAS;AACxC,QAAO,OAAO,KAAK,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,SAAS,OAAO;;AAG5D,MAAM,eAAe,GAAe,MAA8B;AACjE,KAAI,EAAE,WAAW,EAAG,QAAO;AAC3B,KAAI,EAAE,WAAW,EAAG,QAAO;CAC3B,MAAM,MAAM,IAAI,WAAW,EAAE,SAAS,EAAE,OAAO;AAC/C,KAAI,IAAI,GAAG,EAAE;AACb,KAAI,IAAI,GAAG,EAAE,OAAO;AACpB,QAAO;;AAGR,MAAM,gBAAgB,QAAoB,UAA8B,OAAO,SAAS,MAAM;AAE9F,MAAM,eAAe,UAA+B,MAAM,OAAO,SAAS,SAAS,EAAE;AAErF,MAAM,gBAAgB,WAAsC;CAC3D,MAAM,MAAM,cAAc,OAAO,SAAS,KAAK,IAAI,CAAC,CAAC,MAAM;AAC3D,KAAI,QAAQ,GAAI,QAAO;AACvB,KAAI,CAAC,WAAW,KAAK,IAAI,CAAE,QAAO;CAClC,MAAM,SAAS,OAAO,SAAS,KAAK,EAAE;AACtC,QAAO,OAAO,cAAc,OAAO,IAAI,UAAU,IAAI,SAAS;;AAG/D,MAAM,qBAAqB,WAA+B;CACzD,MAAM,OAAO,cAAc,OAAO,SAAS,GAAG,IAAI,CAAC;CACnD,MAAM,SAAS,cAAc,OAAO,SAAS,KAAK,IAAI,CAAC;AACvD,QAAO,WAAW,KAAK,OAAO,GAAG,OAAO,GAAG;;AAG5C,MAAM,0BAA0B,SAAyB;CACxD,IAAI,aAAa;AACjB,QAAO,WAAW,WAAW,KAAK,CAAE,cAAa,WAAW,MAAM,EAAE;AACpE,QAAO;;AAoBR,MAAM,kCACL,OACA,UAC0E;AAC1E,OAAM,SAAS,YAAY,MAAM,QAAQ,MAAM;AAC/C,QAAO,MAAM,OAAO,SAAS,GAAG;AAC/B,MAAI,MAAM,YAAY,MAAM;GAC3B,MAAM,UAAU,MAAM;GACtB,MAAM,YAAY,QAAQ,aAAa,QAAQ;GAC/C,MAAM,OAAO,KAAK,IAAI,WAAW,MAAM,OAAO,OAAO;GACrD,MAAM,cAAc,KAAK,IAAI,GAAG,KAAK,IAAI,MAAM,QAAQ,OAAO,QAAQ,iBAAiB,CAAC;AACxF,OAAI,cAAc,EACjB,SAAQ,OAAO,KAAK,MAAM,OAAO,SAAS,GAAG,YAAY,CAAC;AAE3D,SAAM,UAAU;IACf,GAAG;IACH,kBAAkB,QAAQ,mBAAmB;IAC7C,gBAAgB,QAAQ,iBAAiB;IACzC;AACD,SAAM,SAAS,aAAa,MAAM,QAAQ,KAAK;AAC/C,OAAI,MAAM,QAAQ,mBAAmB,MAAM,QAAQ,YAAY;IAC9D,MAAM,YAAY,MAAM;AACxB,UAAM,UAAU;IAChB,MAAM,aACL,UAAU,OAAO,WAAW,IACzB,UAAU,OAAO,KACjB,OAAO,OAAO,UAAU,OAAO,KAAK,UAAU,OAAO,KAAK,MAAM,CAAC,CAAC;AACtE,QAAI,UAAU,UAAU,iBAAiB;AACxC,WAAM,gBAAgB;AACtB,YAAO,EAAE,MAAM,MAAM;;AAEtB,UAAM,aAAa;;AAEpB;;AAED,MAAI,MAAM,gBAAgB,GAAG;GAC5B,MAAM,OAAO,KAAK,IAAI,MAAM,eAAe,MAAM,OAAO,OAAO;AAC/D,SAAM,iBAAiB;AACvB,SAAM,SAAS,aAAa,MAAM,QAAQ,KAAK;AAC/C;;AAED,MAAI,MAAM,OAAO,SAAS,eAAgB,QAAO,EAAE,MAAM,OAAO;EAChE,MAAM,SAAS,MAAM,OAAO,SAAS,GAAG,eAAe;AACvD,QAAM,SAAS,aAAa,MAAM,QAAQ,eAAe;AACzD,MAAI,YAAY,OAAO,CAAE;EACzB,MAAM,OAAO,aAAa,OAAO;AACjC,MAAI,SAAS,KACZ,QAAO;GAAE,MAAM;GAAO,OAAO,SAAS,0CAA0C;GAAE;EAEnF,MAAM,aAAa,KAAK,KAAK,OAAO,eAAe,GAAG;EACtD,MAAM,YAAY,uBAAuB,kBAAkB,OAAO,CAAC;AACnE,MAAI,cAAc,mBAAmB,cAAc,cAAc;AAChE,OAAI,OAAO,+BACV,QAAO;IACN,MAAM;IACN,OAAO,SAAS,eAAe,UAAU,eAAe;IACxD;AAEF,OAAI,SAAS,GAAG;AACf,QAAI,cAAc,iBAAiB;AAClC,WAAM,gBAAgB,IAAI,WAAW,EAAE;AACvC,YAAO,EAAE,MAAM,MAAM;;AAEtB,UAAM,aAAa,IAAI,WAAW,EAAE;AACpC;;AAED,SAAM,UAAU;IACf,OAAO;IACP;IACA;IACA,QAAQ,EAAE;IACV,kBAAkB;IAClB,gBAAgB;IAChB;AACD;;AAED,QAAM,gBAAgB;;AAEvB,QAAO,EAAE,MAAM,OAAO;;AAGvB,MAAM,+BACL,OACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,MAAM,OAAO,OAAO,IAAI;EAC7B,WAAW,KAAK,MAAM,OAAO,KAAK,MAAM,CAAC,SAAS,OAAO,CAAC;EAC1D,QAAQ,UACP,SAAS,gCAAgC,QAAQ,qBAAqB,MAAM;EAC7E,CAAC;AACF,KAAI,CAAC,MAAM,QAAQ,IAAI,CACtB,QAAO,OAAO,OAAO,KACpB,SAAS,gCAAgC,QAAQ,kBAAkB,CACnE;CAEF,MAAM,uBAAO,IAAI,KAAa;AAC9B,MAAK,MAAM,CAAC,OAAO,UAAU,IAAI,SAAS,EAAE;AAC3C,MAAI,OAAO,UAAU,YAAY,UAAU,KAC1C,QAAO,OAAO,OAAO,KACpB,SAAS,8BAA8B,MAAM,MAAM,QAAQ,mBAAmB,CAC9E;EAEF,MAAM,WAAY,MAA0C;AAC5D,MAAI,aAAa,KAAA,KAAa,aAAa,KAAM;AACjD,MAAI,CAAC,MAAM,QAAQ,SAAS,CAC3B,QAAO,OAAO,OAAO,KACpB,SAAS,8BAA8B,MAAM,MAAM,QAAQ,yBAAyB,CACpF;AAEF,OAAK,MAAM,OAAO,UAAU;AAC3B,OAAI,OAAO,QAAQ,YAAY,CAAC,+BAA+B,IAAI,CAClE,QAAO,OAAO,OAAO,KACpB,SACC,8BAA8B,MAAM,MAAM,QAAQ,uBAAuB,OACxE,IACA,GACD,CACD;AAEF,OAAI,KAAK,IAAI,IAAI,CAChB,QAAO,OAAO,OAAO,KACpB,SAAS,2BAA2B,QAAQ,mBAAmB,MAAM,CACrE;AAEF,QAAK,IAAI,IAAI;;;AAGf,QAAO;EACN;AAEH,MAAM,yBAAyB,UAAiC;AAE/D,KAAI,MAAM,WAAW,qBAAoB,EAAE;EAC1C,MAAM,YAAY,MAAM,MAAM,GAA2B;AACzD,MAAI,UAAU,WAAW,qBAAqB,IAAI,+BAA+B,UAAU,CAC1F,QAAO;AAER,SAAO;;AAER,KAAI,MAAM,WAAW,qBAAqB,IAAI,+BAA+B,MAAM,CAClF,QAAO;AAER,QAAO;;AAGR,MAAM,gCACL,OACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,MAAM,OAAO,OAAO,IAAI;EAC7B,WAAW,KAAK,MAAM,OAAO,KAAK,MAAM,CAAC,SAAS,OAAO,CAAC;EAC1D,QAAQ,UAAU,SAAS,6BAA6B,QAAQ,qBAAqB,MAAM;EAC3F,CAAC;AACF,KAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,MAAM,QAAQ,IAAI,CAChE,QAAO,OAAO,OAAO,KAAK,SAAS,6BAA6B,QAAQ,mBAAmB,CAAC;CAE7F,MAAM,YAAa,IAAyC;AAC5D,KAAI,CAAC,MAAM,QAAQ,UAAU,CAC5B,QAAO,OAAO,OAAO,KACpB,SAAS,6BAA6B,QAAQ,0BAA0B,CACxE;CAEF,MAAM,uBAAO,IAAI,KAAa;AAC9B,MAAK,MAAM,CAAC,OAAO,UAAU,UAAU,SAAS,EAAE;AACjD,MAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,MAAM,CACtE,QAAO,OAAO,OAAO,KACpB,SAAS,8BAA8B,MAAM,MAAM,QAAQ,mBAAmB,CAC9E;EAEF,MAAM,cAAe,MAA6C;AAClE,MAAI,gBAAgB,KAAA,KAAa,gBAAgB,KAAM;AACvD,MAAI,OAAO,gBAAgB,YAAY,MAAM,QAAQ,YAAY,CAChE,QAAO,OAAO,OAAO,KACpB,SAAS,8BAA8B,MAAM,MAAM,QAAQ,0BAA0B,CACrF;EAEF,MAAM,YAAa,YAClB;EAED,MAAM,UAAW,YAChB;AAED,OAAK,MAAM,SAAS,CAAC,WAAW,QAAQ,EAAE;AACzC,OAAI,OAAO,UAAU,SAAU;GAC/B,MAAM,MAAM,sBAAsB,MAAM;AACxC,OAAI,QAAQ,KAAM;AAClB,OAAI,KAAK,IAAI,IAAI,CAChB,QAAO,OAAO,OAAO,KACpB,SAAS,wBAAwB,QAAQ,mBAAmB,MAAM,CAClE;AAEF,QAAK,IAAI,IAAI;;;AAGf,QAAO;EACN;AAEH,MAAa,uBACZ,aACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAC7B,MAAM,QAAoC;EACzC,QAAQ,IAAI,WAAW,EAAE;EACzB,eAAe;EACf,eAAe;EACf,YAAY;EACZ,SAAS;EACT;AACD,QAAO,GAAG,OAAO,YAAY,CAAC,KAC7B,OAAO,iBAAiB,UAAU;EACjC,MAAM,SAAS,+BAA+B,OAAO,MAAM;AAC3D,MAAI,OAAO,UAAU,KAAA,EAAW,QAAO,OAAO,KAAK,OAAO,MAAM;AAChE,SAAO,OAAO,QAAQ,OAAO,KAAK;GACjC,EACF,OAAO,UACP,OAAO,OAAO,UACb,iBAAiB,0BACd,OAAO,KAAK,MAAM,GAClB,OAAO,KAAK,SAAS,kCAAkC,YAAY,UAAU,MAAM,CAAC,CACvF,CACD;AACD,KAAI,MAAM,kBAAkB,KAC3B,QAAO,OAAO,4BAA4B,MAAM,eAAe,QAAQ;AAExE,KAAI,MAAM,eAAe,KACxB,QAAO,OAAO,6BAA6B,MAAM,YAAY,QAAQ;AAEtE,QAAO,OAAO,OAAO,KACpB,SAAS,sBAAsB,QAAQ,+CAA+C,CACtF;EACA;AAEH,MAAa,yBACZ,SACA,YACA,yBACkD;CAClD,MAAM,2BAAW,IAAI,KAAa;CAClC,MAAM,mBAA6B,EAAE;AACrC,MAAK,MAAM,OAAO,qBACjB,KAAI,SAAS,IAAI,IAAI,CACpB,kBAAiB,KAAK,IAAI;KAE1B,UAAS,IAAI,IAAI;AAGnB,KAAI,iBAAiB,SAAS,EAC7B,QAAO,OAAO,KACb,SACC,sBAAsB,QAAQ,qCAAqC,iBAAiB,KACnF,KACA,GACD,CACD;CAEF,MAAM,UAAU,CAAC,GAAG,SAAS,CAAC,QAAQ,QAAQ,CAAC,WAAW,IAAI,IAAI,CAAC;CACnE,MAAM,aAAa,CAAC,GAAG,WAAW,CAAC,QAAQ,QAAQ,CAAC,SAAS,IAAI,IAAI,CAAC;AACtE,KAAI,QAAQ,WAAW,KAAK,WAAW,WAAW,EAAG,QAAO,OAAO;CACnE,MAAM,QAAkB,EAAE;AAC1B,KAAI,QAAQ,SAAS,EAAG,OAAM,KAAK,YAAY,QAAQ,KAAK,KAAK,GAAG;AACpE,KAAI,WAAW,SAAS,EAAG,OAAM,KAAK,eAAe,WAAW,KAAK,KAAK,GAAG;AAC7E,QAAO,OAAO,KACb,SACC,sBAAsB,QAAQ,wCAAwC,MAAM,KAAK,KAAK,CAAC,GACvF,CACD"}

package/dist/orchestrators/snapshot/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/orchestrators/snapshot/integrity.d.mts

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

package/dist/orchestrators/snapshot/integrity.mjs

@@ -0,0 +1,74 @@
+import { IntegrityFileSchema, SnapshotLayout, isSafeSnapshotRelativePath } from "./descriptor.mjs";
+import { Effect, FileSystem, Schema, Stream } from "effect";
+import { createHash } from "node:crypto";
+//#region src/orchestrators/snapshot/integrity.ts
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+const fail = (detail) => Effect.fail(new Error(detail));
+const hashFile = (path) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const hash = createHash("sha256");
+	yield* Stream.runForEach(fs.stream(path), (chunk) => Effect.sync(() => {
+		hash.update(chunk);
+	})).pipe(Effect.catch((cause) => fail(`hash ${path} failed: ${String(cause)}`)));
+	return hash.digest("hex");
+});
+const collectArtifactFiles = (root) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const files = [];
+	const walk = (dir, prefix) => Effect.gen(function* () {
+		const names = yield* fs.readDirectory(dir).pipe(Effect.catch((cause) => fail(`readDirectory(${dir}) failed: ${String(cause)}`)));
+		for (const name of names) {
+			const relPath = prefix === "" ? name : `${prefix}/${name}`;
+			if (!isSafeSnapshotRelativePath(relPath)) return yield* fail(`unsafe artifact relative path: ${relPath}`);
+			const absPath = `${dir}/${name}`;
+			const stat = yield* fs.stat(absPath).pipe(Effect.catch((cause) => fail(`stat(${absPath}) failed: ${String(cause)}`)));
+			if (stat.type === "Directory") yield* walk(absPath, relPath);
+			else if (stat.type === "File") {
+				if (relPath !== SnapshotLayout.integrityFile) files.push(relPath);
+			} else return yield* fail(`snapshot artifact path is not a regular file: ${relPath}`);
+		}
+	});
+	yield* walk(root, "");
+	return files.sort((a, b) => a.localeCompare(b));
+});
+const computeArtifactIntegrity = (root) => Effect.gen(function* () {
+	const hashes = {};
+	for (const relPath of yield* collectArtifactFiles(root)) hashes[relPath] = yield* hashFile(`${root}/${relPath}`);
+	return {
+		version: 1,
+		hashes
+	};
+});
+const writeArtifactIntegrity = (root) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const integrity = yield* computeArtifactIntegrity(root);
+	yield* fs.writeFileString(`${root}/${SnapshotLayout.integrityFile}`, JSON.stringify(integrity, null, 2)).pipe(Effect.catch((cause) => fail(`write ${SnapshotLayout.integrityFile} failed: ${String(cause)}`)));
+	return integrity;
+});
+const readIntegrity = (root) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = `${root}/${SnapshotLayout.integrityFile}`;
+	const text = yield* fs.readFileString(path).pipe(Effect.catch((cause) => fail(`read ${path} failed: ${String(cause)}`)));
+	const raw = yield* Effect.try({
+		try: () => JSON.parse(text),
+		catch: (cause) => /* @__PURE__ */ new Error(`${path} is not valid JSON: ${String(cause)}`)
+	});
+	const decoded = yield* Schema.decodeUnknownEffect(IntegrityFileSchema)(raw).pipe(Effect.catch((cause) => fail(`${path} failed schema decode: ${String(cause)}`)));
+	for (const [relPath, digest] of Object.entries(decoded.hashes)) {
+		if (!isSafeSnapshotRelativePath(relPath) || relPath === SnapshotLayout.integrityFile) return yield* fail(`unsafe integrity path: ${relPath}`);
+		if (!SHA256_HEX.test(digest)) return yield* fail(`invalid sha256 digest for ${relPath}`);
+	}
+	return decoded;
+});
+const verifyArtifactIntegrity = (root) => Effect.gen(function* () {
+	const expected = yield* readIntegrity(root);
+	const actual = yield* computeArtifactIntegrity(root);
+	const expectedPaths = Object.keys(expected.hashes).sort((a, b) => a.localeCompare(b));
+	const actualPaths = Object.keys(actual.hashes).sort((a, b) => a.localeCompare(b));
+	if (expectedPaths.join("\n") !== actualPaths.join("\n")) return yield* fail("snapshot integrity file list does not match artifact contents");
+	for (const relPath of expectedPaths) if (expected.hashes[relPath] !== actual.hashes[relPath]) return yield* fail(`snapshot integrity mismatch for ${relPath}`);
+});
+//#endregion
+export { verifyArtifactIntegrity, writeArtifactIntegrity };
+
+//# sourceMappingURL=integrity.mjs.map

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

@@ -0,0 +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 {\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\nconst fail = (detail: string): Effect.Effect<never, Error> => Effect.fail(new Error(detail));\n\nconst hashFile = (path: string): Effect.Effect<string, Error, 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) => fail(`hash ${path} failed: ${String(cause)}`)));\n\t\treturn hash.digest('hex');\n\t});\n\nconst collectArtifactFiles = (\n\troot: string,\n): Effect.Effect<ReadonlyArray<string>, Error, 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, Error> =>\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) => fail(`readDirectory(${dir}) failed: ${String(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* fail(`unsafe artifact relative path: ${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) => fail(`stat(${absPath}) failed: ${String(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* fail(`snapshot artifact path is not a regular file: ${relPath}`);\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, Error, 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, Error, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst integrity = yield* computeArtifactIntegrity(root);\n\t\tyield* fs\n\t\t\t.writeFileString(\n\t\t\t\t`${root}/${SnapshotLayout.integrityFile}`,\n\t\t\t\tJSON.stringify(integrity, null, 2),\n\t\t\t)\n\t\t\t.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tfail(`write ${SnapshotLayout.integrityFile} failed: ${String(cause)}`),\n\t\t\t\t),\n\t\t\t);\n\t\treturn integrity;\n\t});\n\nconst readIntegrity = (root: string): Effect.Effect<IntegrityFile, Error, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst path = `${root}/${SnapshotLayout.integrityFile}`;\n\t\tconst text = yield* fs\n\t\t\t.readFileString(path)\n\t\t\t.pipe(Effect.catch((cause) => fail(`read ${path} failed: ${String(cause)}`)));\n\t\tconst raw = yield* Effect.try({\n\t\t\ttry: () => JSON.parse(text) as unknown,\n\t\t\tcatch: (cause) => new Error(`${path} is not valid JSON: ${String(cause)}`),\n\t\t});\n\t\tconst decoded = yield* Schema.decodeUnknownEffect(IntegrityFileSchema)(raw).pipe(\n\t\t\tEffect.catch((cause) => fail(`${path} failed schema decode: ${String(cause)}`)),\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* fail(`unsafe integrity path: ${relPath}`);\n\t\t\t}\n\t\t\tif (!SHA256_HEX.test(digest)) {\n\t\t\t\treturn yield* fail(`invalid sha256 digest for ${relPath}`);\n\t\t\t}\n\t\t}\n\t\treturn decoded;\n\t});\n\nexport const verifyArtifactIntegrity = (\n\troot: string,\n): Effect.Effect<void, Error, 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* fail('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* fail(`snapshot integrity mismatch for ${relPath}`);\n\t\t\t}\n\t\t}\n\t});\n"],"mappings":"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"}

package/dist/orchestrators/snapshot/prune.d.mts

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

package/dist/orchestrators/snapshot/prune.mjs

@@ -0,0 +1,110 @@
+import { SnapshotMetadataSchema } from "./descriptor.mjs";
+import { SNAPSHOTS_DIR_NAME } from "./wipe.mjs";
+import { Effect, FileSystem, Schema } from "effect";
+//#region src/orchestrators/snapshot/prune.ts
+var PrunePhaseError = class extends Schema.TaggedErrorClass()("SnapshotPrunePhaseError", {
+	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 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
+	}).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`).
+*
+* Also removes managed images via the runtime adapter's label-filtered
+* image cleanup.
+*/
+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 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}`;
+		const meta = yield* readMetaOpt(dir);
+		if (meta === null) {
+			yield* fs.remove(dir, {
+				recursive: true,
+				force: true
+			}).pipe(Effect.catch(failPhase("sweep-directories", `remove ${dir} failed`)));
+			reaped.push({
+				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`)));
+	return {
+		inspected: ids.length,
+		reaped,
+		imagesSwept
+	};
+}).pipe(Effect.withSpan("orchestrator.snapshot.prune"));
+//#endregion
+export { runPrune };
+
+//# sourceMappingURL=prune.mjs.map