@mysten-incubation/devstack 0.1.1 → 0.2.0

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

@@ -1 +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 { mintRandomSuffix } from '../../substrate/runtime/random-suffix.ts';\n\nimport { Context, Effect, FileSystem, Layer, Ref, Schema, Scope } from 'effect';\n\nimport type { SnapshotableDecl } from '../../contracts/snapshotable.ts';\nimport type { ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport { ContainerRuntimeService } from '../../runtime/docker/index.ts';\nimport { decodeJsonText } from '../../substrate/runtime/runtime-decode.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\tSnapshotDescriptorError,\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 { runPrune, type PruneResult, type PrunePhaseError } from './prune.ts';\nimport {\n\trecoverPendingRestore,\n\ttype RestorePendingRecoveryError,\n\ttype RestorePendingRecoverySummary,\n} from './recover-pending.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 { planWipe, runWipe, type WipePhaseError, type WipeTargets } 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| RestorePendingRecoveryError\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\t| SnapshotDescriptorError;\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/** 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/** Enumerate the concrete teardown targets a `wipe` of the same\n\t *  `(app, stack)` would remove WITHOUT removing anything — the\n\t *  read-only preview behind `devstack wipe --dry-run`. Same args as\n\t *  `wipe` so the preview honors the same `keepSnapshots`/`keepCache`\n\t *  preservation policy the real wipe applies. */\n\treadonly wipePlan: (args: {\n\t\treadonly keepSnapshots?: boolean;\n\t\treadonly keepCache?: boolean;\n\t}) => Effect.Effect<WipeTargets, SnapshotOrchestratorError, FileSystem.FileSystem>;\n\n\t/** Prune the snapshot catalog (reaps partial artifacts) and sweeps\n\t *  byproduct images via the runtime adapter's label-scoped cleanup. */\n\treadonly prune: () => Effect.Effect<\n\t\tPruneResult,\n\t\tSnapshotOrchestratorError,\n\t\tFileSystem.FileSystem\n\t>;\n\n\t/** Recover from a snapshot-restore that crashed mid-way through the\n\t *  post-publish Docker handoff. Reads the on-disk pending marker,\n\t *  retries each outstanding image promote, and clears the marker.\n\t *  Idempotent — safe to call on every supervise startup; a no-op\n\t *  when no marker is present. */\n\treadonly recoverPendingRestore: Effect.Effect<\n\t\tRestorePendingRecoverySummary,\n\t\tSnapshotOrchestratorError,\n\t\tFileSystem.FileSystem\n\t>;\n}\n\nexport class SnapshotOrchestratorService extends Context.Service<\n\tSnapshotOrchestratorService,\n\tSnapshotOrchestrator\n>()('@devstack/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 => `${prefix}-${Date.now()}-${mintRandomSuffix(8)}`;\n\nconst mintSnapshotId = (): Effect.Effect<SnapshotId, SnapshotDescriptorError> => {\n\tconst raw = mintId();\n\tconst id = parseSnapshotId(raw);\n\treturn id === null\n\t\t? Effect.fail(\n\t\t\t\tnew SnapshotDescriptorError({\n\t\t\t\t\tkind: 'invalid-id',\n\t\t\t\t\tdetail: 'internal snapshot id minting produced an invalid id',\n\t\t\t\t\tvalue: raw,\n\t\t\t\t}),\n\t\t\t)\n\t\t: Effect.succeed(id);\n};\n\nconst mintSnapshotName = (): string => {\n\tconst stamp = new Date().toISOString().replaceAll('-', '').replaceAll(':', '').slice(0, 15);\n\treturn `manual-${stamp}-${mintRandomSuffix(8)}`;\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. Returns `null` when the kernel-probe\n *  couldn't determine startTime — matches `RosterHolderSchema.startTime`\n *  semantics and is honored by the sweep's `checkHolderLiveness`\n *  null-conservative short-circuit. */\nconst ownStartTime = (): number | null => 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\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 registry. The supervisor adds entries\n\t\t// from each plugin's acquire scope; finalizers remove them on\n\t\t// scope close. Sequence number protects against the parallel-\n\t\t// registration-same-key race when two stack instances register\n\t\t// concurrently.\n\t\tconst participantsRef = yield* Ref.make<ReadonlyArray<RegisteredParticipantEntry>>([]);\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 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 ? yield* 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\t// Snapshot stages at the SNAPSHOT-DIR level (siblings of\n\t\t\t\t// other artifact dirs, NOT siblings of `artifactDir`) so\n\t\t\t\t// the `list` walker's `.staging.` / `.bak.` prefix skip\n\t\t\t\t// at line 517 keeps transient dirs invisible without\n\t\t\t\t// having to descend a level. This layout is structurally\n\t\t\t\t// distinct from `${target}.staging.<id>` so we pass\n\t\t\t\t// explicit `stagingPath`/`backupPath` instead of\n\t\t\t\t// `idSuffix` (the substrate primitive supports both\n\t\t\t\t// shapes — see `stageAndSwap`'s union arg).\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\t// O(N) catalog scan for label uniqueness — acceptable\n\t\t\t\t\t\t// because N (snapshot count per stack) is small in\n\t\t\t\t\t\t// practice and capture is a rare, human-paced verb. A\n\t\t\t\t\t\t// future optimization could maintain a sibling name-\n\t\t\t\t\t\t// index (e.g. `${snapshotDir}/.names/${label}` empty\n\t\t\t\t\t\t// marker files) that lets uniqueness collapse to a\n\t\t\t\t\t\t// single `fs.exists`, but that would need a paired\n\t\t\t\t\t\t// cleanup-on-delete pathway + a corruption-tolerance\n\t\t\t\t\t\t// story for the sidecar, which is outside this scope.\n\t\t\t\t\t\t//\n\t\t\t\t\t\t// Forward-reference safety: `list` is declared LATER\n\t\t\t\t\t\t// in this outer `Effect.gen` body. No TDZ fires\n\t\t\t\t\t\t// because `capture` is an arrow function returned\n\t\t\t\t\t\t// from the gen — by the time any caller invokes it,\n\t\t\t\t\t\t// the outer gen has fully resolved and all `const`\n\t\t\t\t\t\t// bindings (including `list`) are bound. The\n\t\t\t\t\t\t// regression guard at\n\t\t\t\t\t\t// test/orchestrators/snapshot/capture-collision-tdz.test.ts\n\t\t\t\t\t\t// pins this; if a future refactor wraps `list` in\n\t\t\t\t\t\t// an `Effect.fn` decorator or extracts it through a\n\t\t\t\t\t\t// hoisting-sensitive path, the guard will fail.\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 decoded = yield* decodeJsonText(SnapshotMetadataSchema, text, {\n\t\t\t\t\tsource: metaPath,\n\t\t\t\t\tmkError: () => null,\n\t\t\t\t}).pipe(Effect.catch(() => Effect.succeed(null)));\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 wipePlan: SnapshotOrchestrator['wipePlan'] = (args) =>\n\t\t\t// Read-only: no stack-lock / reservation. `planWipe` only lists\n\t\t\t// matching containers and reads the stack-root directory, so it\n\t\t\t// is safe to run without serializing against peers (a concurrent\n\t\t\t// mutation just makes the preview slightly stale — acceptable for\n\t\t\t// a dry-run estimate).\n\t\t\tplanWipe({\n\t\t\t\tlabelMatch: { app: identity.app, stack: identity.stack },\n\t\t\t\tstackRoot: paths.stackRoot,\n\t\t\t\tstateFilePath: paths.stateFile,\n\t\t\t\truntime,\n\t\t\t\tkeepSnapshots: args.keepSnapshots,\n\t\t\t\tkeepCache: args.keepCache,\n\t\t\t}).pipe(Effect.withSpan('orchestrator.snapshot.wipe.plan.entry'));\n\n\t\tconst prune: SnapshotOrchestrator['prune'] = () =>\n\t\t\tEffect.scoped(\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tyield* acquireReservation(paths.snapshotReservationFile, ownStartTime());\n\t\t\t\t\treturn yield* runPrune({\n\t\t\t\t\t\tstackRoot: paths.stackRoot,\n\t\t\t\t\t\timageLabelFilter: { app: identity.app, stack: identity.stack },\n\t\t\t\t\t\truntime,\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\tconst recoverPendingRestoreImpl: SnapshotOrchestrator['recoverPendingRestore'] =\n\t\t\trecoverPendingRestore(paths.stackRoot, runtime).pipe(\n\t\t\t\tEffect.withSpan('orchestrator.snapshot.recover-pending.entry'),\n\t\t\t);\n\n\t\treturn SnapshotOrchestratorService.of({\n\t\t\tregisterParticipant,\n\t\t\tcapture,\n\t\t\trestore,\n\t\t\tlist,\n\t\t\tdelete: del,\n\t\t\twipe,\n\t\t\twipePlan,\n\t\t\tprune,\n\t\t\trecoverPendingRestore: recoverPendingRestoreImpl,\n\t\t});\n\t}),\n);\n"],"mappings":"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"}
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/orchestrators/snapshot/service.ts"],"sourcesContent":["// Snapshot orchestrator service.\n//\n// Snapshotting is a parameterization of the lifecycle bounce, not a\n// separate subsystem:\n//\n//   gracefully stop everything → snapshot (docker commit each container +\n//   capture local files) / swap-in (restore) → resume if needed.\n//\n// The two mutate verbs (`capture`, `restore`) share that bounce; `list`,\n// `delete`, `wipe`, `prune` are the catalog/teardown surface around it.\n//\n// Lock discipline: the bounce holds `stack.lock` for the (bounded,\n// whole-stack-stopped) snapshot window. There is no separate snapshot\n// reservation — the stop+commit window is bounded and the lock subsumes\n// the concurrency guard while keeping the roster heartbeat from starving.\n//\n// The service surface is name-blind. The participant list is populated by\n// the substrate at boot from the `Snapshotable` decls of registered\n// plugins; service-specific behavior never reaches this file. Registration\n// is scope-bound: the supervisor calls `registerParticipant(pluginKey,\n// decl)` from inside each plugin's scope so the entry is reaped on teardown.\n\nimport { mintRandomSuffix } from '../../substrate/runtime/random-suffix.ts';\n\nimport { Context, Effect, FileSystem, Layer, Ref, Schema, Scope } from 'effect';\n\nimport type { SnapshotableDecl } from '../../contracts/snapshotable.ts';\nimport type { ContainerRuntime } from '../../contracts/container-runtime.ts';\nimport { ContainerRuntimeService } from '../../runtime/docker/index.ts';\nimport { decodeJsonText } from '../../substrate/runtime/runtime-decode.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\tresumeAfterCapture,\n\ttype CapturePhaseError,\n\ttype SnapshotParticipant,\n} from './capture.ts';\nimport {\n\tSnapshotDescriptorError,\n\tSnapshotLayout,\n\tSnapshotMetadataSchema,\n\tSNAPSHOT_ID_RULE,\n\tparseSnapshotId,\n\ttype SnapshotId,\n\ttype SnapshotCatalogEntry,\n\ttype SnapshotGraphInputIdentity,\n\ttype SnapshotMetadata,\n} from './descriptor.ts';\nimport {\n\ttype IdentityContributionConflictError,\n\ttype IdentityGuardError,\n} from './identity-guard.ts';\nimport { runPrune, type PruneResult, type PrunePhaseError } from './prune.ts';\nimport { runRestore, RestorePhaseError, type RestoreParticipant } from './restore.ts';\nimport {\n\tstageAndSwap,\n\ttype StageAndSwapError,\n} from '../../substrate/runtime/stage-and-swap/index.ts';\nimport { planWipe, runWipe, type WipePhaseError, type WipeTargets } 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| StackLockError\n\t| SnapshotIdError\n\t| SnapshotDescriptorError;\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/** Capture a new snapshot — the lifecycle bounce: gather → graceful-stop\n\t *  (flush) → commit + tar + meta → retag committed images onto original\n\t *  names + hard-rm → resume (recreate + wait-write-ready). The id MAY be\n\t *  caller-supplied; if omitted, the substrate mints a random suffix to\n\t *  sidestep the concurrent-saves-against-same-id silent overwrite.\n\t *\n\t *  `resume` re-converges the stack to write-ready after the publish (the\n\t *  supervisor wires it to a stack restart; omit on an offline one-shot\n\t *  capture where the next boot is the resume).\n\t *\n\t *  `participants` overrides the registered set — primarily for tests.\n\t *  Production callers omit it; the orchestrator reads the registered list. */\n\treadonly capture: (args: {\n\t\treadonly id?: string;\n\t\treadonly label?: string;\n\t\treadonly graphInput: SnapshotGraphInputIdentity;\n\t\treadonly replaceExistingLabel?: boolean;\n\t\treadonly participants?: ReadonlyArray<SnapshotParticipant>;\n\t\treadonly resume?: Effect.Effect<void>;\n\t}) => Effect.Effect<SnapshotMetadata, SnapshotOrchestratorError, FileSystem.FileSystem>;\n\n\t/** Restore from a captured artifact id — the destructive,\n\t *  ordered half of the bounce: identity-guard fail-closed + cache-missing\n\t *  preflight BEFORE any mutation → swap host-tree in + load images → hard-\n\t *  rm → resume = recreate (the next boot / the injected converge). */\n\treadonly restore: (args: {\n\t\treadonly id: string;\n\t\treadonly currentGraphInput?: SnapshotGraphInputIdentity;\n\t\treadonly graphInputMismatchPolicy?: 'warn' | 'block';\n\t\treadonly participants?: ReadonlyArray<RestoreParticipant>;\n\t\treadonly resume?: Effect.Effect<void>;\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 snapshot\n\t *  catalog AND the deploy cache together by default (`keepSnapshots`,\n\t *  default true). A hard reset (`keepSnapshots: false`) drops both so\n\t *  on-chain artifacts re-prove against the next chain — there is no\n\t *  asymmetric keep-snapshots-drop-cache degree of freedom. */\n\treadonly wipe: (args: {\n\t\treadonly keepSnapshots?: boolean;\n\t}) => Effect.Effect<void, SnapshotOrchestratorError, FileSystem.FileSystem>;\n\n\t/** Enumerate the concrete teardown targets a `wipe` of the same\n\t *  `(app, stack)` would remove WITHOUT removing anything — the\n\t *  read-only preview behind `devstack wipe --dry-run`. */\n\treadonly wipePlan: (args: {\n\t\treadonly keepSnapshots?: boolean;\n\t}) => Effect.Effect<WipeTargets, SnapshotOrchestratorError, FileSystem.FileSystem>;\n\n\t/** Prune the snapshot catalog (reaps partial artifacts) and sweeps\n\t *  byproduct images via the runtime adapter's label-scoped cleanup. */\n\treadonly prune: () => Effect.Effect<\n\t\tPruneResult,\n\t\tSnapshotOrchestratorError,\n\t\tFileSystem.FileSystem\n\t>;\n}\n\nexport class SnapshotOrchestratorService extends Context.Service<\n\tSnapshotOrchestratorService,\n\tSnapshotOrchestrator\n>()('@devstack/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 => `${prefix}-${Date.now()}-${mintRandomSuffix(8)}`;\n\nconst mintSnapshotId = (): Effect.Effect<SnapshotId, SnapshotDescriptorError> => {\n\tconst raw = mintId();\n\tconst id = parseSnapshotId(raw);\n\treturn id === null\n\t\t? Effect.fail(\n\t\t\t\tnew SnapshotDescriptorError({\n\t\t\t\t\tkind: 'invalid-id',\n\t\t\t\t\tdetail: 'internal snapshot id minting produced an invalid id',\n\t\t\t\t\tvalue: raw,\n\t\t\t\t}),\n\t\t\t)\n\t\t: Effect.succeed(id);\n};\n\nconst mintSnapshotName = (): string => {\n\tconst stamp = new Date().toISOString().replaceAll('-', '').replaceAll(':', '').slice(0, 15);\n\treturn `manual-${stamp}-${mintRandomSuffix(8)}`;\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\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/** 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\n/**\n * Wire the orchestrator from the substrate's path resolver + the runtime\n * container adapter.\n *\n * Discipline: capture/restore acquire `stack.lock` for the (bounded,\n * whole-stack-stopped) snapshot window; the `stageAndSwap` rename publishes\n * atomically inside it. List/delete/wipe/prune acquire `stack.lock` briefly\n * (they don't bounce containers).\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 registry. The supervisor adds entries from\n\t\t// each plugin's acquire scope; finalizers remove them on scope close.\n\t\t// Sequence number protects against the parallel-registration-same-key\n\t\t// race when two stack instances register concurrently.\n\t\tconst participantsRef = yield* Ref.make<ReadonlyArray<RegisteredParticipantEntry>>([]);\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}) as Effect.Effect<void, never, Scope.Scope>;\n\n\t\tconst capture: SnapshotOrchestrator['capture'] = ({\n\t\t\tid,\n\t\t\tlabel,\n\t\t\tgraphInput,\n\t\t\treplaceExistingLabel,\n\t\t\tparticipants,\n\t\t\tresume,\n\t\t}) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst snapshotId =\n\t\t\t\t\tid === undefined ? yield* 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\t// Snapshot stages at the SNAPSHOT-DIR level (siblings of other\n\t\t\t\t// artifact dirs) so the `list` walker's `.staging.` / `.bak.`\n\t\t\t\t// prefix skip keeps transient dirs invisible.\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// Hold `stack.lock` ONLY across the build+publish half of the\n\t\t\t\t// bounce (gather → graceful-stop → commit + tar + meta →\n\t\t\t\t// stage-and-swap). The lock subsumes the concurrency guard for\n\t\t\t\t// that bounded window while keeping the roster heartbeat from\n\t\t\t\t// starving.\n\t\t\t\t//\n\t\t\t\t// CRITICAL: the lock is RELEASED before the resume. The post-\n\t\t\t\t// publish resume re-converges the stack, and each plugin's\n\t\t\t\t// re-acquire takes `stack.lock` for its container-claim protocol\n\t\t\t\t// (runtime/docker/container.ts) — `stack.lock` is a non-reentrant\n\t\t\t\t// O_EXCL file lock, so holding it across the resume self-deadlocks:\n\t\t\t\t// the re-acquire's claim EEXISTs against THIS process's own still-\n\t\t\t\t// held lock, can't reclaim it (the holder PID is alive — us), and\n\t\t\t\t// times out after 5s → every plugin's `start` fails → the resume\n\t\t\t\t// comes back `failed` (sui RPC dead → `fetch failed`; codegen\n\t\t\t\t// contributions never re-register → empty `config.ts`). Scoping the\n\t\t\t\t// lock to the publish and running `resumeAfterCapture` AFTER it\n\t\t\t\t// releases lets the re-acquire claim containers normally.\n\t\t\t\tconst { meta, replacedSnapshotIds } = yield* 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\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\t// O(N) catalog scan for label uniqueness — N is small and\n\t\t\t\t\t\t// capture is human-paced. `list` is declared LATER in this\n\t\t\t\t\t\t// gen; no TDZ fires because `capture` is invoked only after\n\t\t\t\t\t\t// the outer gen has resolved all `const` bindings.\n\t\t\t\t\t\tconst existing = yield* list;\n\t\t\t\t\t\tconst duplicateLabels = existing.filter(\n\t\t\t\t\t\t\t(entry) => entry.metadata?.label === snapshotName,\n\t\t\t\t\t\t);\n\t\t\t\t\t\tif (duplicateLabels.length > 0 && replaceExistingLabel !== true) {\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\t\t\t\t\t\tconst replacedSnapshotIds = duplicateLabels\n\t\t\t\t\t\t\t.map((entry) => entry.id)\n\t\t\t\t\t\t\t.filter((entryId) => entryId !== snapshotId);\n\n\t\t\t\t\t\t// Build + publish the artifact (gather → stop → commit +\n\t\t\t\t\t\t// tar + meta), atomically via stage-and-swap so watchers /\n\t\t\t\t\t\t// `list` 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.network,\n\t\t\t\t\t\t\t\tgraphInput,\n\t\t\t\t\t\t\t\truntimeStackRoot: paths.stackRoot,\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}),\n\t\t\t\t\t\t});\n\t\t\t\t\t\treturn { meta, replacedSnapshotIds };\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t\t// Post-publish bounce tail — runs with `stack.lock` RELEASED (see\n\t\t\t\t// the CRITICAL note above) so the resume's per-plugin container\n\t\t\t\t// claims can take the lock. Retag committed images onto original\n\t\t\t\t// names + hard-rm + resume (recreate + wait-write-ready). Runs AFTER\n\t\t\t\t// the swap so a publish failure leaves the live stack only stopped\n\t\t\t\t// (recoverable by the next boot).\n\t\t\t\tyield* resumeAfterCapture(meta, {\n\t\t\t\t\truntime,\n\t\t\t\t\tapp: identity.app,\n\t\t\t\t\tstack: identity.stack,\n\t\t\t\t\t...(resume === undefined ? {} : { resume }),\n\t\t\t\t});\n\t\t\t\tyield* Effect.forEach(replacedSnapshotIds, del, { discard: true });\n\t\t\t\treturn meta;\n\t\t\t});\n\n\t\tconst restore: SnapshotOrchestrator['restore'] = ({\n\t\t\tid,\n\t\t\tcurrentGraphInput,\n\t\t\tgraphInputMismatchPolicy,\n\t\t\tparticipants,\n\t\t\tresume,\n\t\t}) =>\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\t// The effective participant set is the live registered set (or an\n\t\t\t\t// explicit override). During startup restore, interrupted-restore\n\t\t\t\t// recovery, and offline CLI restore, no plugin has registered yet,\n\t\t\t\t// so this is EMPTY. `runRestore` reads an empty\n\t\t\t\t// participant set as \"no live stack to compare against\" and skips\n\t\t\t\t// ONLY the cross-plugin contribution guard (the runtime app/stack/\n\t\t\t\t// network guard + the snapshot-side emptiness refusal still fire).\n\t\t\t\t// A LIVE-supervisor restore (operator-triggered while the stack is up)\n\t\t\t\t// has a populated registered set, so the real contribution guard runs.\n\t\t\t\tconst effectiveParticipants =\n\t\t\t\t\tparticipants ?? (yield* Ref.get(participantsRef)).map((e) => e.restore);\n\t\t\t\t// Hold `stack.lock` ONLY across the destructive swap+load+hard-rm\n\t\t\t\t// half of the bounce — the resume is run AFTER the lock releases.\n\t\t\t\t// The resume re-converges the stack and each plugin's re-acquire\n\t\t\t\t// takes `stack.lock` for its container-claim protocol; `stack.lock`\n\t\t\t\t// is a non-reentrant O_EXCL file lock, so holding it across the\n\t\t\t\t// resume self-deadlocks (the claim EEXISTs against this process's\n\t\t\t\t// own live lock and times out → every plugin fails). The offline\n\t\t\t\t// restore omits `resume` (the next boot is the resume), so this only\n\t\t\t\t// matters for a live-supervisor restore — but keep both bounce verbs\n\t\t\t\t// consistent: lock the publish, resume unlocked. So `runRestore` runs\n\t\t\t\t// WITHOUT `resume`, and we run the injected resume below, unlocked.\n\t\t\t\tconst meta = yield* 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\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.network,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t...(currentGraphInput === undefined ? {} : { currentGraphInput }),\n\t\t\t\t\t\t\t...(graphInputMismatchPolicy === undefined ? {} : { graphInputMismatchPolicy }),\n\t\t\t\t\t\t});\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t\t// Resume with `stack.lock` RELEASED so the re-converge's per-plugin\n\t\t\t\t// container claims can take the lock (see the note above). Omitted\n\t\t\t\t// on the offline restore (the next boot is the resume).\n\t\t\t\tif (resume !== undefined) {\n\t\t\t\t\tyield* resume.pipe(\n\t\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t\t(cause) =>\n\t\t\t\t\t\t\t\tnew RestorePhaseError({\n\t\t\t\t\t\t\t\t\tphase: 'resume',\n\t\t\t\t\t\t\t\t\tdetail: 'stack resume after restore failed',\n\t\t\t\t\t\t\t\t\tcause,\n\t\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\treturn meta;\n\t\t\t});\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 — invisible to the\n\t\t\t\t// catalog by construction (the `.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 decoded = yield* decodeJsonText(SnapshotMetadataSchema, text, {\n\t\t\t\t\tsource: metaPath,\n\t\t\t\t\tmkError: () => null,\n\t\t\t\t}).pipe(Effect.catch(() => Effect.succeed(null)));\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});\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});\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\truntime,\n\t\t\t\t\t\t\tkeepSnapshots: args.keepSnapshots,\n\t\t\t\t\t\t});\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t});\n\n\t\tconst wipePlan: SnapshotOrchestrator['wipePlan'] = (args) =>\n\t\t\t// Read-only: no stack-lock. `planWipe` only lists matching\n\t\t\t// containers and reads the stack-root directory, so it is safe to\n\t\t\t// run without serializing against peers (a concurrent mutation just\n\t\t\t// makes the preview slightly stale — acceptable for a dry-run).\n\t\t\tplanWipe({\n\t\t\t\tlabelMatch: { app: identity.app, stack: identity.stack },\n\t\t\t\tstackRoot: paths.stackRoot,\n\t\t\t\truntime,\n\t\t\t\tkeepSnapshots: args.keepSnapshots,\n\t\t\t});\n\n\t\tconst prune: SnapshotOrchestrator['prune'] = () =>\n\t\t\tEffect.scoped(\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tyield* acquireStackLock(paths.stackLockFile);\n\t\t\t\t\treturn yield* runPrune({\n\t\t\t\t\t\tstackRoot: paths.stackRoot,\n\t\t\t\t\t\timageLabelFilter: { app: identity.app, stack: identity.stack },\n\t\t\t\t\t\truntime,\n\t\t\t\t\t});\n\t\t\t\t}),\n\t\t\t);\n\n\t\treturn SnapshotOrchestratorService.of({\n\t\t\tregisterParticipant,\n\t\t\tcapture,\n\t\t\trestore,\n\t\t\tlist,\n\t\t\tdelete: del,\n\t\t\twipe,\n\t\t\twipePlan,\n\t\t\tprune,\n\t\t});\n\t}),\n);\n"],"mappings":"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"}

package/dist/orchestrators/snapshot/wipe.mjs

@@ -1,3 +1,7 @@
+import { appName, stackName } from "../../substrate/brand.mjs";
+import { labelScope, reconcileSpec } from "../../substrate/runtime/reconcile/spec.mjs";
+import { reconcileLabel } from "../../substrate/runtime/reconcile/label.mjs";
+import "../../substrate/runtime/reconcile/index.mjs";
 import { makePhaseFailer } from "./phase-error.mjs";
 import { Effect, FileSystem, Schema } from "effect";
 //#region src/orchestrators/snapshot/wipe.ts
@@ -5,43 +9,36 @@ var WipePhaseError = class extends Schema.TaggedErrorClass()("SnapshotWipePhaseE
 	phase: Schema.Literals([
 		"sweep-containers",
 		"sweep-networks-volumes",
-		"remove-state",
 		"remove-runtime-tree"
 	]),
 	detail: Schema.String,
 	cause: Schema.optional(Schema.Defect)
 }) {};
 const failPhase = makePhaseFailer(WipePhaseError);
