@mysten-incubation/devstack 0.0.0

package/dist/orchestrators/snapshot/service.mjs

@@ -0,0 +1,296 @@
+import { IdentityContext, StackPathsService } from "../../substrate/runtime/paths.mjs";
+import { ownHolder } from "../../substrate/runtime/cross-process/liveness.mjs";
+import { acquireStackLock } from "../../substrate/runtime/cross-process/stack-lock.mjs";
+import { ContainerRuntimeService } from "../../runtime/docker/service.mjs";
+import { acquireReservation } from "../../substrate/runtime/cross-process/snapshot-reservation.mjs";
+import { SNAPSHOT_ID_RULE, SnapshotLayout, SnapshotMetadataSchema, parseSnapshotId } from "./descriptor.mjs";
+import { runCapture } from "./capture.mjs";
+import { runWipe } from "./wipe.mjs";
+import { runPrune } from "./prune.mjs";
+import { stageAndSwap } from "../../substrate/runtime/stage-and-swap/index.mjs";
+import { runRestore } from "./restore.mjs";
+import { Context, Effect, FileSystem, Layer, Ref, Schema } from "effect";
+import { randomUUID } from "node:crypto";
+Schema.TaggedErrorClass()("SnapshotBootError", { detail: Schema.String });
+var SnapshotIdError = class extends Schema.TaggedErrorClass()("SnapshotIdError", {
+	operation: Schema.Literals([
+		"capture",
+		"restore",
+		"delete"
+	]),
+	field: Schema.Literals(["id", "name"]),
+	value: Schema.String,
+	detail: Schema.String
+}) {};
+var SnapshotOrchestratorService = class extends Context.Service()("@devstack-rewrite/orchestrators/Snapshot") {};
+/** Mint a snapshot id when the caller didn't pass one. Carries an
+*  8-hex random suffix from `crypto.randomUUID()` (STYLE_GUIDE §17) so
+*  concurrent saves don't silently overwrite. */
+const mintId = (prefix = "snap") => `${prefix}-${Date.now()}-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
+const mintSnapshotId = () => {
+	const id = parseSnapshotId(mintId());
+	if (id === null) throw new Error("internal snapshot id minting produced an invalid id");
+	return id;
+};
+const mintSnapshotName = () => {
+	return `manual-${(/* @__PURE__ */ new Date()).toISOString().replaceAll("-", "").replaceAll(":", "").slice(0, 15)}-${randomUUID().replace(/-/g, "").slice(0, 4)}`;
+};
+const validateSnapshotId = (operation, value) => {
+	const id = parseSnapshotId(value);
+	return id === null ? Effect.fail(new SnapshotIdError({
+		operation,
+		field: "id",
+		value,
+		detail: SNAPSHOT_ID_RULE
+	})) : Effect.succeed(id);
+};
+const normalizeSnapshotName = (operation, name) => {
+	if (name === void 0) return Effect.succeed(mintSnapshotName());
+	const normalized = name.trim();
+	if (normalized.length === 0 || normalized.includes("\0") || normalized.length > 128) return Effect.fail(new SnapshotIdError({
+		operation,
+		field: "name",
+		value: name,
+		detail: "snapshot names must be 1-128 characters after trimming and cannot contain NUL bytes"
+	}));
+	return Effect.succeed(normalized);
+};
+/** Read this process's canonical startTime stamp for the snapshot
+*  reservation liveness check. */
+const ownStartTime = () => ownHolder("snapshot").startTime;
+const normalizeIdentityValue = (value) => {
+	if (Array.isArray(value)) return value.map(normalizeIdentityValue);
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, nested]) => [key, normalizeIdentityValue(nested)]));
+	return value;
+};
+const stableIdentityString = (value) => {
+	return JSON.stringify(normalizeIdentityValue(value)) ?? String(value);
+};
+const identityHookFromDecl = (pluginKey, decl) => decl.preRestore === void 0 ? Effect.succeed({}) : decl.preRestore.pipe(Effect.map((value) => ({ [pluginKey]: stableIdentityString(value) })));
+const layerSnapshotOrchestrator = Layer.effect(SnapshotOrchestratorService, Effect.gen(function* () {
+	const paths = yield* StackPathsService;
+	const identity = yield* IdentityContext;
+	const runtime = yield* ContainerRuntimeService;
+	const participantsRef = yield* Ref.make([]);
+	const classifiersRef = yield* Ref.make([]);
+	const seqRef = yield* Ref.make(0);
+	const registerParticipant = (pluginKey, decl, hooks) => Effect.gen(function* () {
+		const seq = yield* Ref.updateAndGet(seqRef, (n) => n + 1);
+		const declIdentity = identityHookFromDecl(pluginKey, decl);
+		const entry = {
+			pluginKey,
+			capture: {
+				plugin: pluginKey,
+				decl,
+				captureIdentity: hooks?.captureIdentity ?? declIdentity,
+				captureContribution: hooks?.captureContribution ?? Effect.succeed(void 0)
+			},
+			restore: {
+				plugin: pluginKey,
+				liveIdentity: hooks?.liveIdentity ?? declIdentity,
+				postRestore: decl.postRestore
+			},
+			seq
+		};
+		yield* Ref.update(participantsRef, (xs) => [...xs, entry]);
+		yield* Effect.addFinalizer(() => Ref.update(participantsRef, (xs) => xs.filter((e) => e.seq !== seq)));
+		yield* Effect.annotateCurrentSpan({
+			"snapshot.participant.plugin": pluginKey,
+			"snapshot.participant.subtrees": decl.subtrees.length
+		});
+	}).pipe(Effect.withSpan("orchestrator.snapshot.registerParticipant"));
+	const registerClassifier = (pluginKey, decl) => Effect.gen(function* () {
+		const seq = yield* Ref.updateAndGet(seqRef, (n) => n + 1);
+		const entry = {
+			dispatch: {
+				plugin: pluginKey,
+				decl
+			},
+			seq
+		};
+		yield* Ref.update(classifiersRef, (xs) => [...xs, entry]);
+		yield* Effect.addFinalizer(() => Ref.update(classifiersRef, (xs) => xs.filter((e) => e.seq !== seq)));
+		yield* Effect.annotateCurrentSpan({ "snapshot.classifier.plugin": pluginKey });
+	}).pipe(Effect.withSpan("orchestrator.snapshot.registerClassifier"));
+	const capture = ({ id, label, participants, onProgress }) => Effect.gen(function* () {
+		const snapshotId = id === void 0 ? mintSnapshotId() : yield* validateSnapshotId("capture", id);
+		const snapshotName = yield* normalizeSnapshotName("capture", label);
+		const effectiveParticipants = participants ?? (yield* Ref.get(participantsRef)).map((e) => e.capture);
+		const artifactDir = `${paths.snapshotDir}/${snapshotId}`;
+		const stagingDir = `${paths.snapshotDir}/.staging.${snapshotId}`;
+		const backupDir = `${paths.snapshotDir}/.bak.${snapshotId}`;
+		return yield* Effect.scoped(Effect.gen(function* () {
+			yield* acquireReservation(paths.snapshotReservationFile, ownStartTime());
+			if (yield* (yield* FileSystem.FileSystem).exists(artifactDir).pipe(Effect.catch(() => Effect.succeed(false)))) return yield* Effect.fail(new SnapshotIdError({
+				operation: "capture",
+				field: "id",
+				value: snapshotId,
+				detail: "snapshot id already exists"
+			}));
+			if ((yield* list).some((entry) => entry.metadata?.label === snapshotName)) return yield* Effect.fail(new SnapshotIdError({
+				operation: "capture",
+				field: "name",
+				value: snapshotName,
+				detail: "snapshot name already exists"
+			}));
+			return yield* stageAndSwap({
+				targetPath: artifactDir,
+				stagingPath: stagingDir,
+				backupPath: backupDir,
+				build: runCapture({
+					stagingDir,
+					snapshotId,
+					label: snapshotName,
+					app: identity.app,
+					stack: identity.stack,
+					network: identity.chain,
+					runtimeStackRoot: paths.stackRoot,
+					stateFilePath: paths.stateFile,
+					participants: effectiveParticipants,
+					runtime,
+					onProgress
+				})
+			});
+		}));
+	}).pipe(Effect.withSpan("orchestrator.snapshot.capture.entry"));
+	const restore = ({ id, participants }) => Effect.gen(function* () {
+		const snapshotId = yield* validateSnapshotId("restore", id);
+		const artifactDir = `${paths.snapshotDir}/${snapshotId}`;
+		const effectiveParticipants = participants ?? (yield* Ref.get(participantsRef)).map((e) => e.restore);
+		return yield* Effect.scoped(Effect.gen(function* () {
+			yield* acquireReservation(paths.snapshotReservationFile, ownStartTime());
+			return yield* runRestore({
+				snapshotId,
+				artifactDir,
+				runtimeStackRoot: paths.stackRoot,
+				runtimeStagingPath: `${paths.stackRoot}.staging.${snapshotId}`,
+				runtimeBackupPath: `${paths.stackRoot}.bak.${snapshotId}`,
+				participants: effectiveParticipants,
+				runtime,
+				runtimeIdentity: {
+					app: identity.app,
+					stack: identity.stack,
+					network: identity.chain
+				}
+			});
+		}));
+	}).pipe(Effect.withSpan("orchestrator.snapshot.restore.entry"));
+	const list = Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		if (!(yield* fs.exists(paths.snapshotDir).pipe(Effect.catch(() => Effect.succeed(false))))) return [];
+		const ids = yield* fs.readDirectory(paths.snapshotDir).pipe(Effect.catch(() => Effect.succeed([])));
+		const entries = [];
+		for (const id of ids) {
+			if (id.startsWith(".staging.") || id.startsWith(".bak.")) continue;
+			const parsedId = parseSnapshotId(id);
+			if (parsedId === null) {
+				yield* Effect.logWarning(`ignoring unsafe snapshot catalog entry: ${id}`);
+				continue;
+			}
+			const dir = `${paths.snapshotDir}/${id}`;
+			const metaPath = `${dir}/${SnapshotLayout.metaFile}`;
+			if (!(yield* fs.exists(metaPath).pipe(Effect.catch(() => Effect.succeed(false))))) {
+				entries.push({
+					id,
+					directory: dir,
+					metadata: null
+				});
+				continue;
+			}
+			const text = yield* fs.readFileString(metaPath).pipe(Effect.catch(() => Effect.succeed("")));
+			if (text === "") {
+				entries.push({
+					id,
+					directory: dir,
+					metadata: null
+				});
+				continue;
+			}
+			const raw = yield* Effect.try({
+				try: () => JSON.parse(text),
+				catch: () => null
+			}).pipe(Effect.catch(() => Effect.succeed(null)));
+			if (raw === null) {
+				entries.push({
+					id,
+					directory: dir,
+					metadata: null
+				});
+				continue;
+			}
+			const decoded = yield* Schema.decodeUnknownEffect(SnapshotMetadataSchema)(raw).pipe(Effect.catch(() => Effect.succeed(null)));
+			if (decoded !== null && parseSnapshotId(decoded.id) === null) {
+				yield* Effect.logWarning(`ignoring snapshot metadata with unsafe id: ${decoded.id}`);
+				entries.push({
+					id,
+					directory: dir,
+					metadata: null
+				});
+				continue;
+			}
+			entries.push({
+				id: parsedId,
+				directory: dir,
+				metadata: decoded
+			});
+		}
+		return entries;
+	}).pipe(Effect.withSpan("orchestrator.snapshot.list"));
+	const del = (id) => Effect.gen(function* () {
+		const snapshotId = yield* validateSnapshotId("delete", id);
+		const fs = yield* FileSystem.FileSystem;
+		const dir = `${paths.snapshotDir}/${snapshotId}`;
+		yield* Effect.scoped(Effect.gen(function* () {
+			yield* acquireStackLock(paths.stackLockFile);
+			yield* fs.remove(dir, {
+				recursive: true,
+				force: true
+			}).pipe(Effect.ignore);
+		}));
+	}).pipe(Effect.withSpan("orchestrator.snapshot.delete"));
+	const wipe = (args) => Effect.gen(function* () {
+		yield* Effect.scoped(Effect.gen(function* () {
+			yield* acquireStackLock(paths.stackLockFile);
+			yield* runWipe({
+				labelMatch: {
+					app: identity.app,
+					stack: identity.stack
+				},
+				stackRoot: paths.stackRoot,
+				stateFilePath: paths.stateFile,
+				runtime,
+				keepSnapshots: args.keepSnapshots,
+				keepCache: args.keepCache
+			});
+		}));
+	}).pipe(Effect.withSpan("orchestrator.snapshot.wipe.entry"));
+	const prune = ({ classifiers }) => Effect.gen(function* () {
+		const effectiveClassifiers = classifiers ?? (yield* Ref.get(classifiersRef)).map((e) => e.dispatch);
+		return yield* Effect.scoped(Effect.gen(function* () {
+			yield* acquireReservation(paths.snapshotReservationFile, ownStartTime());
+			return yield* runPrune({
+				stackRoot: paths.stackRoot,
+				imageLabelFilter: {
+					app: identity.app,
+					stack: identity.stack
+				},
+				classifiers: effectiveClassifiers,
+				runtime
+			});
+		}));
+	}).pipe(Effect.withSpan("orchestrator.snapshot.prune.entry"));
+	return SnapshotOrchestratorService.of({
+		registerParticipant,
+		registerClassifier,
+		capture,
+		restore,
+		list,
+		delete: del,
+		wipe,
+		prune
+	});
+}));
+//#endregion
+export { SnapshotOrchestratorService, layerSnapshotOrchestrator };
+
+//# sourceMappingURL=service.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/service.ts"],"sourcesContent":["// Snapshot orchestrator service.\n//\n// Architecture § L3 § Snapshot orchestrator:\n//   \"Collects all `Snapshotable` decls, applies one capture-wide\n//   pause window for managed containers, tars host subtrees with mode\n//   round-trip, commits container writable layers, threads a typed metadata record\n//   (identity guard + per-participant slice), atomic stage-and-swap\n//   for restore, identity-guard fires before any destructive mutation.\"\n//\n// This file is the orchestrator's typed entry point — `capture`,\n// `restore`, `list`, `delete`, `wipe`, `prune` — wired to the\n// cross-process safety primitives (`snapshot.reservation`,\n// `stack.lock`) and the substrate path resolver.\n//\n// The service surface is name-blind. The two participant lists\n// (capture and restore) are populated by the substrate at boot from\n// the `Snapshotable` decls of registered plugins; service-specific\n// behavior never reaches this file. Registration is scope-bound: the\n// supervisor calls `registerParticipant(pluginKey, decl)` from inside\n// each plugin's scope so the registry entry is reaped on plugin\n// teardown.\n\nimport { randomUUID } from 'node:crypto';\n\nimport { Context, Effect, FileSystem, Layer, Ref, Schema, Scope } from 'effect';\n\nimport type { LivenessClassifierDecl } from '../../contracts/liveness-classifier.ts';\nimport type { SnapshotableDecl } from '../../contracts/snapshotable.ts';\nimport type { ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport { ContainerRuntimeService } from '../../runtime/docker/index.ts';\nimport { ownHolder } from '../../substrate/runtime/cross-process/liveness.ts';\nimport {\n\tacquireReservation,\n\ttype SnapshotReservationError,\n} from '../../substrate/runtime/cross-process/snapshot-reservation.ts';\nimport {\n\tacquireStackLock,\n\ttype StackLockError,\n} from '../../substrate/runtime/cross-process/stack-lock.ts';\nimport { IdentityContext, StackPathsService } from '../../substrate/runtime/paths.ts';\nimport {\n\trunCapture,\n\ttype CapturePhaseError,\n\ttype SnapshotParticipant,\n\ttype SnapshotProgressReporter,\n} from './capture.ts';\nimport {\n\tSnapshotLayout,\n\tSnapshotMetadataSchema,\n\tSNAPSHOT_ID_RULE,\n\tparseSnapshotId,\n\ttype SnapshotId,\n\ttype SnapshotCatalogEntry,\n\ttype SnapshotMetadata,\n} from './descriptor.ts';\nimport {\n\ttype IdentityContributionConflictError,\n\ttype IdentityGuardError,\n} from './identity-guard.ts';\nimport {\n\trunPrune,\n\ttype ClassifierDispatch,\n\ttype PruneResult,\n\ttype PrunePhaseError,\n} from './prune.ts';\nimport { runRestore, type RestoreParticipant, type RestorePhaseError } from './restore.ts';\nimport {\n\tstageAndSwap,\n\ttype StageAndSwapError,\n} from '../../substrate/runtime/stage-and-swap/index.ts';\nimport { runWipe, type WipePhaseError } from './wipe.ts';\n\n// -----------------------------------------------------------------------------\n// The service shape\n// -----------------------------------------------------------------------------\n\n/** Tagged union of every error the orchestrator surface can surface.\n *  Callers `catchTags` on the precise tags they care about. */\nexport type SnapshotOrchestratorError =\n\t| CapturePhaseError\n\t| RestorePhaseError\n\t| WipePhaseError\n\t| PrunePhaseError\n\t| IdentityGuardError\n\t| IdentityContributionConflictError\n\t| StageAndSwapError\n\t| SnapshotReservationError\n\t| StackLockError\n\t| SnapshotIdError;\n\n/** Tagged failure when the substrate's startTime probe could not be\n *  reduced to a number. */\nexport class SnapshotBootError extends Schema.TaggedErrorClass<SnapshotBootError>()(\n\t'SnapshotBootError',\n\t{\n\t\tdetail: Schema.String,\n\t},\n) {}\n\nexport class SnapshotIdError extends Schema.TaggedErrorClass<SnapshotIdError>()('SnapshotIdError', {\n\toperation: Schema.Literals(['capture', 'restore', 'delete']),\n\tfield: Schema.Literals(['id', 'name']),\n\tvalue: Schema.String,\n\tdetail: Schema.String,\n}) {}\n\nexport interface SnapshotOrchestrator {\n\t/** Register a `SnapshotableDecl` from a plugin. Scope-bound — when\n\t *  the caller's scope (the plugin's acquire scope) closes, the\n\t *  registration is reaped. The supervisor calls this once per\n\t *  `SnapshotableDecl` on each plugin's `capabilities` tuple.\n\t *\n\t *  `captureIdentity` / `captureContribution` are separately wired\n\t *  hooks (not on `SnapshotableDecl` itself) — they plumb through\n\t *  the plugin's resolved value. Identity is validated by the\n\t *  orchestrator; contribution payloads are persisted as opaque JSON\n\t *  that plugins must validate at their own boundary if they read it. */\n\treadonly registerParticipant: (\n\t\tpluginKey: string,\n\t\tdecl: SnapshotableDecl,\n\t\thooks?: {\n\t\t\treadonly captureIdentity?: Effect.Effect<Readonly<Record<string, string>>>;\n\t\t\treadonly captureContribution?: Effect.Effect<unknown>;\n\t\t\treadonly liveIdentity?: Effect.Effect<Readonly<Record<string, string>>>;\n\t\t},\n\t) => Effect.Effect<void, never, Scope.Scope>;\n\n\t/** Register a plugin-emitted `LivenessClassifier`. The decl is\n\t *  consumed by `prune()`. Scope-bound. */\n\treadonly registerClassifier: (\n\t\tpluginKey: string,\n\t\tdecl: LivenessClassifierDecl,\n\t) => Effect.Effect<void, never, Scope.Scope>;\n\n\t/** Capture a new snapshot. The id MAY be caller-supplied; if\n\t *  omitted, the substrate mints a random suffix to sidestep the\n\t *  concurrent-saves-against-same-id silent overwrite.\n\t *\n\t *  `participants` overrides the registered set — primarily for\n\t *  tests. Production callers omit it; the orchestrator reads the\n\t *  registered list. */\n\treadonly capture: (args: {\n\t\treadonly id?: string;\n\t\treadonly label?: string;\n\t\treadonly participants?: ReadonlyArray<SnapshotParticipant>;\n\t\treadonly onProgress?: SnapshotProgressReporter;\n\t}) => Effect.Effect<SnapshotMetadata, SnapshotOrchestratorError, FileSystem.FileSystem>;\n\n\t/** Restore from a previously-captured artifact id. Refuses on\n\t *  identity mismatch BEFORE any destructive mutation. */\n\treadonly restore: (args: {\n\t\treadonly id: string;\n\t\treadonly participants?: ReadonlyArray<RestoreParticipant>;\n\t}) => Effect.Effect<SnapshotMetadata, SnapshotOrchestratorError, FileSystem.FileSystem>;\n\n\t/** Catalog list — tolerates partial / corrupt entries (they appear\n\t *  with `metadata: null`). */\n\treadonly list: Effect.Effect<\n\t\tReadonlyArray<SnapshotCatalogEntry>,\n\t\tSnapshotOrchestratorError,\n\t\tFileSystem.FileSystem\n\t>;\n\n\t/** Delete one artifact by id. Idempotent — missing id is a no-op. */\n\treadonly delete: (\n\t\tid: string,\n\t) => Effect.Effect<void, SnapshotOrchestratorError, FileSystem.FileSystem>;\n\n\t/** Wipe the live (`app`, `stack`) footprint; preserves the\n\t *  snapshot catalog by default. Stack-local artifact cache is\n\t *  removed unless `keepCache` is explicitly true. */\n\treadonly wipe: (args: {\n\t\treadonly keepSnapshots?: boolean;\n\t\treadonly keepCache?: boolean;\n\t}) => Effect.Effect<void, SnapshotOrchestratorError, FileSystem.FileSystem>;\n\n\t/** Prune the snapshot catalog + byproduct images via plugin-\n\t *  contributed classifiers. `classifiers` overrides the registered\n\t *  set; omit to consume registered classifiers. */\n\treadonly prune: (args: {\n\t\treadonly classifiers?: ReadonlyArray<ClassifierDispatch>;\n\t}) => Effect.Effect<PruneResult, SnapshotOrchestratorError, FileSystem.FileSystem>;\n}\n\nexport class SnapshotOrchestratorService extends Context.Service<\n\tSnapshotOrchestratorService,\n\tSnapshotOrchestrator\n>()('@devstack-rewrite/orchestrators/Snapshot') {}\n\n// -----------------------------------------------------------------------------\n// Helpers\n// -----------------------------------------------------------------------------\n\n/** Mint a snapshot id when the caller didn't pass one. Carries an\n *  8-hex random suffix from `crypto.randomUUID()` (STYLE_GUIDE §17) so\n *  concurrent saves don't silently overwrite. */\nconst mintId = (prefix = 'snap'): string =>\n\t`${prefix}-${Date.now()}-${randomUUID().replace(/-/g, '').slice(0, 8)}`;\n\nconst mintSnapshotId = (): SnapshotId => {\n\tconst id = parseSnapshotId(mintId());\n\tif (id === null) {\n\t\tthrow new Error('internal snapshot id minting produced an invalid id');\n\t}\n\treturn id;\n};\n\nconst mintSnapshotName = (): string => {\n\tconst stamp = new Date().toISOString().replaceAll('-', '').replaceAll(':', '').slice(0, 15);\n\treturn `manual-${stamp}-${randomUUID().replace(/-/g, '').slice(0, 4)}`;\n};\n\nconst validateSnapshotId = (\n\toperation: SnapshotIdError['operation'],\n\tvalue: string,\n): Effect.Effect<SnapshotId, SnapshotIdError> => {\n\tconst id = parseSnapshotId(value);\n\treturn id === null\n\t\t? Effect.fail(\n\t\t\t\tnew SnapshotIdError({\n\t\t\t\t\toperation,\n\t\t\t\t\tfield: 'id',\n\t\t\t\t\tvalue,\n\t\t\t\t\tdetail: SNAPSHOT_ID_RULE,\n\t\t\t\t}),\n\t\t\t)\n\t\t: Effect.succeed(id);\n};\n\nconst normalizeSnapshotName = (\n\toperation: SnapshotIdError['operation'],\n\tname: string | undefined,\n): Effect.Effect<string, SnapshotIdError> => {\n\tif (name === undefined) return Effect.succeed(mintSnapshotName());\n\tconst normalized = name.trim();\n\tif (normalized.length === 0 || normalized.includes('\\0') || normalized.length > 128) {\n\t\treturn Effect.fail(\n\t\t\tnew SnapshotIdError({\n\t\t\t\toperation,\n\t\t\t\tfield: 'name',\n\t\t\t\tvalue: name,\n\t\t\t\tdetail:\n\t\t\t\t\t'snapshot names must be 1-128 characters after trimming and cannot contain NUL bytes',\n\t\t\t}),\n\t\t);\n\t}\n\treturn Effect.succeed(normalized);\n};\n\n/** Read this process's canonical startTime stamp for the snapshot\n *  reservation liveness check. */\nconst ownStartTime = (): number => ownHolder('snapshot').startTime;\n\nconst normalizeIdentityValue = (value: unknown): unknown => {\n\tif (Array.isArray(value)) return value.map(normalizeIdentityValue);\n\tif (value !== null && typeof value === 'object') {\n\t\treturn Object.fromEntries(\n\t\t\tObject.entries(value)\n\t\t\t\t.sort(([a], [b]) => a.localeCompare(b))\n\t\t\t\t.map(([key, nested]) => [key, normalizeIdentityValue(nested)]),\n\t\t);\n\t}\n\treturn value;\n};\n\nconst stableIdentityString = (value: unknown): string => {\n\tconst encoded = JSON.stringify(normalizeIdentityValue(value));\n\treturn encoded ?? String(value);\n};\n\nconst identityHookFromDecl = (\n\tpluginKey: string,\n\tdecl: SnapshotableDecl,\n): Effect.Effect<Readonly<Record<string, string>>> =>\n\tdecl.preRestore === undefined\n\t\t? Effect.succeed({})\n\t\t: decl.preRestore.pipe(Effect.map((value) => ({ [pluginKey]: stableIdentityString(value) })));\n\n// -----------------------------------------------------------------------------\n// Layer\n// -----------------------------------------------------------------------------\n\n/**\n * Wire the orchestrator from the substrate's path resolver + the\n * runtime container adapter.\n *\n * Discipline:\n *   - Capture/restore acquire `snapshot.reservation` (O_EXCL,\n *     no retry) — concurrent capture is structurally refused.\n *   - List/delete/wipe acquire `stack.lock` briefly (no reservation\n *     needed; they don't pause containers).\n *   - Prune acquires both — it walks the catalog AND sweeps images.\n */\n/** Per-plugin participant registration entry kept on the orchestrator's\n *  inner ref. Sequence number lets parallel registrations under the\n *  same key be reaped independently when their owning scopes close. */\ninterface RegisteredParticipantEntry {\n\treadonly pluginKey: string;\n\treadonly capture: SnapshotParticipant;\n\treadonly restore: RestoreParticipant;\n\treadonly seq: number;\n}\n\ninterface RegisteredClassifierEntry {\n\treadonly dispatch: ClassifierDispatch;\n\treadonly seq: number;\n}\n\nexport const layerSnapshotOrchestrator: Layer.Layer<\n\tSnapshotOrchestratorService,\n\tnever,\n\tStackPathsService | IdentityContext | ContainerRuntimeService\n> = Layer.effect(\n\tSnapshotOrchestratorService,\n\tEffect.gen(function* () {\n\t\tconst paths = yield* StackPathsService;\n\t\tconst identity = yield* IdentityContext;\n\t\tconst runtime: ContainerRuntime = yield* ContainerRuntimeService;\n\n\t\t// Scope-local participant + classifier registries. The supervisor\n\t\t// adds entries from each plugin's acquire scope; finalizers\n\t\t// remove them on scope close. Sequence number protects against\n\t\t// the parallel-registration-same-key race when two stack\n\t\t// instances register concurrently.\n\t\tconst participantsRef = yield* Ref.make<ReadonlyArray<RegisteredParticipantEntry>>([]);\n\t\tconst classifiersRef = yield* Ref.make<ReadonlyArray<RegisteredClassifierEntry>>([]);\n\t\tconst seqRef = yield* Ref.make(0);\n\n\t\tconst registerParticipant: SnapshotOrchestrator['registerParticipant'] = (\n\t\t\tpluginKey,\n\t\t\tdecl,\n\t\t\thooks,\n\t\t) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst seq = yield* Ref.updateAndGet(seqRef, (n) => n + 1);\n\t\t\t\tconst declIdentity = identityHookFromDecl(pluginKey, decl);\n\t\t\t\tconst capture: SnapshotParticipant = {\n\t\t\t\t\tplugin: pluginKey,\n\t\t\t\t\tdecl,\n\t\t\t\t\tcaptureIdentity: hooks?.captureIdentity ?? declIdentity,\n\t\t\t\t\tcaptureContribution: hooks?.captureContribution ?? Effect.succeed<unknown>(undefined),\n\t\t\t\t};\n\t\t\t\tconst restore: RestoreParticipant = {\n\t\t\t\t\tplugin: pluginKey,\n\t\t\t\t\tliveIdentity: hooks?.liveIdentity ?? declIdentity,\n\t\t\t\t\tpostRestore: decl.postRestore as Effect.Effect<void> | undefined,\n\t\t\t\t};\n\t\t\t\tconst entry: RegisteredParticipantEntry = { pluginKey, capture, restore, seq };\n\t\t\t\tyield* Ref.update(participantsRef, (xs) => [...xs, entry]);\n\t\t\t\tyield* Effect.addFinalizer(() =>\n\t\t\t\t\tRef.update(participantsRef, (xs) => xs.filter((e) => e.seq !== seq)),\n\t\t\t\t);\n\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t'snapshot.participant.plugin': pluginKey,\n\t\t\t\t\t'snapshot.participant.subtrees': decl.subtrees.length,\n\t\t\t\t});\n\t\t\t}).pipe(Effect.withSpan('orchestrator.snapshot.registerParticipant')) as Effect.Effect<\n\t\t\t\tvoid,\n\t\t\t\tnever,\n\t\t\t\tScope.Scope\n\t\t\t>;\n\n\t\tconst registerClassifier: SnapshotOrchestrator['registerClassifier'] = (pluginKey, decl) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst seq = yield* Ref.updateAndGet(seqRef, (n) => n + 1);\n\t\t\t\tconst dispatch: ClassifierDispatch = { plugin: pluginKey, decl };\n\t\t\t\tconst entry: RegisteredClassifierEntry = { dispatch, seq };\n\t\t\t\tyield* Ref.update(classifiersRef, (xs) => [...xs, entry]);\n\t\t\t\tyield* Effect.addFinalizer(() =>\n\t\t\t\t\tRef.update(classifiersRef, (xs) => xs.filter((e) => e.seq !== seq)),\n\t\t\t\t);\n\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t'snapshot.classifier.plugin': pluginKey,\n\t\t\t\t});\n\t\t\t}).pipe(Effect.withSpan('orchestrator.snapshot.registerClassifier')) as Effect.Effect<\n\t\t\t\tvoid,\n\t\t\t\tnever,\n\t\t\t\tScope.Scope\n\t\t\t>;\n\n\t\tconst capture: SnapshotOrchestrator['capture'] = ({ id, label, participants, onProgress }) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst snapshotId =\n\t\t\t\t\tid === undefined ? mintSnapshotId() : yield* validateSnapshotId('capture', id);\n\t\t\t\tconst snapshotName = yield* normalizeSnapshotName('capture', label);\n\t\t\t\tconst effectiveParticipants =\n\t\t\t\t\tparticipants ?? (yield* Ref.get(participantsRef)).map((e) => e.capture);\n\t\t\t\tconst artifactDir = `${paths.snapshotDir}/${snapshotId}`;\n\t\t\t\tconst stagingDir = `${paths.snapshotDir}/.staging.${snapshotId}`;\n\t\t\t\tconst backupDir = `${paths.snapshotDir}/.bak.${snapshotId}`;\n\n\t\t\t\t// Acquire `snapshot.reservation` (O_EXCL, no retry) for the\n\t\t\t\t// duration of the capture. The stack.lock is acquired\n\t\t\t\t// briefly inside `stageAndSwap` for the rename publish.\n\t\t\t\treturn yield* Effect.scoped(\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* acquireReservation(paths.snapshotReservationFile, ownStartTime());\n\t\t\t\t\t\tconst fs = yield* FileSystem.FileSystem;\n\t\t\t\t\t\tconst targetExists = yield* fs\n\t\t\t\t\t\t\t.exists(artifactDir)\n\t\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\t\t\t\tif (targetExists) {\n\t\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\t\tnew SnapshotIdError({\n\t\t\t\t\t\t\t\t\toperation: 'capture',\n\t\t\t\t\t\t\t\t\tfield: 'id',\n\t\t\t\t\t\t\t\t\tvalue: snapshotId,\n\t\t\t\t\t\t\t\t\tdetail: 'snapshot id already exists',\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst existing = yield* list;\n\t\t\t\t\t\tif (existing.some((entry) => entry.metadata?.label === snapshotName)) {\n\t\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\t\tnew SnapshotIdError({\n\t\t\t\t\t\t\t\t\toperation: 'capture',\n\t\t\t\t\t\t\t\t\tfield: 'name',\n\t\t\t\t\t\t\t\t\tvalue: snapshotName,\n\t\t\t\t\t\t\t\t\tdetail: 'snapshot name already exists',\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// Stage-and-swap publishes the artifact directory\n\t\t\t\t\t\t// atomically — external watchers (and `list`)\n\t\t\t\t\t\t// never observe a half-written tree.\n\t\t\t\t\t\tconst meta = yield* stageAndSwap({\n\t\t\t\t\t\t\ttargetPath: artifactDir,\n\t\t\t\t\t\t\tstagingPath: stagingDir,\n\t\t\t\t\t\t\tbackupPath: backupDir,\n\t\t\t\t\t\t\tbuild: runCapture({\n\t\t\t\t\t\t\t\tstagingDir,\n\t\t\t\t\t\t\t\tsnapshotId,\n\t\t\t\t\t\t\t\tlabel: snapshotName,\n\t\t\t\t\t\t\t\tapp: identity.app,\n\t\t\t\t\t\t\t\tstack: identity.stack,\n\t\t\t\t\t\t\t\tnetwork: identity.chain,\n\t\t\t\t\t\t\t\truntimeStackRoot: paths.stackRoot,\n\t\t\t\t\t\t\t\tstateFilePath: paths.stateFile,\n\t\t\t\t\t\t\t\tparticipants: effectiveParticipants,\n\t\t\t\t\t\t\t\truntime,\n\t\t\t\t\t\t\t\tonProgress,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t});\n\t\t\t\t\t\treturn meta;\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}).pipe(Effect.withSpan('orchestrator.snapshot.capture.entry'));\n\n\t\tconst restore: SnapshotOrchestrator['restore'] = ({ id, participants }) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst snapshotId = yield* validateSnapshotId('restore', id);\n\t\t\t\tconst artifactDir = `${paths.snapshotDir}/${snapshotId}`;\n\t\t\t\tconst effectiveParticipants =\n\t\t\t\t\tparticipants ?? (yield* Ref.get(participantsRef)).map((e) => e.restore);\n\t\t\t\treturn yield* Effect.scoped(\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* acquireReservation(paths.snapshotReservationFile, ownStartTime());\n\t\t\t\t\t\treturn yield* runRestore({\n\t\t\t\t\t\t\tsnapshotId,\n\t\t\t\t\t\t\tartifactDir,\n\t\t\t\t\t\t\truntimeStackRoot: paths.stackRoot,\n\t\t\t\t\t\t\truntimeStagingPath: `${paths.stackRoot}.staging.${snapshotId}`,\n\t\t\t\t\t\t\truntimeBackupPath: `${paths.stackRoot}.bak.${snapshotId}`,\n\t\t\t\t\t\t\tparticipants: effectiveParticipants,\n\t\t\t\t\t\t\truntime,\n\t\t\t\t\t\t\truntimeIdentity: {\n\t\t\t\t\t\t\t\tapp: identity.app,\n\t\t\t\t\t\t\t\tstack: identity.stack,\n\t\t\t\t\t\t\t\tnetwork: identity.chain,\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}).pipe(Effect.withSpan('orchestrator.snapshot.restore.entry'));\n\n\t\tconst list: SnapshotOrchestrator['list'] = Effect.gen(function* () {\n\t\t\tconst fs = yield* FileSystem.FileSystem;\n\t\t\tconst exists = yield* fs\n\t\t\t\t.exists(paths.snapshotDir)\n\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\tif (!exists) return [];\n\t\t\tconst ids = yield* fs\n\t\t\t\t.readDirectory(paths.snapshotDir)\n\t\t\t\t.pipe(Effect.catch(() => Effect.succeed([] as ReadonlyArray<string>)));\n\t\t\tconst entries: SnapshotCatalogEntry[] = [];\n\t\t\tfor (const id of ids) {\n\t\t\t\t// Skip transient staging/backup directories — they're\n\t\t\t\t// invisible to the catalog by construction (the\n\t\t\t\t// `.staging.<id>` / `.bak.<id>` naming).\n\t\t\t\tif (id.startsWith('.staging.') || id.startsWith('.bak.')) continue;\n\t\t\t\tconst parsedId = parseSnapshotId(id);\n\t\t\t\tif (parsedId === null) {\n\t\t\t\t\tyield* Effect.logWarning(`ignoring unsafe snapshot catalog entry: ${id}`);\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst dir = `${paths.snapshotDir}/${id}`;\n\t\t\t\tconst metaPath = `${dir}/${SnapshotLayout.metaFile}`;\n\t\t\t\tconst metaExists = yield* fs\n\t\t\t\t\t.exists(metaPath)\n\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\t\tif (!metaExists) {\n\t\t\t\t\tentries.push({ id, directory: dir, metadata: null });\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst text = yield* fs\n\t\t\t\t\t.readFileString(metaPath)\n\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed('')));\n\t\t\t\tif (text === '') {\n\t\t\t\t\tentries.push({ id, directory: dir, metadata: null });\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst raw = yield* Effect.try({\n\t\t\t\t\ttry: () => JSON.parse(text) as unknown,\n\t\t\t\t\tcatch: () => null,\n\t\t\t\t}).pipe(Effect.catch(() => Effect.succeed(null)));\n\t\t\t\tif (raw === null) {\n\t\t\t\t\tentries.push({ id, directory: dir, metadata: null });\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tconst decoded = yield* Schema.decodeUnknownEffect(SnapshotMetadataSchema)(raw).pipe(\n\t\t\t\t\tEffect.catch(() => Effect.succeed(null)),\n\t\t\t\t);\n\t\t\t\tif (decoded !== null && parseSnapshotId(decoded.id) === null) {\n\t\t\t\t\tyield* Effect.logWarning(`ignoring snapshot metadata with unsafe id: ${decoded.id}`);\n\t\t\t\t\tentries.push({ id, directory: dir, metadata: null });\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tentries.push({ id: parsedId, directory: dir, metadata: decoded });\n\t\t\t}\n\t\t\treturn entries;\n\t\t}).pipe(Effect.withSpan('orchestrator.snapshot.list'));\n\n\t\tconst del: SnapshotOrchestrator['delete'] = (id) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst snapshotId = yield* validateSnapshotId('delete', id);\n\t\t\t\tconst fs = yield* FileSystem.FileSystem;\n\t\t\t\tconst dir = `${paths.snapshotDir}/${snapshotId}`;\n\t\t\t\tyield* Effect.scoped(\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* acquireStackLock(paths.stackLockFile);\n\t\t\t\t\t\tyield* fs.remove(dir, { recursive: true, force: true }).pipe(Effect.ignore);\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}).pipe(Effect.withSpan('orchestrator.snapshot.delete'));\n\n\t\tconst wipe: SnapshotOrchestrator['wipe'] = (args) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tyield* Effect.scoped(\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* acquireStackLock(paths.stackLockFile);\n\t\t\t\t\t\tyield* runWipe({\n\t\t\t\t\t\t\tlabelMatch: { app: identity.app, stack: identity.stack },\n\t\t\t\t\t\t\tstackRoot: paths.stackRoot,\n\t\t\t\t\t\t\tstateFilePath: paths.stateFile,\n\t\t\t\t\t\t\truntime,\n\t\t\t\t\t\t\tkeepSnapshots: args.keepSnapshots,\n\t\t\t\t\t\t\tkeepCache: args.keepCache,\n\t\t\t\t\t\t});\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}).pipe(Effect.withSpan('orchestrator.snapshot.wipe.entry'));\n\n\t\tconst prune: SnapshotOrchestrator['prune'] = ({ classifiers }) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst effectiveClassifiers =\n\t\t\t\t\tclassifiers ?? (yield* Ref.get(classifiersRef)).map((e) => e.dispatch);\n\t\t\t\treturn yield* Effect.scoped(\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* acquireReservation(paths.snapshotReservationFile, ownStartTime());\n\t\t\t\t\t\treturn yield* runPrune({\n\t\t\t\t\t\t\tstackRoot: paths.stackRoot,\n\t\t\t\t\t\t\timageLabelFilter: { app: identity.app, stack: identity.stack },\n\t\t\t\t\t\t\tclassifiers: effectiveClassifiers,\n\t\t\t\t\t\t\truntime,\n\t\t\t\t\t\t});\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}).pipe(Effect.withSpan('orchestrator.snapshot.prune.entry'));\n\n\t\treturn SnapshotOrchestratorService.of({\n\t\t\tregisterParticipant,\n\t\t\tregisterClassifier,\n\t\t\tcapture,\n\t\t\trestore,\n\t\t\tlist,\n\t\t\tdelete: del,\n\t\t\twipe,\n\t\t\tprune,\n\t\t});\n\t}),\n);\n"],"mappings":";;;;;;;;;;;;;AA4FuC,OAAO,kBAAqC,CAClF,qBACA,EACC,QAAQ,OAAO,QACf,CACD;AAED,IAAa,kBAAb,cAAqC,OAAO,kBAAmC,CAAC,mBAAmB;CAClG,WAAW,OAAO,SAAS;EAAC;EAAW;EAAW;EAAS,CAAC;CAC5D,OAAO,OAAO,SAAS,CAAC,MAAM,OAAO,CAAC;CACtC,OAAO,OAAO;CACd,QAAQ,OAAO;CACf,CAAC,CAAC;AAgFH,IAAa,8BAAb,cAAiD,QAAQ,SAGtD,CAAC,2CAA2C,CAAC;;;;AAShD,MAAM,UAAU,SAAS,WACxB,GAAG,OAAO,GAAG,KAAK,KAAK,CAAC,GAAG,YAAY,CAAC,QAAQ,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE;AAEtE,MAAM,uBAAmC;CACxC,MAAM,KAAK,gBAAgB,QAAQ,CAAC;AACpC,KAAI,OAAO,KACV,OAAM,IAAI,MAAM,sDAAsD;AAEvE,QAAO;;AAGR,MAAM,yBAAiC;AAEtC,QAAO,2BADO,IAAI,MAAM,EAAC,aAAa,CAAC,WAAW,KAAK,GAAG,CAAC,WAAW,KAAK,GAAG,CAAC,MAAM,GAAG,GAClE,CAAC,GAAG,YAAY,CAAC,QAAQ,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE;;AAGrE,MAAM,sBACL,WACA,UACgD;CAChD,MAAM,KAAK,gBAAgB,MAAM;AACjC,QAAO,OAAO,OACX,OAAO,KACP,IAAI,gBAAgB;EACnB;EACA,OAAO;EACP;EACA,QAAQ;EACR,CAAC,CACF,GACA,OAAO,QAAQ,GAAG;;AAGtB,MAAM,yBACL,WACA,SAC4C;AAC5C,KAAI,SAAS,KAAA,EAAW,QAAO,OAAO,QAAQ,kBAAkB,CAAC;CACjE,MAAM,aAAa,KAAK,MAAM;AAC9B,KAAI,WAAW,WAAW,KAAK,WAAW,SAAS,KAAK,IAAI,WAAW,SAAS,IAC/E,QAAO,OAAO,KACb,IAAI,gBAAgB;EACnB;EACA,OAAO;EACP,OAAO;EACP,QACC;EACD,CAAC,CACF;AAEF,QAAO,OAAO,QAAQ,WAAW;;;;AAKlC,MAAM,qBAA6B,UAAU,WAAW,CAAC;AAEzD,MAAM,0BAA0B,UAA4B;AAC3D,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,MAAM,IAAI,uBAAuB;AAClE,KAAI,UAAU,QAAQ,OAAO,UAAU,SACtC,QAAO,OAAO,YACb,OAAO,QAAQ,MAAM,CACnB,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC,CACtC,KAAK,CAAC,KAAK,YAAY,CAAC,KAAK,uBAAuB,OAAO,CAAC,CAAC,CAC/D;AAEF,QAAO;;AAGR,MAAM,wBAAwB,UAA2B;AAExD,QADgB,KAAK,UAAU,uBAAuB,MAAM,CAC9C,IAAI,OAAO,MAAM;;AAGhC,MAAM,wBACL,WACA,SAEA,KAAK,eAAe,KAAA,IACjB,OAAO,QAAQ,EAAE,CAAC,GAClB,KAAK,WAAW,KAAK,OAAO,KAAK,WAAW,GAAG,YAAY,qBAAqB,MAAM,EAAE,EAAE,CAAC;AAgC/F,MAAa,4BAIT,MAAM,OACT,6BACA,OAAO,IAAI,aAAa;CACvB,MAAM,QAAQ,OAAO;CACrB,MAAM,WAAW,OAAO;CACxB,MAAM,UAA4B,OAAO;CAOzC,MAAM,kBAAkB,OAAO,IAAI,KAAgD,EAAE,CAAC;CACtF,MAAM,iBAAiB,OAAO,IAAI,KAA+C,EAAE,CAAC;CACpF,MAAM,SAAS,OAAO,IAAI,KAAK,EAAE;CAEjC,MAAM,uBACL,WACA,MACA,UAEA,OAAO,IAAI,aAAa;EACvB,MAAM,MAAM,OAAO,IAAI,aAAa,SAAS,MAAM,IAAI,EAAE;EACzD,MAAM,eAAe,qBAAqB,WAAW,KAAK;EAY1D,MAAM,QAAoC;GAAE;GAAW,SAAA;IAVtD,QAAQ;IACR;IACA,iBAAiB,OAAO,mBAAmB;IAC3C,qBAAqB,OAAO,uBAAuB,OAAO,QAAiB,KAAA,EAAU;IAOxB;GAAE,SAAA;IAJ/D,QAAQ;IACR,cAAc,OAAO,gBAAgB;IACrC,aAAa,KAAK;IAEoD;GAAE;GAAK;AAC9E,SAAO,IAAI,OAAO,kBAAkB,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC;AAC1D,SAAO,OAAO,mBACb,IAAI,OAAO,kBAAkB,OAAO,GAAG,QAAQ,MAAM,EAAE,QAAQ,IAAI,CAAC,CACpE;AACD,SAAO,OAAO,oBAAoB;GACjC,+BAA+B;GAC/B,iCAAiC,KAAK,SAAS;GAC/C,CAAC;GACD,CAAC,KAAK,OAAO,SAAS,4CAA4C,CAAC;CAMtE,MAAM,sBAAkE,WAAW,SAClF,OAAO,IAAI,aAAa;EACvB,MAAM,MAAM,OAAO,IAAI,aAAa,SAAS,MAAM,IAAI,EAAE;EAEzD,MAAM,QAAmC;GAAE,UAAA;IADJ,QAAQ;IAAW;IACP;GAAE;GAAK;AAC1D,SAAO,IAAI,OAAO,iBAAiB,OAAO,CAAC,GAAG,IAAI,MAAM,CAAC;AACzD,SAAO,OAAO,mBACb,IAAI,OAAO,iBAAiB,OAAO,GAAG,QAAQ,MAAM,EAAE,QAAQ,IAAI,CAAC,CACnE;AACD,SAAO,OAAO,oBAAoB,EACjC,8BAA8B,WAC9B,CAAC;GACD,CAAC,KAAK,OAAO,SAAS,2CAA2C,CAAC;CAMrE,MAAM,WAA4C,EAAE,IAAI,OAAO,cAAc,iBAC5E,OAAO,IAAI,aAAa;EACvB,MAAM,aACL,OAAO,KAAA,IAAY,gBAAgB,GAAG,OAAO,mBAAmB,WAAW,GAAG;EAC/E,MAAM,eAAe,OAAO,sBAAsB,WAAW,MAAM;EACnE,MAAM,wBACL,iBAAiB,OAAO,IAAI,IAAI,gBAAgB,EAAE,KAAK,MAAM,EAAE,QAAQ;EACxE,MAAM,cAAc,GAAG,MAAM,YAAY,GAAG;EAC5C,MAAM,aAAa,GAAG,MAAM,YAAY,YAAY;EACpD,MAAM,YAAY,GAAG,MAAM,YAAY,QAAQ;AAK/C,SAAO,OAAO,OAAO,OACpB,OAAO,IAAI,aAAa;AACvB,UAAO,mBAAmB,MAAM,yBAAyB,cAAc,CAAC;AAKxE,OAAI,QAHwB,OADV,WAAW,YAE3B,OAAO,YAAY,CACnB,KAAK,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,CAEhD,QAAO,OAAO,OAAO,KACpB,IAAI,gBAAgB;IACnB,WAAW;IACX,OAAO;IACP,OAAO;IACP,QAAQ;IACR,CAAC,CACF;AAGF,QAAI,OADoB,MACX,MAAM,UAAU,MAAM,UAAU,UAAU,aAAa,CACnE,QAAO,OAAO,OAAO,KACpB,IAAI,gBAAgB;IACnB,WAAW;IACX,OAAO;IACP,OAAO;IACP,QAAQ;IACR,CAAC,CACF;AAwBF,UAAO,OAlBa,aAAa;IAChC,YAAY;IACZ,aAAa;IACb,YAAY;IACZ,OAAO,WAAW;KACjB;KACA;KACA,OAAO;KACP,KAAK,SAAS;KACd,OAAO,SAAS;KAChB,SAAS,SAAS;KAClB,kBAAkB,MAAM;KACxB,eAAe,MAAM;KACrB,cAAc;KACd;KACA;KACA,CAAC;IACF,CAAC;IAED,CACF;GACA,CAAC,KAAK,OAAO,SAAS,sCAAsC,CAAC;CAEhE,MAAM,WAA4C,EAAE,IAAI,mBACvD,OAAO,IAAI,aAAa;EACvB,MAAM,aAAa,OAAO,mBAAmB,WAAW,GAAG;EAC3D,MAAM,cAAc,GAAG,MAAM,YAAY,GAAG;EAC5C,MAAM,wBACL,iBAAiB,OAAO,IAAI,IAAI,gBAAgB,EAAE,KAAK,MAAM,EAAE,QAAQ;AACxE,SAAO,OAAO,OAAO,OACpB,OAAO,IAAI,aAAa;AACvB,UAAO,mBAAmB,MAAM,yBAAyB,cAAc,CAAC;AACxE,UAAO,OAAO,WAAW;IACxB;IACA;IACA,kBAAkB,MAAM;IACxB,oBAAoB,GAAG,MAAM,UAAU,WAAW;IAClD,mBAAmB,GAAG,MAAM,UAAU,OAAO;IAC7C,cAAc;IACd;IACA,iBAAiB;KAChB,KAAK,SAAS;KACd,OAAO,SAAS;KAChB,SAAS,SAAS;KAClB;IACD,CAAC;IACD,CACF;GACA,CAAC,KAAK,OAAO,SAAS,sCAAsC,CAAC;CAEhE,MAAM,OAAqC,OAAO,IAAI,aAAa;EAClE,MAAM,KAAK,OAAO,WAAW;AAI7B,MAAI,EAAC,OAHiB,GACpB,OAAO,MAAM,YAAY,CACzB,KAAK,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,EACpC,QAAO,EAAE;EACtB,MAAM,MAAM,OAAO,GACjB,cAAc,MAAM,YAAY,CAChC,KAAK,OAAO,YAAY,OAAO,QAAQ,EAAE,CAA0B,CAAC,CAAC;EACvE,MAAM,UAAkC,EAAE;AAC1C,OAAK,MAAM,MAAM,KAAK;AAIrB,OAAI,GAAG,WAAW,YAAY,IAAI,GAAG,WAAW,QAAQ,CAAE;GAC1D,MAAM,WAAW,gBAAgB,GAAG;AACpC,OAAI,aAAa,MAAM;AACtB,WAAO,OAAO,WAAW,2CAA2C,KAAK;AACzE;;GAED,MAAM,MAAM,GAAG,MAAM,YAAY,GAAG;GACpC,MAAM,WAAW,GAAG,IAAI,GAAG,eAAe;AAI1C,OAAI,EAAC,OAHqB,GACxB,OAAO,SAAS,CAChB,KAAK,OAAO,YAAY,OAAO,QAAQ,MAAM,CAAC,CAAC,GAChC;AAChB,YAAQ,KAAK;KAAE;KAAI,WAAW;KAAK,UAAU;KAAM,CAAC;AACpD;;GAED,MAAM,OAAO,OAAO,GAClB,eAAe,SAAS,CACxB,KAAK,OAAO,YAAY,OAAO,QAAQ,GAAG,CAAC,CAAC;AAC9C,OAAI,SAAS,IAAI;AAChB,YAAQ,KAAK;KAAE;KAAI,WAAW;KAAK,UAAU;KAAM,CAAC;AACpD;;GAED,MAAM,MAAM,OAAO,OAAO,IAAI;IAC7B,WAAW,KAAK,MAAM,KAAK;IAC3B,aAAa;IACb,CAAC,CAAC,KAAK,OAAO,YAAY,OAAO,QAAQ,KAAK,CAAC,CAAC;AACjD,OAAI,QAAQ,MAAM;AACjB,YAAQ,KAAK;KAAE;KAAI,WAAW;KAAK,UAAU;KAAM,CAAC;AACpD;;GAED,MAAM,UAAU,OAAO,OAAO,oBAAoB,uBAAuB,CAAC,IAAI,CAAC,KAC9E,OAAO,YAAY,OAAO,QAAQ,KAAK,CAAC,CACxC;AACD,OAAI,YAAY,QAAQ,gBAAgB,QAAQ,GAAG,KAAK,MAAM;AAC7D,WAAO,OAAO,WAAW,8CAA8C,QAAQ,KAAK;AACpF,YAAQ,KAAK;KAAE;KAAI,WAAW;KAAK,UAAU;KAAM,CAAC;AACpD;;AAED,WAAQ,KAAK;IAAE,IAAI;IAAU,WAAW;IAAK,UAAU;IAAS,CAAC;;AAElE,SAAO;GACN,CAAC,KAAK,OAAO,SAAS,6BAA6B,CAAC;CAEtD,MAAM,OAAuC,OAC5C,OAAO,IAAI,aAAa;EACvB,MAAM,aAAa,OAAO,mBAAmB,UAAU,GAAG;EAC1D,MAAM,KAAK,OAAO,WAAW;EAC7B,MAAM,MAAM,GAAG,MAAM,YAAY,GAAG;AACpC,SAAO,OAAO,OACb,OAAO,IAAI,aAAa;AACvB,UAAO,iBAAiB,MAAM,cAAc;AAC5C,UAAO,GAAG,OAAO,KAAK;IAAE,WAAW;IAAM,OAAO;IAAM,CAAC,CAAC,KAAK,OAAO,OAAO;IAC1E,CACF;GACA,CAAC,KAAK,OAAO,SAAS,+BAA+B,CAAC;CAEzD,MAAM,QAAsC,SAC3C,OAAO,IAAI,aAAa;AACvB,SAAO,OAAO,OACb,OAAO,IAAI,aAAa;AACvB,UAAO,iBAAiB,MAAM,cAAc;AAC5C,UAAO,QAAQ;IACd,YAAY;KAAE,KAAK,SAAS;KAAK,OAAO,SAAS;KAAO;IACxD,WAAW,MAAM;IACjB,eAAe,MAAM;IACrB;IACA,eAAe,KAAK;IACpB,WAAW,KAAK;IAChB,CAAC;IACD,CACF;GACA,CAAC,KAAK,OAAO,SAAS,mCAAmC,CAAC;CAE7D,MAAM,SAAwC,EAAE,kBAC/C,OAAO,IAAI,aAAa;EACvB,MAAM,uBACL,gBAAgB,OAAO,IAAI,IAAI,eAAe,EAAE,KAAK,MAAM,EAAE,SAAS;AACvE,SAAO,OAAO,OAAO,OACpB,OAAO,IAAI,aAAa;AACvB,UAAO,mBAAmB,MAAM,yBAAyB,cAAc,CAAC;AACxE,UAAO,OAAO,SAAS;IACtB,WAAW,MAAM;IACjB,kBAAkB;KAAE,KAAK,SAAS;KAAK,OAAO,SAAS;KAAO;IAC9D,aAAa;IACb;IACA,CAAC;IACD,CACF;GACA,CAAC,KAAK,OAAO,SAAS,oCAAoC,CAAC;AAE9D,QAAO,4BAA4B,GAAG;EACrC;EACA;EACA;EACA;EACA;EACA,QAAQ;EACR;EACA;EACA,CAAC;EACD,CACF"}

package/dist/orchestrators/snapshot/state-document.mjs

@@ -0,0 +1,18 @@
+import { StateDocument } from "../../substrate/runtime/state-store/schema.mjs";
+import { Effect, FileSystem, Schema } from "effect";
+//#region src/orchestrators/snapshot/state-document.ts
+const readSnapshotStateDocument = (path) => Effect.gen(function* () {
+	const text = yield* (yield* FileSystem.FileSystem).readFileString(path).pipe(Effect.catch((cause) => Effect.fail(new Error(`read ${path} failed`, { cause }))));
+	const raw = yield* Effect.try({
+		try: () => JSON.parse(text),
+		catch: (cause) => new Error(`${path} is not valid JSON`, { cause })
+	});
+	return yield* Schema.decodeUnknownEffect(StateDocument)(raw).pipe(Effect.catch((cause) => Effect.fail(new Error(`${path} failed StateDocument schema decode`, { cause }))));
+});
+const writeSnapshotStateDocument = (path, doc) => Effect.gen(function* () {
+	yield* (yield* FileSystem.FileSystem).writeFileString(path, `${JSON.stringify(doc, null, 2)}\n`).pipe(Effect.catch((cause) => Effect.fail(new Error(`write ${path} failed`, { cause }))));
+});
+//#endregion
+export { readSnapshotStateDocument, writeSnapshotStateDocument };
+
+//# sourceMappingURL=state-document.mjs.map

package/dist/orchestrators/snapshot/state-document.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-document.mjs","names":["StateDocumentSchema"],"sources":["../../../src/orchestrators/snapshot/state-document.ts"],"sourcesContent":["import { Effect, FileSystem, Schema } from 'effect';\n\nimport {\n\tStateDocument as StateDocumentSchema,\n\ttype StateDocument,\n} from '../../substrate/runtime/state-store/index.ts';\n\nexport const readSnapshotStateDocument = (\n\tpath: string,\n): Effect.Effect<StateDocument, Error, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst text = yield* fs\n\t\t\t.readFileString(path)\n\t\t\t.pipe(Effect.catch((cause) => Effect.fail(new Error(`read ${path} failed`, { 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`, { cause }),\n\t\t});\n\t\treturn yield* Schema.decodeUnknownEffect(StateDocumentSchema)(raw).pipe(\n\t\t\tEffect.catch((cause) =>\n\t\t\t\tEffect.fail(new Error(`${path} failed StateDocument schema decode`, { cause })),\n\t\t\t),\n\t\t);\n\t});\n\nexport const writeSnapshotStateDocument = (\n\tpath: string,\n\tdoc: StateDocument,\n): Effect.Effect<void, Error, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tyield* fs\n\t\t\t.writeFileString(path, `${JSON.stringify(doc, null, 2)}\\n`)\n\t\t\t.pipe(Effect.catch((cause) => Effect.fail(new Error(`write ${path} failed`, { cause }))));\n\t});\n"],"mappings":";;;AAOA,MAAa,6BACZ,SAEA,OAAO,IAAI,aAAa;CAEvB,MAAM,OAAO,QAAO,OADF,WAAW,YAE3B,eAAe,KAAK,CACpB,KAAK,OAAO,OAAO,UAAU,OAAO,KAAK,IAAI,MAAM,QAAQ,KAAK,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACzF,MAAM,MAAM,OAAO,OAAO,IAAI;EAC7B,WAAW,KAAK,MAAM,KAAK;EAC3B,QAAQ,UAAU,IAAI,MAAM,GAAG,KAAK,qBAAqB,EAAE,OAAO,CAAC;EACnE,CAAC;AACF,QAAO,OAAO,OAAO,oBAAoBA,cAAoB,CAAC,IAAI,CAAC,KAClE,OAAO,OAAO,UACb,OAAO,KAAK,IAAI,MAAM,GAAG,KAAK,sCAAsC,EAAE,OAAO,CAAC,CAAC,CAC/E,CACD;EACA;AAEH,MAAa,8BACZ,MACA,QAEA,OAAO,IAAI,aAAa;AAEvB,SAAO,OADW,WAAW,YAE3B,gBAAgB,MAAM,GAAG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC,IAAI,CAC1D,KAAK,OAAO,OAAO,UAAU,OAAO,KAAK,IAAI,MAAM,SAAS,KAAK,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;EACzF"}

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

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