-const resolvePreservePolicy = (inputs) => ({
-	keepSnapshots: inputs.keepSnapshots ?? true,
-	keepCache: inputs.keepCache ?? false
-});
 /** True when a direct child of `stackRoot` is PRESERVED (not removed)
-*  by a wipe under `policy`. `snapshots/` survives by default; `cache/`
-*  survives only when explicitly requested. Every other child — state,
-*  cross-process artifacts, per-plugin runtime trees — is removed. */
-const isPreservedChild = (name, policy) => policy.keepSnapshots && name === "snapshots" || policy.keepCache && name === "cache";
+*  by a wipe under `preserve`. The snapshot catalog (`snapshots/`) and
+*  the deploy cache (`cache/`) survive TOGETHER by default and are
+*  dropped together on a hard reset — they ride the one `preserve`
+*  flag. Every other child — state, cross-process artifacts, per-plugin
+*  runtime trees — is removed regardless. */
+const isPreservedChild = (name, preserve) => preserve && (name === "snapshots" || name === "cache");
 /**
 * Enumerate the concrete targets a wipe of `inputs.labelMatch` would
 * remove, WITHOUT removing anything. Read-only: lists matching
 * containers via the runtime adapter and reads the stack-root directory
 * to classify each child against the SAME preserve predicate `runWipe`
-* uses. Backs `devstack wipe --dry-run`.
+* uses (`snapshots/` and `cache/` survive together by default). Backs
+* `devstack wipe --dry-run`.
 */
 const planWipe = (inputs) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
-	yield* Effect.annotateCurrentSpan({
-		"devstack.snapshot.phase": "wipe-plan",
-		"devstack.app": inputs.labelMatch.app,
-		"devstack.stack": inputs.labelMatch.stack
-	});
 	const containers = (yield* inputs.runtime.inspectByLabels(inputs.labelMatch).pipe(Effect.catch(failPhase("sweep-containers", `container inspect failed`)))).map((h) => h.name).sort();
-	const policy = resolvePreservePolicy(inputs);
+	const preserve = inputs.keepSnapshots ?? true;
 	const children = yield* fs.readDirectory(inputs.stackRoot).pipe(Effect.catch(() => Effect.succeed([])));
 	const onDiskPaths = [];
 	const preserved = [];
 	for (const name of [...children].sort()) {
-		if (isPreservedChild(name, policy)) {
+		if (isPreservedChild(name, preserve)) {
 			preserved.push(name);
 			continue;
 		}
@@ -53,62 +50,76 @@ const planWipe = (inputs) => Effect.gen(function* () {
 		containers,
 		networkLabelMatch: inputs.labelMatch,
 		volumeLabelMatch: inputs.labelMatch,
-		stateFile: inputs.stateFilePath,
 		stackRoot: inputs.stackRoot,
 		onDiskPaths,
 		preserved
 	};
-}).pipe(Effect.withSpan("orchestrator.snapshot.wipe.plan"));
+});
 /**
-* Tear down a stack's live footprint. Snapshots survive by default
-* (architecture § wipe).
+* Tear down a stack's live footprint. The snapshot catalog AND the
+* deploy cache survive together by default (architecture § wipe).
+*
+* Routed through the unified reconcile: a flat LABEL-scope spec —
+* `target: 'absent'` (hard container/network/volume rm) +
+* `fsPlan: [sweep-children(isPreservedChild), reap-empty]` — executed by
+* `reconcileLabel`. The per-step order is:
 *
-* 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.
-*   5. Remove the now-empty stack root when nothing survived (no
-*      preserved child remains) so wipe doesn't leak an empty
-*      `stacks/<stack>/` directory.
+*   3. Sweep the runtime tree EXCEPT the wipe-scoped survivors
+*      (`snapshots/` AND `cache/`) by default — the `sweep-children` op
+*      consults the SAME `isPreservedChild` predicate `planWipe` uses, so
+*      the preview can never drift from what the real wipe removes.
+*   4. Reap the now-empty stack root when nothing survived so wipe doesn't
+*      leak an empty `stacks/<stack>/` directory (the `reap-empty` op,
+*      reading the preserved-count threaded from `sweep-children`).
+*
+* `WipePhaseError` tags are preserved by passing each step's failer into
+* the reconcile (containers → `sweep-containers`; networks/volumes →
+* `sweep-networks-volumes`; child removal → `remove-runtime-tree`). The
+* reap-empty step is best-effort (no phase).
+*
+* `snapshots/` and `cache/` are coupled (decision-1: there is no asymmetric
+* keep-snapshots-drop-cache degree of freedom on disk), so the single
+* `keepSnapshots` flag drives both: the on-disk preservation is driven by
+* `isPreservedChild`.
 */
 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