package/dist/orchestrators/snapshot/wipe.mjs

@@ -0,0 +1,59 @@
+import { Effect, FileSystem, Schema } from "effect";
+//#region src/orchestrators/snapshot/wipe.ts
+var WipePhaseError = class extends Schema.TaggedErrorClass()("SnapshotWipePhaseError", {
+	phase: Schema.Literals([
+		"sweep-containers",
+		"sweep-networks-volumes",
+		"remove-state",
+		"remove-runtime-tree"
+	]),
+	detail: Schema.String,
+	cause: Schema.optional(Schema.Defect)
+}) {};
+const failPhase = (phase, detail) => (cause) => Effect.fail(new WipePhaseError({
+	phase,
+	detail,
+	cause
+}));
+/**
+* Tear down a stack's live footprint. Snapshots survive by default
+* (architecture § wipe).
+*
+* Order:
+*   1. Force-remove managed containers by `{ app, stack }` labels.
+*   2. Remove managed networks and volumes by the same label filter.
+*   3. Remove state.json.
+*   4. Remove the runtime tree EXCEPT the snapshot catalog by default.
+*/
+const runWipe = (inputs) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	yield* Effect.annotateCurrentSpan({
+		"devstack.snapshot.phase": "wipe",
+		"devstack.app": inputs.labelMatch.app,
+		"devstack.stack": inputs.labelMatch.stack
+	});
+	yield* inputs.runtime.removeManagedContainers(inputs.labelMatch).pipe(Effect.catch(failPhase("sweep-containers", `container sweep failed`)));
+	yield* inputs.runtime.removeManagedNetworks(inputs.labelMatch).pipe(Effect.catch(failPhase("sweep-networks-volumes", `network sweep failed`)));
+	yield* inputs.runtime.removeManagedVolumes(inputs.labelMatch).pipe(Effect.catch(failPhase("sweep-networks-volumes", `volume sweep failed`)));
+	yield* fs.remove(inputs.stateFilePath, { force: true }).pipe(Effect.catch(failPhase("remove-state", `remove state.json failed`)));
+	const children = yield* fs.readDirectory(inputs.stackRoot).pipe(Effect.catch(() => Effect.succeed([])));
+	const keepSnapshots = inputs.keepSnapshots ?? true;
+	const keepCache = inputs.keepCache ?? false;
+	for (const name of children) {
+		if (keepSnapshots && name === "snapshots") continue;
+		if (keepCache && name === "cache") continue;
+		yield* fs.remove(`${inputs.stackRoot}/${name}`, {
+			recursive: true,
+			force: true
+		}).pipe(Effect.catch(failPhase("remove-runtime-tree", `remove ${name} failed`)));
+	}
+}).pipe(Effect.withSpan("orchestrator.snapshot.wipe"));
+/** Centralized constant — the canonical snapshot-catalog directory
+*  name. Used by both `runWipe` (to preserve) and the substrate's
+*  path resolver (to compose `snapshotDir`). Distilled §17 calls out
+*  the "centralize the snapshots-dir-name constant" opportunity. */
+const SNAPSHOTS_DIR_NAME = "snapshots";
+//#endregion
+export { SNAPSHOTS_DIR_NAME, runWipe };
+
+//# sourceMappingURL=wipe.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wipe.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/wipe.ts"],"sourcesContent":["// Wipe — label-scoped teardown.\n//\n// Architecture § Snapshot responsibilities:\n//   \"Provide a wipe operation scoped to one `(app, stack)` that tears\n//   down containers, networks, volumes, and per-stack on-disk state,\n//   with snapshots surviving by default.\"\n//\n// Label-scoped: enumeration uses partial `ContainerLabelTuple` filters\n// (just `{ app, stack }`); the orchestrator does NOT reach for plugin\n// names. The runtime adapter sweeps containers/networks/volumes\n// matching the label set.\n\nimport { Effect, FileSystem, Schema } from 'effect';\n\nimport type { ContainerLabelTuple } from '../../contracts/snapshotable.ts';\nimport type { ContainerRuntime } from '../../contracts/container-runtime.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\nexport class WipePhaseError extends Schema.TaggedErrorClass<WipePhaseError>()(\n\t'SnapshotWipePhaseError',\n\t{\n\t\tphase: Schema.Literals([\n\t\t\t'sweep-containers',\n\t\t\t'sweep-networks-volumes',\n\t\t\t'remove-state',\n\t\t\t'remove-runtime-tree',\n\t\t]),\n\t\tdetail: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\nconst failPhase =\n\t(\n\t\tphase: WipePhaseError['phase'],\n\t\tdetail: string,\n\t): ((cause: unknown) => Effect.Effect<never, WipePhaseError>) =>\n\t(cause) =>\n\t\tEffect.fail(new WipePhaseError({ phase, detail, cause }));\n\n// -----------------------------------------------------------------------------\n// Inputs\n// -----------------------------------------------------------------------------\n\nexport interface WipeInputs {\n\treadonly labelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>;\n\treadonly stackRoot: string;\n\treadonly stateFilePath: string;\n\treadonly runtime: ContainerRuntime;\n\t/** Preserve the snapshot catalog (default behavior). When false,\n\t *  the catalog is removed alongside the runtime tree. */\n\treadonly keepSnapshots?: boolean;\n\t/** Preserve stack-local artifact caches. Defaults to false; wipe\n\t *  should force on-chain artifacts to re-prove against the next\n\t *  chain instead of carrying local ids across a reset. */\n\treadonly keepCache?: boolean;\n}\n\n// -----------------------------------------------------------------------------\n// Wipe\n// -----------------------------------------------------------------------------\n\n/**\n * Tear down a stack's live footprint. Snapshots survive by default\n * (architecture § wipe).\n *\n * Order:\n *   1. Force-remove managed containers by `{ app, stack }` labels.\n *   2. Remove managed networks and volumes by the same label filter.\n *   3. Remove state.json.\n *   4. Remove the runtime tree EXCEPT the snapshot catalog by default.\n */\nexport const runWipe = (\n\tinputs: WipeInputs,\n): Effect.Effect<void, WipePhaseError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.snapshot.phase': 'wipe',\n\t\t\t'devstack.app': inputs.labelMatch.app,\n\t\t\t'devstack.stack': inputs.labelMatch.stack,\n\t\t});\n\n\t\t// 1. Containers.\n\t\tyield* inputs.runtime\n\t\t\t.removeManagedContainers(inputs.labelMatch)\n\t\t\t.pipe(Effect.catch(failPhase('sweep-containers', `container sweep failed`)));\n\n\t\t// 2. Networks + volumes.\n\t\tyield* inputs.runtime\n\t\t\t.removeManagedNetworks(inputs.labelMatch)\n\t\t\t.pipe(Effect.catch(failPhase('sweep-networks-volumes', `network sweep failed`)));\n\t\tyield* inputs.runtime\n\t\t\t.removeManagedVolumes(inputs.labelMatch)\n\t\t\t.pipe(Effect.catch(failPhase('sweep-networks-volumes', `volume sweep failed`)));\n\n\t\t// 3. Remove state.json.\n\t\tyield* fs\n\t\t\t.remove(inputs.stateFilePath, { force: true })\n\t\t\t.pipe(Effect.catch(failPhase('remove-state', `remove state.json failed`)));\n\n\t\t// 4. Remove the runtime tree — but PRESERVE snapshots by default.\n\t\t//    Strategy: enumerate the stack root and remove each child\n\t\t//    whose name is not `snapshots/` (when preserved). Stack-local\n\t\t//    artifact caches are state and are removed unless explicitly\n\t\t//    requested otherwise.\n\t\tconst children = yield* fs\n\t\t\t.readDirectory(inputs.stackRoot)\n\t\t\t.pipe(Effect.catch(() => Effect.succeed([] as ReadonlyArray<string>)));\n\t\tconst keepSnapshots = inputs.keepSnapshots ?? true;\n\t\tconst keepCache = inputs.keepCache ?? false;\n\t\tfor (const name of children) {\n\t\t\tif (keepSnapshots && name === 'snapshots') continue;\n\t\t\tif (keepCache && name === 'cache') continue;\n\t\t\tyield* fs\n\t\t\t\t.remove(`${inputs.stackRoot}/${name}`, { recursive: true, force: true })\n\t\t\t\t.pipe(Effect.catch(failPhase('remove-runtime-tree', `remove ${name} failed`)));\n\t\t}\n\t}).pipe(Effect.withSpan('orchestrator.snapshot.wipe'));\n\n/** Centralized constant — the canonical snapshot-catalog directory\n *  name. Used by both `runWipe` (to preserve) and the substrate's\n *  path resolver (to compose `snapshotDir`). Distilled §17 calls out\n *  the \"centralize the snapshots-dir-name constant\" opportunity. */\nexport const SNAPSHOTS_DIR_NAME = 'snapshots';\n"],"mappings":";;AAqBA,IAAa,iBAAb,cAAoC,OAAO,kBAAkC,CAC5E,0BACA;CACC,OAAO,OAAO,SAAS;EACtB;EACA;EACA;EACA;EACA,CAAC;CACF,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CACD,CAAC;AAEF,MAAM,aAEJ,OACA,YAEA,UACA,OAAO,KAAK,IAAI,eAAe;CAAE;CAAO;CAAQ;CAAO,CAAC,CAAC;;;;;;;;;;;AAkC3D,MAAa,WACZ,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;AAC7B,QAAO,OAAO,oBAAoB;EACjC,2BAA2B;EAC3B,gBAAgB,OAAO,WAAW;EAClC,kBAAkB,OAAO,WAAW;EACpC,CAAC;AAGF,QAAO,OAAO,QACZ,wBAAwB,OAAO,WAAW,CAC1C,KAAK,OAAO,MAAM,UAAU,oBAAoB,yBAAyB,CAAC,CAAC;AAG7E,QAAO,OAAO,QACZ,sBAAsB,OAAO,WAAW,CACxC,KAAK,OAAO,MAAM,UAAU,0BAA0B,uBAAuB,CAAC,CAAC;AACjF,QAAO,OAAO,QACZ,qBAAqB,OAAO,WAAW,CACvC,KAAK,OAAO,MAAM,UAAU,0BAA0B,sBAAsB,CAAC,CAAC;AAGhF,QAAO,GACL,OAAO,OAAO,eAAe,EAAE,OAAO,MAAM,CAAC,CAC7C,KAAK,OAAO,MAAM,UAAU,gBAAgB,2BAA2B,CAAC,CAAC;CAO3E,MAAM,WAAW,OAAO,GACtB,cAAc,OAAO,UAAU,CAC/B,KAAK,OAAO,YAAY,OAAO,QAAQ,EAAE,CAA0B,CAAC,CAAC;CACvE,MAAM,gBAAgB,OAAO,iBAAiB;CAC9C,MAAM,YAAY,OAAO,aAAa;AACtC,MAAK,MAAM,QAAQ,UAAU;AAC5B,MAAI,iBAAiB,SAAS,YAAa;AAC3C,MAAI,aAAa,SAAS,QAAS;AACnC,SAAO,GACL,OAAO,GAAG,OAAO,UAAU,GAAG,QAAQ;GAAE,WAAW;GAAM,OAAO;GAAM,CAAC,CACvE,KAAK,OAAO,MAAM,UAAU,uBAAuB,UAAU,KAAK,SAAS,CAAC,CAAC;;EAE/E,CAAC,KAAK,OAAO,SAAS,6BAA6B,CAAC;;;;;AAMvD,MAAa,qBAAqB"}