+	const preserve = inputs.keepSnapshots ?? true;
+	const sweepChildren = {
+		op: "sweep-children",
+		stackRoot: inputs.stackRoot,
+		preserve: (name) => isPreservedChild(name, preserve),
+		onError: failPhase("remove-runtime-tree", `remove stack-root child failed`)
+	};
+	const reapEmpty = {
+		op: "reap-empty",
+		stackRoot: inputs.stackRoot
+	};
+	yield* reconcileLabel(reconcileSpec({
+		target: "absent",
+		scope: labelScope({
+			app: appName(inputs.labelMatch.app),
+			stack: stackName(inputs.labelMatch.stack)
+		}),
+		direction: "drain",
+		fsPlan: { ops: [sweepChildren, reapEmpty] }
+	}), {
+		runtime: inputs.runtime,
+		onContainersError: failPhase("sweep-containers", `container sweep failed`),
+		onNetworksError: failPhase("sweep-networks-volumes", `network sweep failed`),
+		onVolumesError: failPhase("sweep-networks-volumes", `volume sweep failed`)
 	});
-	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 policy = resolvePreservePolicy(inputs);
-	const children = yield* fs.readDirectory(inputs.stackRoot).pipe(Effect.catch(() => Effect.succeed([])));
-	let preservedCount = 0;
-	for (const name of children) {
-		if (isPreservedChild(name, policy)) {
-			preservedCount += 1;
-			continue;
-		}
-		yield* fs.remove(`${inputs.stackRoot}/${name}`, {
-			recursive: true,
-			force: true
-		}).pipe(Effect.catch(failPhase("remove-runtime-tree", `remove ${name} failed`)));
-	}
-	if (preservedCount === 0 && children.length > 0) yield* fs.remove(inputs.stackRoot, {
-		recursive: true,
-		force: true
-	}).pipe(Effect.ignore);
-}).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";
 /** Canonical stack-local artifact-cache directory name. `runWipe`
-*  preserves it only under `keepCache`; otherwise it is removed so a
-*  reset re-proves on-chain artifacts against the next chain. */
+*  preserves it together with `snapshots/` under the one `keepSnapshots`
+*  flag (default); a hard reset (`keepSnapshots: false`) removes it so a
+*  fresh boot re-proves on-chain artifacts against the next chain. */
 const CACHE_DIR_NAME = "cache";
 //#endregion
 export { CACHE_DIR_NAME, SNAPSHOTS_DIR_NAME, WipePhaseError, planWipe, runWipe };

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

@@ -1 +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';\nimport { makePhaseFailer } from './phase-error.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 = makePhaseFailer(WipePhaseError);\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// Preserve predicate — the single source of truth for \"what survives a\n// wipe on disk\". Both `runWipe` (the destructive pass) and `planWipe`\n// (the dry-run enumeration) consult this so the preview can never drift\n// from what the real wipe removes.\n// -----------------------------------------------------------------------------\n\ninterface PreservePolicy {\n\treadonly keepSnapshots: boolean;\n\treadonly keepCache: boolean;\n}\n\nconst resolvePreservePolicy = (inputs: WipeInputs): PreservePolicy => ({\n\tkeepSnapshots: inputs.keepSnapshots ?? true,\n\tkeepCache: inputs.keepCache ?? false,\n});\n\n/** True when a direct child of `stackRoot` is PRESERVED (not removed)\n *  by a wipe under `policy`. `snapshots/` survives by default; `cache/`\n *  survives only when explicitly requested. Every other child — state,\n *  cross-process artifacts, per-plugin runtime trees — is removed. */\nconst isPreservedChild = (name: string, policy: PreservePolicy): boolean =>\n\t(policy.keepSnapshots && name === SNAPSHOTS_DIR_NAME) ||\n\t(policy.keepCache && name === CACHE_DIR_NAME);\n\n// -----------------------------------------------------------------------------\n// Dry-run enumeration\n// -----------------------------------------------------------------------------\n\n/** Concrete teardown targets a wipe of one `(app, stack)` would remove.\n *  Produced by `planWipe` WITHOUT mutating anything so `devstack wipe\n *  --dry-run` can show the operator exactly what a real wipe deletes. */\nexport interface WipeTargets {\n\treadonly app: string;\n\treadonly stack: string;\n\t/** Managed container NAMES that match the `{ app, stack }` label\n\t *  filter — enumerated via the runtime adapter so the preview lists\n\t *  the exact containers a real wipe force-removes. */\n\treadonly containers: ReadonlyArray<string>;\n\t/** Networks/volumes are removed by the SAME `{ app, stack }` label\n\t *  filter the runtime adapter sweeps on. The contract exposes no\n\t *  by-label LIST for these, so the plan reports the selector that\n\t *  scopes the removal rather than a (daemon-round-trip) name list. */\n\treadonly networkLabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>;\n\treadonly volumeLabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>;\n\t/** Absolute path of the per-stack `state.json` that is removed. */\n\treadonly stateFile: string;\n\t/** Absolute path of the per-stack runtime root. Its non-preserved\n\t *  children (see `onDiskPaths`) are removed; the directory itself is\n\t *  reaped too when nothing survives. */\n\treadonly stackRoot: string;\n\t/** Absolute paths of the `stackRoot` children a real wipe removes —\n\t *  everything except the preserved `snapshots/` (and `cache/` unless\n\t *  `keepCache`). Empty when the stack root does not exist yet. */\n\treadonly onDiskPaths: ReadonlyArray<string>;\n\t/** Direct children PRESERVED on disk (`snapshots/`, optionally\n\t *  `cache/`) — surfaced so the preview is explicit about survivors. */\n\treadonly preserved: ReadonlyArray<string>;\n}\n\n/**\n * Enumerate the concrete targets a wipe of `inputs.labelMatch` would\n * remove, WITHOUT removing anything. Read-only: lists matching\n * containers via the runtime adapter and reads the stack-root directory\n * to classify each child against the SAME preserve predicate `runWipe`\n * uses. Backs `devstack wipe --dry-run`.\n */\nexport const planWipe = (\n\tinputs: WipeInputs,\n): Effect.Effect<WipeTargets, 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-plan',\n\t\t\t'devstack.app': inputs.labelMatch.app,\n\t\t\t'devstack.stack': inputs.labelMatch.stack,\n\t\t});\n\n\t\tconst handles = yield* inputs.runtime\n\t\t\t.inspectByLabels(inputs.labelMatch as ContainerLabelTuple)\n\t\t\t.pipe(Effect.catch(failPhase('sweep-containers', `container inspect failed`)));\n\t\tconst containers = handles.map((h) => h.name).sort();\n\n\t\tconst policy = resolvePreservePolicy(inputs);\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 onDiskPaths: Array<string> = [];\n\t\tconst preserved: Array<string> = [];\n\t\tfor (const name of [...children].sort()) {\n\t\t\tif (isPreservedChild(name, policy)) {\n\t\t\t\tpreserved.push(name);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tonDiskPaths.push(`${inputs.stackRoot}/${name}`);\n\t\t}\n\n\t\treturn {\n\t\t\tapp: inputs.labelMatch.app,\n\t\t\tstack: inputs.labelMatch.stack,\n\t\t\tcontainers,\n\t\t\tnetworkLabelMatch: inputs.labelMatch,\n\t\t\tvolumeLabelMatch: inputs.labelMatch,\n\t\t\tstateFile: inputs.stateFilePath,\n\t\t\tstackRoot: inputs.stackRoot,\n\t\t\tonDiskPaths,\n\t\t\tpreserved,\n\t\t} satisfies WipeTargets;\n\t}).pipe(Effect.withSpan('orchestrator.snapshot.wipe.plan'));\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 *   5. Remove the now-empty stack root when nothing survived (no\n *      preserved child remains) so wipe doesn't leak an empty\n *      `stacks/<stack>/` directory.\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 the\n\t\t//    preserve predicate does NOT keep (`snapshots/` by default;\n\t\t//    `cache/` only when `keepCache`). Stack-local artifact caches\n\t\t//    are state and are removed unless explicitly requested.\n\t\tconst policy = resolvePreservePolicy(inputs);\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\tlet preservedCount = 0;\n\t\tfor (const name of children) {\n\t\t\tif (isPreservedChild(name, policy)) {\n\t\t\t\tpreservedCount += 1;\n\t\t\t\tcontinue;\n\t\t\t}\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\n\t\t// 5. Reap the now-empty stack root. When NOTHING was preserved\n\t\t//    (no `snapshots/`/`cache/` survivor) every child was removed in\n\t\t//    step 4 — any child whose removal FAILED would have raised a\n\t\t//    `remove-runtime-tree` error and aborted before here — so the\n\t\t//    directory is empty at this point. Leaving it behind leaks an\n\t\t//    empty `stacks/<stack>/` shell that `prune --list` would show as\n\t\t//    a bare group. `recursive` is required to remove a directory at\n\t\t//    all (a plain `remove` raises EISDIR even for an empty dir); it\n\t\t//    is safe here precisely BECAUSE the `preservedCount === 0` guard\n\t\t//    means no preserved subtree exists to be recursively swept.\n\t\t//    Best-effort: a (racing) re-created child just leaves the dir.\n\t\tif (preservedCount === 0 && children.length > 0) {\n\t\t\tyield* fs.remove(inputs.stackRoot, { recursive: true, force: true }).pipe(Effect.ignore);\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\n/** Canonical stack-local artifact-cache directory name. `runWipe`\n *  preserves it only under `keepCache`; otherwise it is removed so a\n *  reset re-proves on-chain artifacts against the next chain. */\nexport const CACHE_DIR_NAME = 'cache';\n"],"mappings":"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"}
+{"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 the snapshot catalog AND the deploy cache surviving together\n//   by default; a hard reset drops both.\"\n//\n// Wipe-scope coupling (decision-1): `snapshots/` and `cache/` ride ONE\n// flag (`keepSnapshots`). An ordinary wipe preserves both so a later\n// restore can REUSE the live deploy cache (the deploy ids survive the\n// teardown); a hard reset (`keepSnapshots: false`) drops both so a\n// fresh boot re-proves every on-chain artifact against the next chain.\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';\nimport { appName, stackName } from '../../substrate/brand.ts';\nimport {\n\tlabelScope,\n\treconcileLabel,\n\treconcileSpec,\n\ttype ReconcileFsOp,\n} from '../../substrate/runtime/reconcile/index.ts';\nimport { makePhaseFailer } from './phase-error.ts';\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\nexport class WipePhaseError extends Schema.TaggedErrorClass<WipePhaseError>()(\n\t'SnapshotWipePhaseError',\n\t{\n\t\tphase: Schema.Literals(['sweep-containers', 'sweep-networks-volumes', 'remove-runtime-tree']),\n\t\tdetail: Schema.String,\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n\nconst failPhase = makePhaseFailer(WipePhaseError);\n\n// -----------------------------------------------------------------------------\n// Inputs\n// -----------------------------------------------------------------------------\n\nexport interface WipeInputs {\n\treadonly labelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>;\n\treadonly stackRoot: string;\n\treadonly runtime: ContainerRuntime;\n\t/** Preserve the wipe-scoped state — the snapshot catalog (`snapshots/`)\n\t *  AND the deploy cache (`cache/`) — across the teardown. Defaults to\n\t *  true: an ordinary wipe keeps both so a later restore can REUSE the\n\t *  live deploy cache. Set false for a hard reset, which drops both\n\t *  alongside the runtime tree so a fresh boot re-proves every on-chain\n\t *  artifact against the next chain. The two dirs are coupled — there\n\t *  is no asymmetric \"keep snapshots, drop cache\" (or vice versa). */\n\treadonly keepSnapshots?: boolean;\n}\n\n// -----------------------------------------------------------------------------\n// Preserve predicate — the single source of truth for \"what survives a\n// wipe on disk\". Both `runWipe` (the destructive pass) and `planWipe`\n// (the dry-run enumeration) consult this so the preview can never drift\n// from what the real wipe removes.\n// -----------------------------------------------------------------------------\n\n/** True when a direct child of `stackRoot` is PRESERVED (not removed)\n *  by a wipe under `preserve`. The snapshot catalog (`snapshots/`) and\n *  the deploy cache (`cache/`) survive TOGETHER by default and are\n *  dropped together on a hard reset — they ride the one `preserve`\n *  flag. Every other child — state, cross-process artifacts, per-plugin\n *  runtime trees — is removed regardless. */\nconst isPreservedChild = (name: string, preserve: boolean): boolean =>\n\tpreserve && (name === SNAPSHOTS_DIR_NAME || name === CACHE_DIR_NAME);\n\n// -----------------------------------------------------------------------------\n// Dry-run enumeration\n// -----------------------------------------------------------------------------\n\n/** Concrete teardown targets a wipe of one `(app, stack)` would remove.\n *  Produced by `planWipe` WITHOUT mutating anything so `devstack wipe\n *  --dry-run` can show the operator exactly what a real wipe deletes. */\nexport interface WipeTargets {\n\treadonly app: string;\n\treadonly stack: string;\n\t/** Managed container NAMES that match the `{ app, stack }` label\n\t *  filter — enumerated via the runtime adapter so the preview lists\n\t *  the exact containers a real wipe force-removes. */\n\treadonly containers: ReadonlyArray<string>;\n\t/** Networks/volumes are removed by the SAME `{ app, stack }` label\n\t *  filter the runtime adapter sweeps on. The contract exposes no\n\t *  by-label LIST for these, so the plan reports the selector that\n\t *  scopes the removal rather than a (daemon-round-trip) name list. */\n\treadonly networkLabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>;\n\treadonly volumeLabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>;\n\t/** Absolute path of the per-stack runtime root. Its non-preserved\n\t *  children (see `onDiskPaths`) are removed; the directory itself is\n\t *  reaped too when nothing survives. */\n\treadonly stackRoot: string;\n\t/** Absolute paths of the `stackRoot` children a real wipe removes —\n\t *  everything except the wipe-scoped survivors (`snapshots/` AND\n\t *  `cache/`, kept together unless this is a hard reset). Empty when\n\t *  the stack root does not exist yet. */\n\treadonly onDiskPaths: ReadonlyArray<string>;\n\t/** Direct children PRESERVED on disk (`snapshots/` and `cache/`,\n\t *  coupled) — surfaced so the preview is explicit about survivors. */\n\treadonly preserved: ReadonlyArray<string>;\n}\n\n/**\n * Enumerate the concrete targets a wipe of `inputs.labelMatch` would\n * remove, WITHOUT removing anything. Read-only: lists matching\n * containers via the runtime adapter and reads the stack-root directory\n * to classify each child against the SAME preserve predicate `runWipe`\n * uses (`snapshots/` and `cache/` survive together by default). Backs\n * `devstack wipe --dry-run`.\n */\nexport const planWipe = (\n\tinputs: WipeInputs,\n): Effect.Effect<WipeTargets, WipePhaseError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\n\t\tconst handles = yield* inputs.runtime\n\t\t\t.inspectByLabels(inputs.labelMatch as ContainerLabelTuple)\n\t\t\t.pipe(Effect.catch(failPhase('sweep-containers', `container inspect failed`)));\n\t\tconst containers = handles.map((h) => h.name).sort();\n\n\t\tconst preserve = inputs.keepSnapshots ?? true;\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 onDiskPaths: Array<string> = [];\n\t\tconst preserved: Array<string> = [];\n\t\tfor (const name of [...children].sort()) {\n\t\t\tif (isPreservedChild(name, preserve)) {\n\t\t\t\tpreserved.push(name);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tonDiskPaths.push(`${inputs.stackRoot}/${name}`);\n\t\t}\n\n\t\treturn {\n\t\t\tapp: inputs.labelMatch.app,\n\t\t\tstack: inputs.labelMatch.stack,\n\t\t\tcontainers,\n\t\t\tnetworkLabelMatch: inputs.labelMatch,\n\t\t\tvolumeLabelMatch: inputs.labelMatch,\n\t\t\tstackRoot: inputs.stackRoot,\n\t\t\tonDiskPaths,\n\t\t\tpreserved,\n\t\t} satisfies WipeTargets;\n\t});\n\n// -----------------------------------------------------------------------------\n// Wipe\n// -----------------------------------------------------------------------------\n\n/**\n * Tear down a stack's live footprint. The snapshot catalog AND the\n * deploy cache survive together by default (architecture § wipe).\n *\n * Routed through the unified reconcile: a flat LABEL-scope spec —\n * `target: 'absent'` (hard container/network/volume rm) +\n * `fsPlan: [sweep-children(isPreservedChild), reap-empty]` — executed by\n * `reconcileLabel`. The per-step order is:\n *\n *   1. Force-remove managed containers by `{ app, stack }` labels.\n *   2. Remove managed networks and volumes by the same label filter.\n *   3. Sweep the runtime tree EXCEPT the wipe-scoped survivors\n *      (`snapshots/` AND `cache/`) by default — the `sweep-children` op\n *      consults the SAME `isPreservedChild` predicate `planWipe` uses, so\n *      the preview can never drift from what the real wipe removes.\n *   4. Reap the now-empty stack root when nothing survived so wipe doesn't\n *      leak an empty `stacks/<stack>/` directory (the `reap-empty` op,\n *      reading the preserved-count threaded from `sweep-children`).\n *\n * `WipePhaseError` tags are preserved by passing each step's failer into\n * the reconcile (containers → `sweep-containers`; networks/volumes →\n * `sweep-networks-volumes`; child removal → `remove-runtime-tree`). The\n * reap-empty step is best-effort (no phase).\n *\n * `snapshots/` and `cache/` are coupled (decision-1: there is no asymmetric\n * keep-snapshots-drop-cache degree of freedom on disk), so the single\n * `keepSnapshots` flag drives both: the on-disk preservation is driven by\n * `isPreservedChild`.\n */\nexport const runWipe = (\n\tinputs: WipeInputs,\n): Effect.Effect<void, WipePhaseError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst preserve = inputs.keepSnapshots ?? true;\n\n\t\tconst sweepChildren: ReconcileFsOp<WipePhaseError> = {\n\t\t\top: 'sweep-children',\n\t\t\tstackRoot: inputs.stackRoot,\n\t\t\tpreserve: (name) => isPreservedChild(name, preserve),\n\t\t\t// The failing child's name is not available here, so the detail\n\t\t\t// names the step rather than the child.\n\t\t\tonError: failPhase('remove-runtime-tree', `remove stack-root child failed`),\n\t\t};\n\t\tconst reapEmpty: ReconcileFsOp<WipePhaseError> = {\n\t\t\top: 'reap-empty',\n\t\t\tstackRoot: inputs.stackRoot,\n\t\t};\n\n\t\tyield* reconcileLabel(\n\t\t\treconcileSpec<WipePhaseError>({\n\t\t\t\ttarget: 'absent',\n\t\t\t\tscope: labelScope({\n\t\t\t\t\tapp: appName(inputs.labelMatch.app),\n\t\t\t\t\tstack: stackName(inputs.labelMatch.stack),\n\t\t\t\t}),\n\t\t\t\tdirection: 'drain',\n\t\t\t\tfsPlan: { ops: [sweepChildren, reapEmpty] },\n\t\t\t}),\n\t\t\t{\n\t\t\t\truntime: inputs.runtime,\n\t\t\t\tonContainersError: failPhase('sweep-containers', `container sweep failed`),\n\t\t\t\tonNetworksError: failPhase('sweep-networks-volumes', `network sweep failed`),\n\t\t\t\tonVolumesError: failPhase('sweep-networks-volumes', `volume sweep failed`),\n\t\t\t},\n\t\t);\n\t});\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\n/** Canonical stack-local artifact-cache directory name. `runWipe`\n *  preserves it together with `snapshots/` under the one `keepSnapshots`\n *  flag (default); a hard reset (`keepSnapshots: false`) removes it so a\n *  fresh boot re-proves on-chain artifacts against the next chain. */\nexport const CACHE_DIR_NAME = 'cache';\n"],"mappings":";;;;;;;AAoCA,IAAa,iBAAb,cAAoC,OAAO,iBAAiC,CAAC,CAC5E,0BACA;CACC,OAAO,OAAO,SAAS;EAAC;EAAoB;EAA0B;CAAqB,CAAC;CAC5F,QAAQ,OAAO;CACf,OAAO,OAAO,SAAS,OAAO,MAAM;AACrC,CACD,CAAC,CAAC,CAAC;AAEH,MAAM,YAAY,gBAAgB,cAAc;;;;;;;AAiChD,MAAM,oBAAoB,MAAc,aACvC,aAAa,SAAA,eAA+B,SAAA;;;;;;;;;AA4C7C,MAAa,YACZ,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,KAAK,OAAO,WAAW;CAK7B,MAAM,cAAa,OAHI,OAAO,QAC5B,gBAAgB,OAAO,UAAiC,CAAC,CACzD,KAAK,OAAO,MAAM,UAAU,oBAAoB,0BAA0B,CAAC,CAAC,EAAA,CACnD,KAAK,MAAM,EAAE,IAAI,CAAC,CAAC,KAAK;CAEnD,MAAM,WAAW,OAAO,iBAAiB;CACzC,MAAM,WAAW,OAAO,GACtB,cAAc,OAAO,SAAS,CAAC,CAC/B,KAAK,OAAO,YAAY,OAAO,QAAQ,CAAC,CAA0B,CAAC,CAAC;CACtE,MAAM,cAA6B,CAAC;CACpC,MAAM,YAA2B,CAAC;CAClC,KAAK,MAAM,QAAQ,CAAC,GAAG,QAAQ,CAAC,CAAC,KAAK,GAAG;EACxC,IAAI,iBAAiB,MAAM,QAAQ,GAAG;GACrC,UAAU,KAAK,IAAI;GACnB;EACD;EACA,YAAY,KAAK,GAAG,OAAO,UAAU,GAAG,MAAM;CAC/C;CAEA,OAAO;EACN,KAAK,OAAO,WAAW;EACvB,OAAO,OAAO,WAAW;EACzB;EACA,mBAAmB,OAAO;EAC1B,kBAAkB,OAAO;EACzB,WAAW,OAAO;EAClB;EACA;CACD;AACD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCF,MAAa,WACZ,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,iBAAiB;CAEzC,MAAM,gBAA+C;EACpD,IAAI;EACJ,WAAW,OAAO;EAClB,WAAW,SAAS,iBAAiB,MAAM,QAAQ;EAGnD,SAAS,UAAU,uBAAuB,gCAAgC;CAC3E;CACA,MAAM,YAA2C;EAChD,IAAI;EACJ,WAAW,OAAO;CACnB;CAEA,OAAO,eACN,cAA8B;EAC7B,QAAQ;EACR,OAAO,WAAW;GACjB,KAAK,QAAQ,OAAO,WAAW,GAAG;GAClC,OAAO,UAAU,OAAO,WAAW,KAAK;EACzC,CAAC;EACD,WAAW;EACX,QAAQ,EAAE,KAAK,CAAC,eAAe,SAAS,EAAE;CAC3C,CAAC,GACD;EACC,SAAS,OAAO;EAChB,mBAAmB,UAAU,oBAAoB,wBAAwB;EACzE,iBAAiB,UAAU,0BAA0B,sBAAsB;EAC3E,gBAAgB,UAAU,0BAA0B,qBAAqB;CAC1E,CACD;AACD,CAAC;;;;;AAMF,MAAa,qBAAqB;;;;;AAMlC,MAAa,iBAAiB"}