package/dist/plugins/account/codegen.d.mts

@@ -0,0 +1,12 @@
+//#region src/plugins/account/codegen.d.ts
+/** The typed shape the emitted file exports. Per-account record keyed
+ *  by name. */
+interface AccountBindings {
+  readonly name: string;
+  readonly address: string;
+  readonly scheme: 'ed25519' | 'secp256k1' | 'secp256r1';
+  readonly source: 'real' | 'impersonate';
+}
+//#endregion
+export { AccountBindings };
+//# sourceMappingURL=codegen.d.mts.map

package/dist/plugins/account/codegen.mjs

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+//#region src/plugins/account/codegen.ts
+/** Construct the Codegenable contribution. One emit per account.
+*
+*  The emitter name is `account/${name}` (literal) so multiple
+*  accounts in a single stack get co-located but typed-distinct
+*  emissions; the codegen orchestrator can fold them into a single
+*  `accounts` namespace at staging time. */
+const makeAccountCodegen = (parts) => ({
+	kind: "codegenable",
+	emitterName: `account/${parts.name}`,
+	outputPath: `accounts/${parts.name}.ts`,
+	sensitive: false,
+	emit: (ctx) => Effect.sync(() => {
+		ctx.exportConst(parts.name, parts.resolved);
+		return ctx.done();
+	})
+});
+//#endregion
+export { makeAccountCodegen };
+
+//# sourceMappingURL=codegen.mjs.map