package/dist/plugins/account/codegen.mjs

@@ -11,9 +11,12 @@ const makeAccountCodegen = (parts) => defineSimpleConstExport({
 	outputPath: `accounts/${parts.name}.ts`,
 	exportName: parts.name,
 	value: parts.resolved,
+	outputLocation: "generated-extras",
+	aggregateOnly: true,
 	aggregate: {
 		kind: "account",
 		bucket: "accounts.ts",
+		outputLocation: "generated-extras",
 		project: (exported) => exported
 	}
 });

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

@@ -1 +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 type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\nimport { defineSimpleConstExport } from '../internal/codegen-helpers.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\tdefineSimpleConstExport({\n\t\temitterName: `account/${parts.name}` as `account/${Name}`,\n\t\toutputPath: `accounts/${parts.name}.ts`,\n\t\texportName: parts.name,\n\t\tvalue: parts.resolved,\n\t\taggregate: {\n\t\t\tkind: 'account',\n\t\t\tbucket: 'accounts.ts',\n\t\t\t// Pass-through: this decl's exported map already keys by\n\t\t\t// account name, which is the aggregate's merge key.\n\t\t\tproject: (exported) => exported,\n\t\t},\n\t});\n"],"mappings":";;;;;;;;AAqCA,MAAa,sBAA2C,UAIvD,wBAAwB;CACvB,aAAa,WAAW,MAAM;CAC9B,YAAY,YAAY,MAAM,KAAK;CACnC,YAAY,MAAM;CAClB,OAAO,MAAM;CACb,WAAW;EACV,MAAM;EACN,QAAQ;EAGR,UAAU,aAAa;EACvB;CACD,CAAC"}
+{"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 type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\nimport { defineSimpleConstExport } from '../internal/codegen-helpers.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\tdefineSimpleConstExport({\n\t\temitterName: `account/${parts.name}` as `account/${Name}`,\n\t\toutputPath: `accounts/${parts.name}.ts`,\n\t\texportName: parts.name,\n\t\tvalue: parts.resolved,\n\t\t// Dev-only surface: the combined `accounts.ts` lands in the\n\t\t// gitignored `generated-extras` tree (reached via `@devstack-dev`),\n\t\t// and no standalone per-account file is emitted (aggregateOnly).\n\t\t// The template app must NOT use accounts at runtime; examples\n\t\t// (dev-only) import them from `@devstack-dev`.\n\t\toutputLocation: 'generated-extras',\n\t\taggregateOnly: true,\n\t\taggregate: {\n\t\t\tkind: 'account',\n\t\t\tbucket: 'accounts.ts',\n\t\t\toutputLocation: 'generated-extras',\n\t\t\t// Pass-through: this decl's exported map already keys by\n\t\t\t// account name, which is the aggregate's merge key.\n\t\t\tproject: (exported) => exported,\n\t\t},\n\t});\n"],"mappings":";;;;;;;;AAqCA,MAAa,sBAA2C,UAIvD,wBAAwB;CACvB,aAAa,WAAW,MAAM;CAC9B,YAAY,YAAY,MAAM,KAAK;CACnC,YAAY,MAAM;CAClB,OAAO,MAAM;CAMb,gBAAgB;CAChB,eAAe;CACf,WAAW;EACV,MAAM;EACN,QAAQ;EACR,gBAAgB;EAGhB,UAAU,aAAa;CACxB;AACD,CAAC"}

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

@@ -1,7 +1,7 @@
 //#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' | 'validate-funding' | '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';
+type AccountAcquirePhase = 'validate-name' | 'validate-funding' | '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 {
@@ -63,7 +63,7 @@ interface AccountSignError {
 }
 /** Account variant discriminator. Mirrors the user-facing
  *  `AccountOptions` shape's `kind:` field. */
-type AccountVariantKind = 'ephemeral' | 'keystore' | 'env' | 'inline' | 'signer' | 'impersonate';
+type AccountVariantKind = 'ephemeral' | 'signer' | 'impersonate';
 /** Union of every error an Account-plugin caller may encounter. */
 type AccountError = AccountAcquireError | AccountSignError;
 //#endregion

package/dist/plugins/account/errors.mjs

@@ -7,10 +7,7 @@ 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 };
+export { accountAcquireError, accountSignError };
 
 //# sourceMappingURL=errors.mjs.map

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

@@ -1 +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| 'validate-funding'\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`. Strictly transport / lifecycle\n *  failures along the sign-and-execute pipeline — `signAndExecute`\n *  itself returns a `SignAndExecuteResult` discriminated union for\n *  the on-chain outcome (success vs `FailedTransaction`), so\n *  on-chain failures are NOT in this phase set. The impersonation\n *  refusal lives here so a synchronous throw maps cleanly onto an\n *  async catch boundary when callers wrap the resolved-account\n *  signer in `Effect.try`.\n *\n *   - `build-tx`         — transaction serialisation threw before\n *                          signing.\n *   - `sign`             — the signer rejected / threw.\n *   - `submit`           — `executeTransaction` transport failure\n *                          (RPC unreachable, network error). The\n *                          response never arrived.\n *   - `no-digest`        — `executeTransaction` returned a response\n *                          that violates the SDK envelope contract\n *                          (`$kind` missing OR `Transaction.digest`\n *                          missing OR `FailedTransaction.digest`\n *                          missing). Protocol violation, not a\n *                          transport failure — kept distinct so\n *                          `'submit'` keeps a single failure-kind\n *                          (per §2 \"phases describe steps, not\n *                          failure kinds\").\n *   - `await-finality`   — `waitForTransaction` failed AFTER a\n *                          submit-success; the digest exists but the\n *                          finality wait broke.\n *   - `dependent-package-not-found`\n *   - `lease-acquire`\n *   - `impersonation-bypass-attempt`\n */\nexport type AccountSignPhase =\n\t| 'build-tx'\n\t| 'sign'\n\t| 'submit'\n\t| 'no-digest'\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":";AAkDA,MAAa,uBACZ,WAC0B;CAAE,MAAM;CAAuB,GAAG;CAAO;AA4DpE,MAAa,oBAAoB,WAA6D;CAC7F,MAAM;CACN,GAAG;CACH;;;AAiBD,MAAa,qBAA0D,CACtE,uBACA,mBACA"}
+{"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| 'validate-funding'\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`. Strictly transport / lifecycle\n *  failures along the sign-and-execute pipeline — `signAndExecute`\n *  itself returns a `SignAndExecuteResult` discriminated union for\n *  the on-chain outcome (success vs `FailedTransaction`), so\n *  on-chain failures are NOT in this phase set. The impersonation\n *  refusal lives here so a synchronous throw maps cleanly onto an\n *  async catch boundary when callers wrap the resolved-account\n *  signer in `Effect.try`.\n *\n *   - `build-tx`         — transaction serialisation threw before\n *                          signing.\n *   - `sign`             — the signer rejected / threw.\n *   - `submit`           — `executeTransaction` transport failure\n *                          (RPC unreachable, network error). The\n *                          response never arrived.\n *   - `no-digest`        — `executeTransaction` returned a response\n *                          that violates the SDK envelope contract\n *                          (`$kind` missing OR `Transaction.digest`\n *                          missing OR `FailedTransaction.digest`\n *                          missing). Protocol violation, not a\n *                          transport failure — kept distinct so\n *                          `'submit'` keeps a single failure-kind\n *                          (per §2 \"phases describe steps, not\n *                          failure kinds\").\n *   - `await-finality`   — `waitForTransaction` failed AFTER a\n *                          submit-success; the digest exists but the\n *                          finality wait broke.\n *   - `dependent-package-not-found`\n *   - `lease-acquire`\n *   - `impersonation-bypass-attempt`\n */\nexport type AccountSignPhase =\n\t| 'build-tx'\n\t| 'sign'\n\t| 'submit'\n\t| 'no-digest'\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 = 'ephemeral' | 'signer' | 'impersonate';\n\n/** Union of every error an Account-plugin caller may encounter. */\nexport type AccountError = AccountAcquireError | AccountSignError;\n\n/** The catchable error tags this plugin exposes. Pinned against the\n *  user-facing error catalog by the error-catalog-parity test. */\nexport const ACCOUNT_ERROR_TAGS: ReadonlyArray<AccountError['_tag']> = [\n\t'AccountAcquireError',\n\t'AccountSignError',\n] as const;\n"],"mappings":";AAgDA,MAAa,uBACZ,WAC0B;CAAE,MAAM;CAAuB,GAAG;AAAM;AA4DnE,MAAa,oBAAoB,WAA6D;CAC7F,MAAM;CACN,GAAG;AACJ"}