package/dist/plugins/account/codegen.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/account/codegen.ts"],"sourcesContent":["// Account plugin — Codegenable contribution.\n//\n// Architecture §6 + 12-account.md \"Cross-component references\":\n// Codegen emits a constant address map keyed by account name so\n// downstream code can `import { accounts } from '<staged>/accounts'`\n// and read `accounts.alice.address` at the type level.\n//\n// Distilled-doc tension (12-account.md \"publicKey caveat\"):\n// impersonation accounts have a zero-buffer publicKey — emitting it\n// into the codegen bindings would be a type-level lie. The emitted\n// shape below carries the `source` discriminator INSTEAD of\n// publicKey; consumers branch on `source: 'impersonate'` rather than\n// publicKey-truthiness.\n//\n// SAFETY: the codegen output never emits secret material. Only the\n// `name`, `address`, `scheme`, and `source` fields land on disk.\n// `sensitive: false` is correct because none of these are secret.\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\n/** The typed shape the emitted file exports. Per-account record keyed\n *  by name. */\nexport interface AccountBindings {\n\treadonly name: string;\n\treadonly address: string;\n\treadonly scheme: 'ed25519' | 'secp256k1' | 'secp256r1';\n\treadonly source: 'real' | 'impersonate';\n}\n\n/** Construct the Codegenable contribution. One emit per account.\n *\n *  The emitter name is `account/${name}` (literal) so multiple\n *  accounts in a single stack get co-located but typed-distinct\n *  emissions; the codegen orchestrator can fold them into a single\n *  `accounts` namespace at staging time. */\nexport const makeAccountCodegen = <Name extends string>(parts: {\n\treadonly name: Name;\n\treadonly resolved: AccountBindings;\n}): CodegenableDecl<`account/${Name}`> => ({\n\tkind: 'codegenable',\n\temitterName: `account/${parts.name}` as `account/${Name}`,\n\toutputPath: `accounts/${parts.name}.ts`,\n\tsensitive: false,\n\temit: (ctx) =>\n\t\tEffect.sync(() => {\n\t\t\tctx.exportConst(parts.name, parts.resolved);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n"],"mappings":";;;;;;;;AAqCA,MAAa,sBAA2C,WAGb;CAC1C,MAAM;CACN,aAAa,WAAW,MAAM;CAC9B,YAAY,YAAY,MAAM,KAAK;CACnC,WAAW;CACX,OAAO,QACN,OAAO,WAAW;AACjB,MAAI,YAAY,MAAM,MAAM,MAAM,SAAS;AAC3C,SAAO,IAAI,MAAM;GAChB;CACH"}