package/dist/plugins/account/funding.mjs

@@ -1,13 +1,10 @@
-import { BALANCE_POLL_PROFILE, makeBoundedSpacedSchedule } from "../../substrate/runtime/retry-policy.mjs";
 import { setCurrentPluginPhase } from "../../substrate/runtime/current-plugin.mjs";
+import { BALANCE_POLL_PROFILE, makeBoundedSpacedSchedule } from "../../substrate/runtime/retry-policy.mjs";
 import { StrategyRegistryService } from "../../substrate/runtime/strategy-registry/service.mjs";
 import { chainKeyedStrategyFor } from "../../substrate/runtime/strategy-registry/chain-keyed-strategy-for.mjs";
 import "../../substrate/runtime/strategy-registry/index.mjs";
-import { SuiSpans } from "../sui/spans.mjs";
 import { FAUCET_CAPABILITY_KEY_PREFIX } from "../faucet/dispatcher.mjs";
 import "../faucet/index.mjs";
-import "../sui/index.mjs";
-import { AccountSpans } from "./spans.mjs";
 import { accountAcquireError } from "./errors.mjs";
 import { withAddressLease } from "./lease.mjs";
 import { fundingFailureError } from "../internal/funding-failure-error.mjs";
@@ -74,19 +71,8 @@ const fundEphemeralDefault = (parts) => Effect.gen(function* () {
 		coinLabel: "SUI",
 		amount: parts.amountMist
 	});
-	yield* Effect.annotateCurrentSpan({
-		[AccountSpans.name]: parts.accountName,
-		[AccountSpans.address]: parts.address,
-		[AccountSpans.fundAmountMist]: parts.amountMist.toString(),
-		[SuiSpans.chain]: parts.chainId,
-		[SuiSpans.mode]: parts.suiMode
-	});
 	return "funded";
-}).pipe(Effect.withSpan("devstack.plugin.account.fundEphemeralDefault", { attributes: {
-	[AccountSpans.name]: parts.accountName,
-	[AccountSpans.address]: parts.address,
-	[SuiSpans.mode]: parts.suiMode
-} }));
+});
 /** Apply the cross-cutting funding pass. Variant-agnostic — runs for
 *  every variant once the keypair / impersonation slot is bound and
 *  the address is known.
@@ -177,18 +163,8 @@ const applyCrossCuttingFunding = (parts) => Effect.gen(function* () {
 			outcome: "funded"
 		});
 	}
-	yield* Effect.annotateCurrentSpan({
-		[AccountSpans.name]: parts.accountName,
-		[AccountSpans.address]: parts.address,
-		[AccountSpans.fundCrossCuttingCount]: parts.funding.length,
-		[SuiSpans.chain]: parts.chainId
-	});
 	return applied;
-}).pipe(Effect.withSpan("devstack.plugin.account.applyCrossCuttingFunding", { attributes: {
-	[AccountSpans.name]: parts.accountName,
-	[AccountSpans.address]: parts.address,
-	[AccountSpans.fundCrossCuttingEntries]: parts.funding.length
-} }));
+});
 const readExistingBalance = (balanceReader, args) => balanceReader.readBalance(args);
 const waitForBalanceAtLeast = (parts) => {
 	const reader = parts.balanceReader;