package/dist/plugins/account/errors.d.mts

@@ -0,0 +1,44 @@
+//#region src/plugins/account/errors.d.ts
+/** Phases for `AccountAcquireError`. Closed sum — adding a phase
+ *  requires editing this list AND the cause-walker's display table. */
+type AccountAcquirePhase = 'validate-name' | 'load-keystore' | 'read-env' | 'decode-inline' | 'bind-signer' | 'bind-impersonation-slot' | 'generate-keypair' | 'persist-keypair' | 'read-persisted-keypair' | 'restrict-permissions' | 'derive-address' | 'unsupported-scheme' | 'await-chain-ready' | 'fund-default' | 'fund-cross-cutting' | 'register';
+/** Account acquisition error — raised by the variant resolvers and
+ *  the funding pass. Carries the per-variant + per-phase column. */
+interface AccountAcquireError {
+  readonly _tag: 'AccountAcquireError';
+  readonly phase: AccountAcquirePhase;
+  readonly accountName: string;
+  readonly variant: AccountVariantKind;
+  readonly message: string;
+  readonly hint?: string;
+  readonly cause?: unknown;
+}
+/** Phases for `AccountSignError`. The "sign-and-execute" surface is
+ *  the canonical entry point; the impersonation refusal lives here
+ *  so a synchronous throw maps cleanly onto an async catch boundary
+ *  when callers wrap the resolved-account signer in `Effect.try`. */
+type AccountSignPhase = 'build-tx' | 'sign' | 'submit' | 'await-finality' | 'dependent-package-not-found' | 'lease-acquire' | 'impersonation-bypass-attempt';
+/** Account sign/execute error — raised by the per-account signer's
+ *  `signAndExecute` / `signTransaction` / `signPersonalMessage`
+ *  surfaces.
+ *
+ *  Distilled-doc opportunity: today's implementation projects this to
+ *  JSON specially. Promoting to the uniform-shape interface here lets
+ *  the cause walker treat it like every other plugin's tagged error;
+ *  the special JSON-projection case can go away. */
+interface AccountSignError {
+  readonly _tag: 'AccountSignError';
+  readonly phase: AccountSignPhase;
+  readonly accountName: string;
+  readonly address: string;
+  readonly message: string;
+  readonly cause?: unknown;
+}
+/** Account variant discriminator. Mirrors the user-facing
+ *  `AccountOptions` shape's `kind:` field. */
+type AccountVariantKind = 'ephemeral' | 'keystore' | 'env' | 'inline' | 'signer' | 'impersonate';
+/** Union of every error an Account-plugin caller may encounter. */
+type AccountError = AccountAcquireError | AccountSignError;
+//#endregion
+export { AccountAcquireError, AccountAcquirePhase, AccountError, AccountSignError, AccountSignPhase, AccountVariantKind };
+//# sourceMappingURL=errors.d.mts.map

package/dist/plugins/account/errors.mjs

@@ -0,0 +1,16 @@
+//#region src/plugins/account/errors.ts
+const accountAcquireError = (parts) => ({
+	_tag: "AccountAcquireError",
+	...parts
+});
+const accountSignError = (parts) => ({
+	_tag: "AccountSignError",
+	...parts
+});
+/** Error tags this plugin contributes — surfaced to the cause walker
+*  via `PluginErrorContribution`. */
+const ACCOUNT_ERROR_TAGS = ["AccountAcquireError", "AccountSignError"];
+//#endregion
+export { ACCOUNT_ERROR_TAGS, accountAcquireError, accountSignError };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/plugins/account/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/account/errors.ts"],"sourcesContent":["// Account plugin — typed errors.\n//\n// Distilled-doc finding (12-account.md \"Acquisition vs signing error\n// split\" invariant): two error families must not be mixed. Acquisition\n// errors (keystore unreadable, faucet exhausted, scheme unsupported)\n// surface as `AccountAcquireError`; signing errors (gRPC failure,\n// finality wait, locked-shared-object) surface as `AccountSignError`.\n// Mixing them breaks downstream `catchTag` boundaries — the engine's\n// pretty-cause walker also dispatches on `_tag`, so any merger here\n// would force a renderer-side branch on `phase` instead.\n//\n// Effect v4: plain interface + `_tag` literal discriminator (no\n// subclassing). The architecture's per-plugin tagged-error convention\n// (12-account.md \"Promote the sign/execute error to the same\n// tagged-error class shape\") is honored here — both errors are\n// uniform-shape, the cause walker handles them by `_tag`.\n\n/** Phases for `AccountAcquireError`. Closed sum — adding a phase\n *  requires editing this list AND the cause-walker's display table. */\nexport type AccountAcquirePhase =\n\t| 'validate-name'\n\t| 'load-keystore'\n\t| 'read-env'\n\t| 'decode-inline'\n\t| 'bind-signer'\n\t| 'bind-impersonation-slot'\n\t| 'generate-keypair'\n\t| 'persist-keypair'\n\t| 'read-persisted-keypair'\n\t| 'restrict-permissions'\n\t| 'derive-address'\n\t| 'unsupported-scheme'\n\t| 'await-chain-ready'\n\t| 'fund-default'\n\t| 'fund-cross-cutting'\n\t| 'register';\n\n/** Account acquisition error — raised by the variant resolvers and\n *  the funding pass. Carries the per-variant + per-phase column. */\nexport interface AccountAcquireError {\n\treadonly _tag: 'AccountAcquireError';\n\treadonly phase: AccountAcquirePhase;\n\treadonly accountName: string;\n\treadonly variant: AccountVariantKind;\n\treadonly message: string;\n\treadonly hint?: string;\n\treadonly cause?: unknown;\n}\n\nexport const accountAcquireError = (\n\tparts: Omit<AccountAcquireError, '_tag'>,\n): AccountAcquireError => ({ _tag: 'AccountAcquireError', ...parts });\n\n/** Phases for `AccountSignError`. The \"sign-and-execute\" surface is\n *  the canonical entry point; the impersonation refusal lives here\n *  so a synchronous throw maps cleanly onto an async catch boundary\n *  when callers wrap the resolved-account signer in `Effect.try`. */\nexport type AccountSignPhase =\n\t| 'build-tx'\n\t| 'sign'\n\t| 'submit'\n\t| 'await-finality'\n\t| 'dependent-package-not-found'\n\t| 'lease-acquire'\n\t| 'impersonation-bypass-attempt';\n\n/** Account sign/execute error — raised by the per-account signer's\n *  `signAndExecute` / `signTransaction` / `signPersonalMessage`\n *  surfaces.\n *\n *  Distilled-doc opportunity: today's implementation projects this to\n *  JSON specially. Promoting to the uniform-shape interface here lets\n *  the cause walker treat it like every other plugin's tagged error;\n *  the special JSON-projection case can go away. */\nexport interface AccountSignError {\n\treadonly _tag: 'AccountSignError';\n\treadonly phase: AccountSignPhase;\n\treadonly accountName: string;\n\treadonly address: string;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const accountSignError = (parts: Omit<AccountSignError, '_tag'>): AccountSignError => ({\n\t_tag: 'AccountSignError',\n\t...parts,\n});\n\n/** Account variant discriminator. Mirrors the user-facing\n *  `AccountOptions` shape's `kind:` field. */\nexport type AccountVariantKind =\n\t| 'ephemeral'\n\t| 'keystore'\n\t| 'env'\n\t| 'inline'\n\t| 'signer'\n\t| 'impersonate';\n\n/** Union of every error an Account-plugin caller may encounter. */\nexport type AccountError = AccountAcquireError | AccountSignError;\n\n/** Error tags this plugin contributes — surfaced to the cause walker\n *  via `PluginErrorContribution`. */\nexport const ACCOUNT_ERROR_TAGS: ReadonlyArray<AccountError['_tag']> = [\n\t'AccountAcquireError',\n\t'AccountSignError',\n] as const;\n"],"mappings":";AAiDA,MAAa,uBACZ,WAC0B;CAAE,MAAM;CAAuB,GAAG;CAAO;AAgCpE,MAAa,oBAAoB,WAA6D;CAC7F,MAAM;CACN,GAAG;CACH;;;AAiBD,MAAa,qBAA0D,CACtE,uBACA,mBACA"}