@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/runtime/docker/sweep.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sweep.mjs","names":[],"sources":["../../../src/runtime/docker/sweep.ts"],"sourcesContent":["// Orphan sweep.\n//\n// Architecture § Container runtime § Sweep timing:\n//   The supervisor invokes `sweepOrphans` AT BOOT, BEFORE any plugin\n//   acquire fires. Sweep finds containers stamped with the engine's\n//   label tuple but with no live process holder, and reclaims them\n//   (force-remove) under `stack.lock`.\n//\n// Orphan = labelled with `(app, stack)` AND NOT in the active\n// container-claim ledger AND NOT held by any live peer.\n//\n// \"Live peer\" = roster holder whose PID+startTime liveness check\n// succeeds. The cross-process roster + claim-ledger is the authority;\n// we never use docker labels alone (a peer's container counts as\n// claimed even if our claim ledger is empty for it).\n\nimport { Effect } from 'effect';\n\nimport type { ContainerLabelTuple } from '../../contracts/snapshotable.ts';\nimport { readClaims, type ContainerClaim } from '../../substrate/runtime/cross-process/roster.ts';\nimport { acquireStackLock } from '../../substrate/runtime/cross-process/stack-lock.ts';\nimport { StackPathsService } from '../../substrate/runtime/paths.ts';\nimport {\n\tmakeSpacedRetrySchedule,\n\tNETWORK_REMOVE_RETRY_PROFILE,\n} from '../../substrate/runtime/retry-policy.ts';\nimport { DockerHost, DockerSpawner, dockerRunOk } from './client.ts';\nimport {\n\tContainerRemoveFailed,\n\tDaemonUnreachable,\n\tImageRemoveFailed,\n\tNetworkOperationFailed,\n\ttype DockerRuntimeError,\n} from './errors.ts';\nimport {\n\tlistContainers,\n\tlistDevstackContainers,\n\tlistDevstackContainersByKind,\n\tlistDevstackImages,\n\tlistDevstackNetworks,\n\tlistDevstackVolumes,\n\tlistImages,\n\tlistNetworks,\n\tlistVolumes,\n} from './inventory.ts';\nimport { LabelKey } from './labels.ts';\nimport {\n\tforceDisconnect,\n\tlistAttachedContainers,\n\ttype NetworkAttachedEndpoint,\n} from './network.ts';\nimport { removeVolume } from './volume.ts';\nimport {\n\tisMissingImageStderr,\n\tisMissingNetworkStderr,\n\tisNetworkInUseStderr,\n\tisNoSuchContainerStderr,\n\twrapGeneric,\n} from './wrap.ts';\n\nconst removeManagedContainer = (\n\tname: string,\n): Effect.Effect<boolean, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('rm', ['-f', name]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.rm')),\n\t\t);\n\t\tif (res.exitCode === 0) return true;\n\t\tif (isNoSuchContainerStderr(res.stderr)) return false;\n\t\treturn yield* Effect.fail(\n\t\t\tnew ContainerRemoveFailed({\n\t\t\t\tname,\n\t\t\t\tstderr: res.stderr,\n\t\t\t\texitCode: res.exitCode,\n\t\t\t}),\n\t\t);\n\t});\n\n/** Sweep orphan containers matching the partial label tuple. Returns\n *  the number of containers removed.\n *\n *  The sweep:\n *\n *    1. Lists all containers with the canonical `devstack.managed=true`\n *       + caller-supplied partial tuple (typically `{app, stack}`).\n *    2. Reads the container-claim ledger (the file held alongside\n *       roster.json; mutated only under stack.lock).\n *    3. Under stack.lock, removes any container whose name is NOT in\n *       the ledger.\n *\n *  Concurrent sweepers are serialized by stack.lock. The architecture\n *  says briefly here — we hold the lock only across the read + the\n *  remove decision; we DON'T hold it across the individual `docker\n *  rm` calls (which can be slow). The cost: a peer that registered a\n *  claim between our decision and our rm gets its container rm'd\n *  anyway. The mitigation: this only fires on the BOOT path before\n *  any plugin acquires, so the steady-state \"peer just claimed\" race\n *  is not in the picture. */\nexport const sweepOrphans = (\n\tlabelMatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner | StackPathsService> =>\n\tEffect.gen(function* () {\n\t\tconst paths = yield* StackPathsService;\n\t\tconst containers = yield* listContainers(labelMatch);\n\t\tif (containers.length === 0) return 0;\n\n\t\t// Under stack.lock, snapshot the claim ledger. The decision\n\t\t// (which to remove) happens here; the rm calls happen outside\n\t\t// the lock.\n\t\tconst mapSubstrateError = (cause: unknown): DockerRuntimeError =>\n\t\t\tnew DaemonUnreachable({\n\t\t\t\top: 'cross-process.sweep',\n\t\t\t\tdetail: `sweep substrate read failed: ${String(cause)}`,\n\t\t\t\tcause,\n\t\t\t});\n\t\tconst claimNames = yield* Effect.scoped(\n\t\t\tEffect.gen(function* () {\n\t\t\t\tyield* acquireStackLock(paths.stackLockFile).pipe(Effect.mapError(mapSubstrateError));\n\t\t\t\tconst doc = yield* readClaims({\n\t\t\t\t\tstackLockFile: paths.stackLockFile,\n\t\t\t\t\trosterFile: paths.rosterFile,\n\t\t\t\t\tcontainerClaimsFile: paths.containerClaimsFile,\n\t\t\t\t}).pipe(Effect.mapError(mapSubstrateError));\n\t\t\t\treturn new Set(doc.claims.map((c: ContainerClaim) => c.containerKey));\n\t\t\t}),\n\t\t);\n\n\t\t// Sweep — best-effort per container. Individual rm failures\n\t\t// don't poison the whole sweep, but they DO need operator\n\t\t// visibility: a broken docker socket would otherwise silently\n\t\t// swallow every entry. Surface the cause via `logWarning` so the\n\t\t// supervisor's cascade and structured-log consumers can investigate.\n\t\t// We reuse `removeManagedContainer` so the idempotent \"no such\n\t\t// container\" path (a container reaped between list+rm) doesn't\n\t\t// trip the warning logger.\n\t\tlet removed = 0;\n\t\tfor (const c of containers) {\n\t\t\tif (claimNames.has(c.name)) continue;\n\t\t\tconst didRemove = yield* removeManagedContainer(c.name).pipe(\n\t\t\t\tEffect.tapCause((cause) =>\n\t\t\t\t\tEffect.logWarning('sweep: docker rm -f failed', { name: c.name, cause }),\n\t\t\t\t),\n\t\t\t\tEffect.catch(() => Effect.succeed(false)),\n\t\t\t);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.sweep'));\n\n/** Explicit teardown. Unlike `sweepOrphans`, this does not consult the\n *  claim ledger; wipe/restore are intentional destructive operations. */\nexport const removeManagedContainers = (\n\tlabelMatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst containers = yield* listContainers(labelMatch);\n\t\tlet removed = 0;\n\t\tfor (const c of containers) {\n\t\t\tconst didRemove = yield* removeManagedContainer(c.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeManagedContainers'));\n\nconst labelsMatchAppStack = (\n\tlabels: Readonly<Record<string, string>>,\n\tmatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): boolean => labels[LabelKey.app] === match.app && labels[LabelKey.stack] === match.stack;\n\nexport const removeDevstackContainers = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst containers = yield* listDevstackContainers();\n\t\tlet removed = 0;\n\t\tfor (const c of containers) {\n\t\t\tif (!labelsMatchAppStack(c.labels, labelMatch)) continue;\n\t\t\tconst didRemove = yield* removeManagedContainer(c.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeDevstackContainers'));\n\n/** Remove devstack-managed containers whose generic `kind` label matches\n *  AND whose name matches. The L1 helper is plugin-blind: orchestrators\n *  pass the kind value they themselves stamp at create time. */\nexport const removeDevstackContainersByKindAndName = (\n\tkind: string,\n\tcontainerName: string,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst containers = yield* listDevstackContainersByKind(kind);\n\t\tlet removed = 0;\n\t\tfor (const c of containers) {\n\t\t\tif (c.name !== containerName) continue;\n\t\t\tconst didRemove = yield* removeManagedContainer(c.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeDevstackContainersByKindAndName'));\n\nconst removeManagedImage = (\n\tref: string,\n): Effect.Effect<boolean, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('image', ['rm', '-f', ref]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.image.rm')),\n\t\t);\n\t\tif (res.exitCode === 0) return true;\n\t\tif (isMissingImageStderr(res.stderr)) return false;\n\t\treturn yield* Effect.fail(\n\t\t\tnew ImageRemoveFailed({\n\t\t\t\tref,\n\t\t\t\tstderr: res.stderr,\n\t\t\t\texitCode: res.exitCode,\n\t\t\t}),\n\t\t);\n\t});\n\nexport const removeManagedImages = (\n\tlabelMatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst images = yield* listImages(labelMatch);\n\t\tlet removed = 0;\n\t\tconst seen = new Set<string>();\n\t\tfor (const image of images) {\n\t\t\tconst ref = image.tag;\n\t\t\tif (ref.endsWith(':<none>')) continue;\n\t\t\tif (seen.has(ref)) continue;\n\t\t\tseen.add(ref);\n\t\t\tconst didRemove = yield* removeManagedImage(ref);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeManagedImages'));\n\nexport const removeDevstackImages = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst images = yield* listDevstackImages();\n\t\tlet removed = 0;\n\t\tconst seen = new Set<string>();\n\t\tfor (const image of images) {\n\t\t\tif (!labelsMatchAppStack(image.labels, labelMatch)) continue;\n\t\t\tconst ref = image.tag;\n\t\t\tif (ref.endsWith(':<none>')) continue;\n\t\t\tif (seen.has(ref)) continue;\n\t\t\tseen.add(ref);\n\t\t\tconst didRemove = yield* removeManagedImage(ref);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeDevstackImages'));\n\nconst removeManagedNetwork = (\n\tname: string,\n): Effect.Effect<boolean, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('network', ['rm', name]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.network.rm')),\n\t\t);\n\t\tif (res.exitCode === 0) return true;\n\t\tif (isMissingNetworkStderr(res.stderr)) return false;\n\t\treturn yield* Effect.fail(\n\t\t\tnew NetworkOperationFailed({ op: 'remove', network: name, stderr: res.stderr }),\n\t\t);\n\t});\n\nexport const removeManagedNetworks = (\n\tlabelMatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst networks = yield* listNetworks(labelMatch);\n\t\tlet removed = 0;\n\t\tfor (const network of networks) {\n\t\t\tif (network.labels[LabelKey.networkMarker] !== 'true') continue;\n\t\t\tconst didRemove = yield* removeManagedNetwork(network.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeManagedNetworks'));\n\n/** Parse `network X has active endpoints (name:\"A\" id:\"B\")` stderr —\n *  Docker enumerates each blocking endpoint as a `(name:\"…\" id:\"…\")`\n *  tuple. Returns an empty array on non-matching stderr. */\nconst parseActiveEndpointsFromStderr = (\n\tstderr: string,\n): ReadonlyArray<{ readonly name: string; readonly id: string }> => {\n\tconst out: Array<{ name: string; id: string }> = [];\n\tconst re = /\\(name:\"([^\"]+)\"\\s+id:\"([^\"]+)\"\\)/g;\n\tlet m: RegExpExecArray | null;\n\twhile ((m = re.exec(stderr)) !== null) {\n\t\tout.push({ name: m[1]!, id: m[2]! });\n\t}\n\treturn out;\n};\n\n/** One foreign endpoint preventing a network from being removed —\n *  surfaced in the prune summary so the operator can investigate. */\nexport interface ForeignNetworkHolder {\n\treadonly network: string;\n\treadonly container: NetworkAttachedEndpoint;\n}\n\n/** A `(name, id)` reference that appears in Docker's `network rm`\n *  \"active endpoints\" error but is NOT addressable via `network\n *  disconnect -f` and does NOT appear in `network inspect`'s\n *  Containers map. Symptom of a Docker engine bug where the bridge\n *  driver leaks endpoint metadata for a container that no longer\n *  exists. Only a Docker daemon restart reclaims these. */\nexport interface StaleNetworkEndpoint {\n\treadonly network: string;\n\treadonly name: string;\n\treadonly id: string;\n}\n\ntype NetworkRemoveStep =\n\t| { readonly kind: 'removed' }\n\t| { readonly kind: 'missing' }\n\t| { readonly kind: 'in-use'; readonly stderr: string };\n\ntype NetworkRemoveOutcome =\n\t| { readonly kind: 'removed' }\n\t| { readonly kind: 'missing' }\n\t| {\n\t\t\treadonly kind: 'in-use';\n\t\t\treadonly foreignHolders: ReadonlyArray<NetworkAttachedEndpoint>;\n\t\t\treadonly staleEndpoints: ReadonlyArray<{ readonly name: string; readonly id: string }>;\n\t  };\n\nexport interface DevstackNetworkRemovalSummary {\n\treadonly removed: number;\n\treadonly skippedInUse: number;\n\treadonly foreignHolders: ReadonlyArray<ForeignNetworkHolder>;\n\treadonly staleEndpoints: ReadonlyArray<StaleNetworkEndpoint>;\n}\n\ninterface DevstackNetworkRemovalOptions {\n\treadonly retryAttempts?: number;\n\treadonly retryDelayMillis?: number;\n}\n\nconst removeManagedNetworkOnce = (\n\tname: string,\n): Effect.Effect<NetworkRemoveStep, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('network', ['rm', name]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.network.rm')),\n\t\t);\n\t\tif (res.exitCode === 0) return { kind: 'removed' as const };\n\t\tif (isMissingNetworkStderr(res.stderr)) return { kind: 'missing' as const };\n\t\tif (isNetworkInUseStderr(res.stderr)) {\n\t\t\treturn { kind: 'in-use' as const, stderr: res.stderr };\n\t\t}\n\t\treturn yield* Effect.fail(\n\t\t\tnew NetworkOperationFailed({ op: 'remove', network: name, stderr: res.stderr }),\n\t\t);\n\t});\n\n/** Best-effort network removal that actively evicts our own endpoints\n *  before declaring \"in-use\". Strategy on first in-use response:\n *    1. inspect the network for attached endpoints\n *    2. for each endpoint we own (`devstack.managed=true`), force-\n *       disconnect it\n *    3. retry `network rm`\n *  Anything still holding the network after that is reported as a\n *  foreign holder — typically a non-devstack container, a test fixture,\n *  or a sibling stack we deliberately left alone. */\nconst removeManagedNetworkBestEffort = (\n\tname: string,\n\toptions: Required<DevstackNetworkRemovalOptions>,\n): Effect.Effect<NetworkRemoveOutcome, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst first = yield* removeManagedNetworkOnce(name);\n\t\tif (first.kind !== 'in-use') return first;\n\t\t// Investigate, evict our own endpoints, retry.\n\t\tconst attachments = yield* listAttachedContainers(name).pipe(\n\t\t\tEffect.catch(() => Effect.succeed([] as ReadonlyArray<NetworkAttachedEndpoint>)),\n\t\t);\n\t\tif (attachments.length > 0) {\n\t\t\tconst ownedNames = new Set<string>();\n\t\t\tconst all = yield* listDevstackContainers().pipe(\n\t\t\t\tEffect.catch(() => Effect.succeed([] as ReadonlyArray<{ readonly name: string }>)),\n\t\t\t);\n\t\t\tfor (const c of all) ownedNames.add(c.name);\n\t\t\tfor (const attached of attachments) {\n\t\t\t\tif (!ownedNames.has(attached.name)) continue;\n\t\t\t\tyield* forceDisconnect(attached.name, name).pipe(\n\t\t\t\t\tEffect.tapCause((cause) =>\n\t\t\t\t\t\tEffect.logDebug('prune: force-disconnect failed; will retry rm anyway', {\n\t\t\t\t\t\t\tnetwork: name,\n\t\t\t\t\t\t\tcontainer: attached.name,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t\tEffect.catch(() => Effect.void),\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\t// Retry `network rm` after eviction — Effect.repeat with a\n\t\t// spaced schedule per §16 \"Balance / poll loop\" canonical\n\t\t// helper (substrate `NETWORK_REMOVE_RETRY_PROFILE`). User-\n\t\t// supplied `options.retryAttempts` / `retryDelayMillis`\n\t\t// override the profile defaults. `Schedule.recurs(N)` allows\n\t\t// N additional recurrences, so this retry block makes\n\t\t// `1 + retryAttempts` rm calls when persistently in-use. Counting\n\t\t// the pre-eviction `first` probe above, the worst-case in-use\n\t\t// total for this function is `2 + retryAttempts` rm invocations.\n\t\tconst lastStep: NetworkRemoveStep = yield* removeManagedNetworkOnce(name).pipe(\n\t\t\tEffect.repeat({\n\t\t\t\tschedule: makeSpacedRetrySchedule(options.retryDelayMillis, options.retryAttempts),\n\t\t\t\tuntil: (step): boolean => step.kind !== 'in-use',\n\t\t\t}),\n\t\t);\n\t\tif (lastStep.kind === 'removed') return { kind: 'removed' as const };\n\t\tif (lastStep.kind === 'missing') return { kind: 'missing' as const };\n\t\tconst lastStderr = lastStep.stderr;\n\t\t// Still in-use after our best effort — diagnose what's holding it.\n\t\tconst finalAttachments = yield* listAttachedContainers(name).pipe(\n\t\t\tEffect.catch(() => Effect.succeed([] as ReadonlyArray<NetworkAttachedEndpoint>)),\n\t\t);\n\t\tconst ownedNames = new Set<string>();\n\t\tconst all = yield* listDevstackContainers().pipe(\n\t\t\tEffect.catch(() => Effect.succeed([] as ReadonlyArray<{ readonly name: string }>)),\n\t\t);\n\t\tfor (const c of all) ownedNames.add(c.name);\n\t\tconst foreign = finalAttachments.filter((a) => !ownedNames.has(a.name));\n\t\t// Endpoints Docker mentions in the rm error but which DON'T\n\t\t// appear in inspect → stale metadata. The bridge driver kept\n\t\t// the endpoint record around after the container was reaped;\n\t\t// no CLI/API path can remove it. Operator must restart Docker.\n\t\tconst attachedNames = new Set(finalAttachments.map((a) => a.name));\n\t\tconst stale = parseActiveEndpointsFromStderr(lastStderr).filter(\n\t\t\t(ep) => !attachedNames.has(ep.name),\n\t\t);\n\t\treturn {\n\t\t\tkind: 'in-use' as const,\n\t\t\tforeignHolders: foreign,\n\t\t\tstaleEndpoints: stale,\n\t\t};\n\t});\n\nexport const removeDevstackNetworks = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst networks = yield* listDevstackNetworks();\n\t\tlet removed = 0;\n\t\tfor (const network of networks) {\n\t\t\tif (!labelsMatchAppStack(network.labels, labelMatch)) continue;\n\t\t\tconst didRemove = yield* removeManagedNetwork(network.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeDevstackNetworks'));\n\nexport const removeDevstackNetworksBestEffort = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n\toptions: DevstackNetworkRemovalOptions = {},\n): Effect.Effect<DevstackNetworkRemovalSummary, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst networks = yield* listDevstackNetworks();\n\t\tconst retryOptions = {\n\t\t\tretryAttempts: options.retryAttempts ?? NETWORK_REMOVE_RETRY_PROFILE.attempts,\n\t\t\tretryDelayMillis: options.retryDelayMillis ?? NETWORK_REMOVE_RETRY_PROFILE.delayMs,\n\t\t};\n\t\tlet removed = 0;\n\t\tlet skippedInUse = 0;\n\t\tconst foreignHolders: Array<ForeignNetworkHolder> = [];\n\t\tconst staleEndpoints: Array<StaleNetworkEndpoint> = [];\n\t\tfor (const network of networks) {\n\t\t\tif (!labelsMatchAppStack(network.labels, labelMatch)) continue;\n\t\t\tconst outcome = yield* removeManagedNetworkBestEffort(network.name, retryOptions);\n\t\t\tif (outcome.kind === 'removed') removed += 1;\n\t\t\telse if (outcome.kind === 'in-use') {\n\t\t\t\tskippedInUse += 1;\n\t\t\t\tfor (const container of outcome.foreignHolders) {\n\t\t\t\t\tforeignHolders.push({ network: network.name, container });\n\t\t\t\t}\n\t\t\t\tfor (const ep of outcome.staleEndpoints) {\n\t\t\t\t\tstaleEndpoints.push({ network: network.name, name: ep.name, id: ep.id });\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn { removed, skippedInUse, foreignHolders, staleEndpoints };\n\t}).pipe(Effect.withSpan('runtime.docker.removeDevstackNetworksBestEffort'));\n\nexport const removeManagedVolumes = (\n\tlabelMatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst volumes = yield* listVolumes(labelMatch);\n\t\tlet removed = 0;\n\t\tfor (const volume of volumes) {\n\t\t\tif (volume.labels[LabelKey.volumeMarker] !== 'true') continue;\n\t\t\t// Best-effort per volume: an in-use/locked volume must not poison\n\t\t\t// the loop and strand later volumes. Surface the cause via\n\t\t\t// `logWarning` for operator visibility, then continue.\n\t\t\tconst didRemove = yield* removeVolume(volume.name).pipe(\n\t\t\t\tEffect.tapCause((cause) =>\n\t\t\t\t\tEffect.logWarning('sweep: docker volume rm failed', { name: volume.name, cause }),\n\t\t\t\t),\n\t\t\t\tEffect.as(true),\n\t\t\t\tEffect.catch(() => Effect.succeed(false)),\n\t\t\t);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeManagedVolumes'));\n\nexport const removeDevstackVolumes = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst volumes = yield* listDevstackVolumes();\n\t\tlet removed = 0;\n\t\tfor (const volume of volumes) {\n\t\t\tif (!labelsMatchAppStack(volume.labels, labelMatch)) continue;\n\t\t\t// Best-effort per volume: an in-use/locked volume must not poison\n\t\t\t// the loop and strand later volumes. Surface the cause via\n\t\t\t// `logWarning` for operator visibility, then continue.\n\t\t\tconst didRemove = yield* removeVolume(volume.name).pipe(\n\t\t\t\tEffect.tapCause((cause) =>\n\t\t\t\t\tEffect.logWarning('sweep: docker volume rm failed', { name: volume.name, cause }),\n\t\t\t\t),\n\t\t\t\tEffect.as(true),\n\t\t\t\tEffect.catch(() => Effect.succeed(false)),\n\t\t\t);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeDevstackVolumes'));\n"],"mappings":"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"}
+{"version":3,"file":"sweep.mjs","names":[],"sources":["../../../src/runtime/docker/sweep.ts"],"sourcesContent":["// Managed-resource teardown.\n//\n// Explicit, label-scoped removal of devstack-managed containers, images,\n// networks, and volumes. These are the intentional destructive paths\n// (wipe / restore / cross-stack prune) — they match on the engine's\n// label tuple and force-remove, without consulting the cross-process\n// claim ledger.\n\nimport { Effect } from 'effect';\n\nimport type { ContainerLabelTuple } from '../../contracts/snapshotable.ts';\nimport {\n\tmakeSpacedRetrySchedule,\n\tNETWORK_REMOVE_RETRY_PROFILE,\n} from '../../substrate/runtime/retry-policy.ts';\nimport { DockerHost, DockerSpawner, dockerRunOk } from './client.ts';\nimport {\n\tContainerRemoveFailed,\n\tImageRemoveFailed,\n\tNetworkOperationFailed,\n\ttype DockerRuntimeError,\n} from './errors.ts';\nimport {\n\tlistContainers,\n\tlistDevstackContainers,\n\tlistDevstackContainersByKind,\n\tlistDevstackImages,\n\tlistDevstackNetworks,\n\tlistDevstackVolumes,\n\tlistImages,\n\tlistNetworks,\n\tlistVolumes,\n} from './inventory.ts';\nimport { LabelKey } from './labels.ts';\nimport {\n\tforceDisconnect,\n\tlistAttachedContainers,\n\ttype NetworkAttachedEndpoint,\n} from './network.ts';\nimport { removeVolume } from './volume.ts';\nimport {\n\tisMissingImageStderr,\n\tisMissingNetworkStderr,\n\tisNetworkInUseStderr,\n\tisNoSuchContainerStderr,\n\twrapGeneric,\n} from './wrap.ts';\n\nconst removeManagedContainer = (\n\tname: string,\n): Effect.Effect<boolean, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('rm', ['-f', name]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.rm')),\n\t\t);\n\t\tif (res.exitCode === 0) return true;\n\t\tif (isNoSuchContainerStderr(res.stderr)) return false;\n\t\treturn yield* Effect.fail(\n\t\t\tnew ContainerRemoveFailed({\n\t\t\t\tname,\n\t\t\t\tstderr: res.stderr,\n\t\t\t\texitCode: res.exitCode,\n\t\t\t}),\n\t\t);\n\t});\n\n/** Explicit teardown — force-removes managed containers matching the\n *  partial label tuple, regardless of claim-ledger entries. Wipe/restore\n *  are intentional destructive operations. */\nexport const removeManagedContainers = (\n\tlabelMatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst containers = yield* listContainers(labelMatch);\n\t\tlet removed = 0;\n\t\tfor (const c of containers) {\n\t\t\tconst didRemove = yield* removeManagedContainer(c.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t});\n\nconst labelsMatchAppStack = (\n\tlabels: Readonly<Record<string, string>>,\n\tmatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): boolean => labels[LabelKey.app] === match.app && labels[LabelKey.stack] === match.stack;\n\nexport const removeDevstackContainers = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst containers = yield* listDevstackContainers();\n\t\tlet removed = 0;\n\t\tfor (const c of containers) {\n\t\t\tif (!labelsMatchAppStack(c.labels, labelMatch)) continue;\n\t\t\tconst didRemove = yield* removeManagedContainer(c.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t});\n\n/** Remove devstack-managed containers whose generic `kind` label matches\n *  AND whose name matches. The L1 helper is plugin-blind: orchestrators\n *  pass the kind value they themselves stamp at create time. */\nexport const removeDevstackContainersByKindAndName = (\n\tkind: string,\n\tcontainerName: string,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst containers = yield* listDevstackContainersByKind(kind);\n\t\tlet removed = 0;\n\t\tfor (const c of containers) {\n\t\t\tif (c.name !== containerName) continue;\n\t\t\tconst didRemove = yield* removeManagedContainer(c.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t});\n\nconst removeManagedImage = (\n\tref: string,\n): Effect.Effect<boolean, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('image', ['rm', '-f', ref]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.image.rm')),\n\t\t);\n\t\tif (res.exitCode === 0) return true;\n\t\tif (isMissingImageStderr(res.stderr)) return false;\n\t\treturn yield* Effect.fail(\n\t\t\tnew ImageRemoveFailed({\n\t\t\t\tref,\n\t\t\t\tstderr: res.stderr,\n\t\t\t\texitCode: res.exitCode,\n\t\t\t}),\n\t\t);\n\t});\n\nexport const removeManagedImages = (\n\tlabelMatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst images = yield* listImages(labelMatch);\n\t\tlet removed = 0;\n\t\tconst seen = new Set<string>();\n\t\tfor (const image of images) {\n\t\t\tconst ref = image.tag;\n\t\t\tif (ref.endsWith(':<none>')) continue;\n\t\t\tif (seen.has(ref)) continue;\n\t\t\tseen.add(ref);\n\t\t\tconst didRemove = yield* removeManagedImage(ref);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t});\n\nexport const removeDevstackImages = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst images = yield* listDevstackImages();\n\t\tlet removed = 0;\n\t\tconst seen = new Set<string>();\n\t\tfor (const image of images) {\n\t\t\tif (!labelsMatchAppStack(image.labels, labelMatch)) continue;\n\t\t\tconst ref = image.tag;\n\t\t\tif (ref.endsWith(':<none>')) continue;\n\t\t\tif (seen.has(ref)) continue;\n\t\t\tseen.add(ref);\n\t\t\tconst didRemove = yield* removeManagedImage(ref);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t});\n\nconst removeManagedNetwork = (\n\tname: string,\n): Effect.Effect<boolean, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('network', ['rm', name]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.network.rm')),\n\t\t);\n\t\tif (res.exitCode === 0) return true;\n\t\tif (isMissingNetworkStderr(res.stderr)) return false;\n\t\treturn yield* Effect.fail(\n\t\t\tnew NetworkOperationFailed({ op: 'remove', network: name, stderr: res.stderr }),\n\t\t);\n\t});\n\nexport const removeManagedNetworks = (\n\tlabelMatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst networks = yield* listNetworks(labelMatch);\n\t\tlet removed = 0;\n\t\tfor (const network of networks) {\n\t\t\tif (network.labels[LabelKey.networkMarker] !== 'true') continue;\n\t\t\tconst didRemove = yield* removeManagedNetwork(network.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t});\n\n/** Parse `network X has active endpoints (name:\"A\" id:\"B\")` stderr —\n *  Docker enumerates each blocking endpoint as a `(name:\"…\" id:\"…\")`\n *  tuple. Returns an empty array on non-matching stderr. */\nconst parseActiveEndpointsFromStderr = (\n\tstderr: string,\n): ReadonlyArray<{ readonly name: string; readonly id: string }> => {\n\tconst out: Array<{ name: string; id: string }> = [];\n\tconst re = /\\(name:\"([^\"]+)\"\\s+id:\"([^\"]+)\"\\)/g;\n\tlet m: RegExpExecArray | null;\n\twhile ((m = re.exec(stderr)) !== null) {\n\t\tout.push({ name: m[1]!, id: m[2]! });\n\t}\n\treturn out;\n};\n\n/** One foreign endpoint preventing a network from being removed —\n *  surfaced in the prune summary so the operator can investigate. */\nexport interface ForeignNetworkHolder {\n\treadonly network: string;\n\treadonly container: NetworkAttachedEndpoint;\n}\n\n/** A `(name, id)` reference that appears in Docker's `network rm`\n *  \"active endpoints\" error but is NOT addressable via `network\n *  disconnect -f` and does NOT appear in `network inspect`'s\n *  Containers map. Symptom of a Docker engine bug where the bridge\n *  driver leaks endpoint metadata for a container that no longer\n *  exists. Only a Docker daemon restart reclaims these. */\nexport interface StaleNetworkEndpoint {\n\treadonly network: string;\n\treadonly name: string;\n\treadonly id: string;\n}\n\ntype NetworkRemoveStep =\n\t| { readonly kind: 'removed' }\n\t| { readonly kind: 'missing' }\n\t| { readonly kind: 'in-use'; readonly stderr: string };\n\ntype NetworkRemoveOutcome =\n\t| { readonly kind: 'removed' }\n\t| { readonly kind: 'missing' }\n\t| {\n\t\t\treadonly kind: 'in-use';\n\t\t\treadonly foreignHolders: ReadonlyArray<NetworkAttachedEndpoint>;\n\t\t\treadonly staleEndpoints: ReadonlyArray<{ readonly name: string; readonly id: string }>;\n\t  };\n\nexport interface DevstackNetworkRemovalSummary {\n\treadonly removed: number;\n\treadonly skippedInUse: number;\n\treadonly foreignHolders: ReadonlyArray<ForeignNetworkHolder>;\n\treadonly staleEndpoints: ReadonlyArray<StaleNetworkEndpoint>;\n}\n\ninterface DevstackNetworkRemovalOptions {\n\treadonly retryAttempts?: number;\n\treadonly retryDelayMillis?: number;\n}\n\nconst removeManagedNetworkOnce = (\n\tname: string,\n): Effect.Effect<NetworkRemoveStep, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('network', ['rm', name]).pipe(\n\t\t\tEffect.mapError(wrapGeneric('docker.network.rm')),\n\t\t);\n\t\tif (res.exitCode === 0) return { kind: 'removed' as const };\n\t\tif (isMissingNetworkStderr(res.stderr)) return { kind: 'missing' as const };\n\t\tif (isNetworkInUseStderr(res.stderr)) {\n\t\t\treturn { kind: 'in-use' as const, stderr: res.stderr };\n\t\t}\n\t\treturn yield* Effect.fail(\n\t\t\tnew NetworkOperationFailed({ op: 'remove', network: name, stderr: res.stderr }),\n\t\t);\n\t});\n\n/** Best-effort network removal that actively evicts our own endpoints\n *  before declaring \"in-use\". Strategy on first in-use response:\n *    1. inspect the network for attached endpoints\n *    2. for each endpoint we own (`devstack.managed=true`), force-\n *       disconnect it\n *    3. retry `network rm`\n *  Anything still holding the network after that is reported as a\n *  foreign holder — typically a non-devstack container, a test fixture,\n *  or a sibling stack we deliberately left alone. */\nconst removeManagedNetworkBestEffort = (\n\tname: string,\n\toptions: Required<DevstackNetworkRemovalOptions>,\n): Effect.Effect<NetworkRemoveOutcome, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst first = yield* removeManagedNetworkOnce(name);\n\t\tif (first.kind !== 'in-use') return first;\n\t\t// Investigate, evict our own endpoints, retry.\n\t\tconst attachments = yield* listAttachedContainers(name).pipe(\n\t\t\tEffect.catch(() => Effect.succeed([] as ReadonlyArray<NetworkAttachedEndpoint>)),\n\t\t);\n\t\tif (attachments.length > 0) {\n\t\t\tconst ownedNames = new Set<string>();\n\t\t\tconst all = yield* listDevstackContainers().pipe(\n\t\t\t\tEffect.catch(() => Effect.succeed([] as ReadonlyArray<{ readonly name: string }>)),\n\t\t\t);\n\t\t\tfor (const c of all) ownedNames.add(c.name);\n\t\t\tfor (const attached of attachments) {\n\t\t\t\tif (!ownedNames.has(attached.name)) continue;\n\t\t\t\tyield* forceDisconnect(attached.name, name).pipe(\n\t\t\t\t\tEffect.tapCause((cause) =>\n\t\t\t\t\t\tEffect.logDebug('prune: force-disconnect failed; will retry rm anyway', {\n\t\t\t\t\t\t\tnetwork: name,\n\t\t\t\t\t\t\tcontainer: attached.name,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t\tEffect.catch(() => Effect.void),\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t\t// Retry `network rm` after eviction — Effect.repeat with a\n\t\t// spaced schedule per §16 \"Balance / poll loop\" canonical\n\t\t// helper (substrate `NETWORK_REMOVE_RETRY_PROFILE`). User-\n\t\t// supplied `options.retryAttempts` / `retryDelayMillis`\n\t\t// override the profile defaults. `Schedule.recurs(N)` allows\n\t\t// N additional recurrences, so this retry block makes\n\t\t// `1 + retryAttempts` rm calls when persistently in-use. Counting\n\t\t// the pre-eviction `first` probe above, the worst-case in-use\n\t\t// total for this function is `2 + retryAttempts` rm invocations.\n\t\tconst lastStep: NetworkRemoveStep = yield* removeManagedNetworkOnce(name).pipe(\n\t\t\tEffect.repeat({\n\t\t\t\tschedule: makeSpacedRetrySchedule(options.retryDelayMillis, options.retryAttempts),\n\t\t\t\tuntil: (step): boolean => step.kind !== 'in-use',\n\t\t\t}),\n\t\t);\n\t\tif (lastStep.kind === 'removed') return { kind: 'removed' as const };\n\t\tif (lastStep.kind === 'missing') return { kind: 'missing' as const };\n\t\tconst lastStderr = lastStep.stderr;\n\t\t// Still in-use after our best effort — diagnose what's holding it.\n\t\tconst finalAttachments = yield* listAttachedContainers(name).pipe(\n\t\t\tEffect.catch(() => Effect.succeed([] as ReadonlyArray<NetworkAttachedEndpoint>)),\n\t\t);\n\t\tconst ownedNames = new Set<string>();\n\t\tconst all = yield* listDevstackContainers().pipe(\n\t\t\tEffect.catch(() => Effect.succeed([] as ReadonlyArray<{ readonly name: string }>)),\n\t\t);\n\t\tfor (const c of all) ownedNames.add(c.name);\n\t\tconst foreign = finalAttachments.filter((a) => !ownedNames.has(a.name));\n\t\t// Endpoints Docker mentions in the rm error but which DON'T\n\t\t// appear in inspect → stale metadata. The bridge driver kept\n\t\t// the endpoint record around after the container was reaped;\n\t\t// no CLI/API path can remove it. Operator must restart Docker.\n\t\tconst attachedNames = new Set(finalAttachments.map((a) => a.name));\n\t\tconst stale = parseActiveEndpointsFromStderr(lastStderr).filter(\n\t\t\t(ep) => !attachedNames.has(ep.name),\n\t\t);\n\t\treturn {\n\t\t\tkind: 'in-use' as const,\n\t\t\tforeignHolders: foreign,\n\t\t\tstaleEndpoints: stale,\n\t\t};\n\t});\n\nexport const removeDevstackNetworks = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst networks = yield* listDevstackNetworks();\n\t\tlet removed = 0;\n\t\tfor (const network of networks) {\n\t\t\tif (!labelsMatchAppStack(network.labels, labelMatch)) continue;\n\t\t\tconst didRemove = yield* removeManagedNetwork(network.name);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t});\n\nexport const removeDevstackNetworksBestEffort = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n\toptions: DevstackNetworkRemovalOptions = {},\n): Effect.Effect<DevstackNetworkRemovalSummary, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst networks = yield* listDevstackNetworks();\n\t\tconst retryOptions = {\n\t\t\tretryAttempts: options.retryAttempts ?? NETWORK_REMOVE_RETRY_PROFILE.attempts,\n\t\t\tretryDelayMillis: options.retryDelayMillis ?? NETWORK_REMOVE_RETRY_PROFILE.delayMs,\n\t\t};\n\t\tlet removed = 0;\n\t\tlet skippedInUse = 0;\n\t\tconst foreignHolders: Array<ForeignNetworkHolder> = [];\n\t\tconst staleEndpoints: Array<StaleNetworkEndpoint> = [];\n\t\tfor (const network of networks) {\n\t\t\tif (!labelsMatchAppStack(network.labels, labelMatch)) continue;\n\t\t\tconst outcome = yield* removeManagedNetworkBestEffort(network.name, retryOptions);\n\t\t\tif (outcome.kind === 'removed') removed += 1;\n\t\t\telse if (outcome.kind === 'in-use') {\n\t\t\t\tskippedInUse += 1;\n\t\t\t\tfor (const container of outcome.foreignHolders) {\n\t\t\t\t\tforeignHolders.push({ network: network.name, container });\n\t\t\t\t}\n\t\t\t\tfor (const ep of outcome.staleEndpoints) {\n\t\t\t\t\tstaleEndpoints.push({ network: network.name, name: ep.name, id: ep.id });\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn { removed, skippedInUse, foreignHolders, staleEndpoints };\n\t});\n\nexport const removeManagedVolumes = (\n\tlabelMatch: Partial<ContainerLabelTuple>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst volumes = yield* listVolumes(labelMatch);\n\t\tlet removed = 0;\n\t\tfor (const volume of volumes) {\n\t\t\tif (volume.labels[LabelKey.volumeMarker] !== 'true') continue;\n\t\t\t// Best-effort per volume: an in-use/locked volume must not poison\n\t\t\t// the loop and strand later volumes. Surface the cause via\n\t\t\t// `logWarning` for operator visibility, then continue.\n\t\t\tconst didRemove = yield* removeVolume(volume.name).pipe(\n\t\t\t\tEffect.tapCause((cause) =>\n\t\t\t\t\tEffect.logWarning('sweep: docker volume rm failed', { name: volume.name, cause }),\n\t\t\t\t),\n\t\t\t\tEffect.as(true),\n\t\t\t\tEffect.catch(() => Effect.succeed(false)),\n\t\t\t);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t});\n\nexport const removeDevstackVolumes = (\n\tlabelMatch: Pick<ContainerLabelTuple, 'app' | 'stack'>,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst volumes = yield* listDevstackVolumes();\n\t\tlet removed = 0;\n\t\tfor (const volume of volumes) {\n\t\t\tif (!labelsMatchAppStack(volume.labels, labelMatch)) continue;\n\t\t\t// Best-effort per volume: an in-use/locked volume must not poison\n\t\t\t// the loop and strand later volumes. Surface the cause via\n\t\t\t// `logWarning` for operator visibility, then continue.\n\t\t\tconst didRemove = yield* removeVolume(volume.name).pipe(\n\t\t\t\tEffect.tapCause((cause) =>\n\t\t\t\t\tEffect.logWarning('sweep: docker volume rm failed', { name: volume.name, cause }),\n\t\t\t\t),\n\t\t\t\tEffect.as(true),\n\t\t\t\tEffect.catch(() => Effect.succeed(false)),\n\t\t\t);\n\t\t\tif (didRemove) removed += 1;\n\t\t}\n\t\treturn removed;\n\t});\n"],"mappings":"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"}

package/dist/runtime/docker/volume.mjs

@@ -19,7 +19,7 @@ const removeVolume = (name) => Effect.gen(function* () {
 		volume: name,
 		stderr: res.stderr
 	}));
-}).pipe(Effect.withSpan("runtime.docker.volume.remove"));
+});
 //#endregion
 export { removeVolume };
 

package/dist/runtime/docker/volume.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"volume.mjs","names":[],"sources":["../../../src/runtime/docker/volume.ts"],"sourcesContent":["// Docker volume lifecycle.\n//\n// Architecture invariant: PRE-CREATE labelled volumes BEFORE the run\n// argv fires. Docker's lazy `-v <name>:<path>` produces UNLABELLED\n// volumes that no inventory enumeration can find. Bind mounts pass\n// through unchanged (host-owned paths).\n\nimport { Effect, Schema } from 'effect';\n\nimport type { ContainerLabelTuple } from '../../contracts/snapshotable.ts';\nimport { DockerHost, DockerSpawner, dockerRun, dockerRunOk } from './client.ts';\nimport {\n\ttype DockerRuntimeError,\n\tForeignDockerResource,\n\tVolumeOperationFailed,\n} from './errors.ts';\nimport { dockerInspectAndDecode } from './inspect-and-decode.ts';\nimport {\n\texpectedVolumeOwnershipLabels,\n\townershipMismatchDetail,\n\treadLabels,\n\trenderVolumeLabels,\n} from './labels.ts';\nimport { wrapVolumeError } from './wrap.ts';\n\ninterface VolumeInspectFacts {\n\treadonly name: string;\n\treadonly labels: Readonly<Record<string, string>>;\n}\n\nconst VolumeInspectSchema = Schema.Struct({\n\tName: Schema.String,\n\tLabels: Schema.optional(Schema.Unknown),\n});\n\nconst isNoSuchVolumeStderr = (stderr: string): boolean => /no such volume/i.test(stderr);\n\nconst inspectVolume = (\n\tname: string,\n): Effect.Effect<VolumeInspectFacts | null, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst decoded = yield* dockerInspectAndDecode({\n\t\t\tresourceKind: 'volume',\n\t\t\tname,\n\t\t\top: 'docker.volume.inspect',\n\t\t\tinspectCommand: dockerRunOk('volume', ['inspect', name]).pipe(\n\t\t\t\tEffect.mapError(wrapVolumeError('inspect', name)),\n\t\t\t),\n\t\t\tschema: VolumeInspectSchema,\n\t\t\tisMissingStderr: isNoSuchVolumeStderr,\n\t\t});\n\t\tif (decoded === null) return null;\n\t\treturn { name: decoded.Name, labels: readLabels(decoded.Labels) };\n\t});\n\nconst assertVolumeOwned = (\n\tname: string,\n\tfacts: VolumeInspectFacts,\n\ttuple: ContainerLabelTuple,\n): Effect.Effect<void, DockerRuntimeError> =>\n\tEffect.gen(function* () {\n\t\tconst expected = expectedVolumeOwnershipLabels(tuple);\n\t\tconst mismatch = ownershipMismatchDetail(expected, facts.labels);\n\t\tif (mismatch !== null) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew ForeignDockerResource({\n\t\t\t\t\tresource: 'volume',\n\t\t\t\t\tname,\n\t\t\t\t\texpected,\n\t\t\t\t\tactual: facts.labels,\n\t\t\t\t\tdetail: mismatch,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t});\n\n/** Idempotent `docker volume create`. Stamps the canonical label set.\n *  Returns the volume name on success. */\nexport const ensureVolume = (\n\tname: string,\n\ttuple: ContainerLabelTuple,\n): Effect.Effect<string, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst probe = yield* inspectVolume(name);\n\t\tif (probe !== null) {\n\t\t\tyield* assertVolumeOwned(name, probe, tuple);\n\t\t\treturn probe.name;\n\t\t}\n\t\tconst labelArgs = renderVolumeLabels(name, tuple).flatMap((l) => ['--label', l]);\n\t\tyield* dockerRun('volume', ['create', ...labelArgs, name]).pipe(\n\t\t\tEffect.mapError(wrapVolumeError('create', name)),\n\t\t);\n\t\treturn name;\n\t}).pipe(Effect.withSpan('runtime.docker.volume.ensure'));\n\nexport const removeVolume = (\n\tname: string,\n): Effect.Effect<void, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('volume', ['rm', '--force', name]).pipe(\n\t\t\tEffect.mapError(wrapVolumeError('remove', name)),\n\t\t);\n\t\t// \"no such volume\" is idempotent success.\n\t\tif (res.exitCode !== 0 && !/no such volume/i.test(res.stderr)) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew VolumeOperationFailed({ op: 'remove', volume: name, stderr: res.stderr }),\n\t\t\t);\n\t\t}\n\t}).pipe(Effect.withSpan('runtime.docker.volume.remove'));\n"],"mappings":";;;;;;AA8B4B,OAAO,OAAO;CACzC,MAAM,OAAO;CACb,QAAQ,OAAO,SAAS,OAAO,QAAQ;CACvC,CAAC;AA8DF,MAAa,gBACZ,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,MAAM,OAAO,YAAY,UAAU;EAAC;EAAM;EAAW;EAAK,CAAC,CAAC,KACjE,OAAO,SAAS,gBAAgB,UAAU,KAAK,CAAC,CAChD;AAED,KAAI,IAAI,aAAa,KAAK,CAAC,kBAAkB,KAAK,IAAI,OAAO,CAC5D,QAAO,OAAO,OAAO,KACpB,IAAI,sBAAsB;EAAE,IAAI;EAAU,QAAQ;EAAM,QAAQ,IAAI;EAAQ,CAAC,CAC7E;EAED,CAAC,KAAK,OAAO,SAAS,+BAA+B,CAAC"}
+{"version":3,"file":"volume.mjs","names":[],"sources":["../../../src/runtime/docker/volume.ts"],"sourcesContent":["// Docker volume lifecycle.\n//\n// Architecture invariant: PRE-CREATE labelled volumes BEFORE the run\n// argv fires. Docker's lazy `-v <name>:<path>` produces UNLABELLED\n// volumes that no inventory enumeration can find. Bind mounts pass\n// through unchanged (host-owned paths).\n\nimport { Effect, Schema } from 'effect';\n\nimport type { ContainerLabelTuple } from '../../contracts/snapshotable.ts';\nimport { DockerHost, DockerSpawner, dockerRun, dockerRunOk } from './client.ts';\nimport { type DockerRuntimeError, ForeignDockerResource, VolumeOperationFailed } from './errors.ts';\nimport { dockerInspectAndDecode } from './inspect-and-decode.ts';\nimport {\n\texpectedVolumeOwnershipLabels,\n\townershipMismatchDetail,\n\treadLabels,\n\trenderVolumeLabels,\n} from './labels.ts';\nimport { wrapVolumeError } from './wrap.ts';\n\ninterface VolumeInspectFacts {\n\treadonly name: string;\n\treadonly labels: Readonly<Record<string, string>>;\n}\n\nconst VolumeInspectSchema = Schema.Struct({\n\tName: Schema.String,\n\tLabels: Schema.optional(Schema.Unknown),\n});\n\nconst isNoSuchVolumeStderr = (stderr: string): boolean => /no such volume/i.test(stderr);\n\nconst inspectVolume = (\n\tname: string,\n): Effect.Effect<VolumeInspectFacts | null, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst decoded = yield* dockerInspectAndDecode({\n\t\t\tresourceKind: 'volume',\n\t\t\tname,\n\t\t\top: 'docker.volume.inspect',\n\t\t\tinspectCommand: dockerRunOk('volume', ['inspect', name]).pipe(\n\t\t\t\tEffect.mapError(wrapVolumeError('inspect', name)),\n\t\t\t),\n\t\t\tschema: VolumeInspectSchema,\n\t\t\tisMissingStderr: isNoSuchVolumeStderr,\n\t\t});\n\t\tif (decoded === null) return null;\n\t\treturn { name: decoded.Name, labels: readLabels(decoded.Labels) };\n\t});\n\nconst assertVolumeOwned = (\n\tname: string,\n\tfacts: VolumeInspectFacts,\n\ttuple: ContainerLabelTuple,\n): Effect.Effect<void, DockerRuntimeError> =>\n\tEffect.gen(function* () {\n\t\tconst expected = expectedVolumeOwnershipLabels(tuple);\n\t\tconst mismatch = ownershipMismatchDetail(expected, facts.labels);\n\t\tif (mismatch !== null) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew ForeignDockerResource({\n\t\t\t\t\tresource: 'volume',\n\t\t\t\t\tname,\n\t\t\t\t\texpected,\n\t\t\t\t\tactual: facts.labels,\n\t\t\t\t\tdetail: mismatch,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t});\n\n/** Idempotent `docker volume create`. Stamps the canonical label set.\n *  Returns the volume name on success. */\nexport const ensureVolume = (\n\tname: string,\n\ttuple: ContainerLabelTuple,\n): Effect.Effect<string, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst probe = yield* inspectVolume(name);\n\t\tif (probe !== null) {\n\t\t\tyield* assertVolumeOwned(name, probe, tuple);\n\t\t\treturn probe.name;\n\t\t}\n\t\tconst labelArgs = renderVolumeLabels(name, tuple).flatMap((l) => ['--label', l]);\n\t\tyield* dockerRun('volume', ['create', ...labelArgs, name]).pipe(\n\t\t\tEffect.mapError(wrapVolumeError('create', name)),\n\t\t);\n\t\treturn name;\n\t});\n\nexport const removeVolume = (\n\tname: string,\n): Effect.Effect<void, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst res = yield* dockerRunOk('volume', ['rm', '--force', name]).pipe(\n\t\t\tEffect.mapError(wrapVolumeError('remove', name)),\n\t\t);\n\t\t// \"no such volume\" is idempotent success.\n\t\tif (res.exitCode !== 0 && !/no such volume/i.test(res.stderr)) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew VolumeOperationFailed({ op: 'remove', volume: name, stderr: res.stderr }),\n\t\t\t);\n\t\t}\n\t});\n"],"mappings":";;;;;;AA0B4B,OAAO,OAAO;CACzC,MAAM,OAAO;CACb,QAAQ,OAAO,SAAS,OAAO,OAAO;AACvC,CAAC;AA8DD,MAAa,gBACZ,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,MAAM,OAAO,YAAY,UAAU;EAAC;EAAM;EAAW;CAAI,CAAC,CAAC,CAAC,KACjE,OAAO,SAAS,gBAAgB,UAAU,IAAI,CAAC,CAChD;CAEA,IAAI,IAAI,aAAa,KAAK,CAAC,kBAAkB,KAAK,IAAI,MAAM,GAC3D,OAAO,OAAO,OAAO,KACpB,IAAI,sBAAsB;EAAE,IAAI;EAAU,QAAQ;EAAM,QAAQ,IAAI;CAAO,CAAC,CAC7E;AAEF,CAAC"}

package/dist/runtime/docker/wrap.mjs

@@ -26,8 +26,16 @@ const isNetworkAlreadyExistsStderr = (stderr) => /network with name \S+ already
 /** Docker bridge IPAM exhaustion. This is a stale-network / missing
 *  explicit-subnet policy failure, not a daemon reachability failure. */
 const isNetworkAddressPoolExhaustedStderr = (stderr) => /all predefined address pools have been fully subnetted/i.test(stderr);
-/** Image not found — pull or inspect against an unknown ref. */
-const isImageNotFoundStderr = (stderr) => /pull access denied/i.test(stderr) || /manifest .* not found/i.test(stderr) || /repository .* not found/i.test(stderr) || /No such image/i.test(stderr);
+/** Image not found — pull or inspect against an unknown ref. Also
+*  covers the implicit-pull-on-create case: `docker run` against a
+*  local-only image name that isn't present (an interrupted restore
+*  left the target image un-promoted, or a locally-built image was
+*  GC'd) tries an implicit registry pull and fails with `Unable to
+*  find image '<ref>' locally` followed by a `manifest unknown` /
+*  `pull access denied` line. Matching these here lets `wrapCreateError`
+*  surface a typed, recoverable `ImageNotFound` instead of an opaque
+*  fatal `ContainerCreateFailed`. */
+const isImageNotFoundStderr = (stderr) => /pull access denied/i.test(stderr) || /manifest .* not found/i.test(stderr) || /manifest unknown/i.test(stderr) || /repository .* not found/i.test(stderr) || /Unable to find image/i.test(stderr) || /No such image/i.test(stderr);
 /** Image missing — classifier for `docker image rm` / `docker tag`
 *  flows. Matches the daemon's canonical wording only — a bare
 *  `/not found/` alternation would misclassify permission-denied and
@@ -98,6 +106,10 @@ const wrapCreateError = (name) => (err) => {
 		stderr: err.stderr,
 		exitCode: err.exitCode
 	});
+	if (isImageNotFoundStderr(err.stderr)) return new ImageNotFound({
+		ref: name,
+		detail: "create target image not present locally"
+	});
 	return new ContainerCreateFailed({
 		name,
 		stderr: err.stderr,

package/dist/runtime/docker/wrap.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"wrap.mjs","names":[],"sources":["../../../src/runtime/docker/wrap.ts"],"sourcesContent":["// Subprocess-capture → typed docker-error translation.\n//\n// Architecture inverts the legacy \"stderr-pattern wording\" coupling:\n// instead of every plugin staring at stderr substrings, we classify\n// in ONE place and surface typed errors. Plugins consume typed errors\n// (`ImageNotFound`, `BuildFailed`, …) and never see raw stderr text\n// outside the error envelope's `detail` field.\n//\n// Stderr classifiers are kept here, not scattered. New runtime\n// backends (podman / finch) ship their own dialect of the classifier\n// set; the typed-error surface is the same.\n\nimport type {\n\tCaptureError,\n\tCaptureResult,\n} from '../../substrate/runtime/observability/subprocess-capture.ts';\nimport {\n\tBuildFailed,\n\tContainerCreateFailed,\n\tContainerNameCollisionUnrecoverable,\n\tContainerPortPublishConflict,\n\tDaemonUnreachable,\n\ttype DockerRuntimeError,\n\tImageNotFound,\n\tImagePullFailed,\n\tNetworkAddressPoolExhausted,\n\tNetworkOperationFailed,\n\tVolumeOperationFailed,\n} from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Classifiers\n// -----------------------------------------------------------------------------\n\n/** Daemon unreachable — the connection itself failed. Highest-priority\n *  classifier; if this is true, no further classification is meaningful. */\nexport const isDaemonUnreachableStderr = (stderr: string): boolean =>\n\t/Cannot connect to the Docker daemon/i.test(stderr) ||\n\t/Is the docker daemon running\\?/i.test(stderr) ||\n\t/ENOENT.*docker/i.test(stderr);\n\n/** Name collision — `docker create` / `run -d` returns exit 125 with\n *  \"name is already in use\" wording. Architecture §1 — name-atomic create. */\nexport const isNameCollisionStderr = (stderr: string): boolean =>\n\t/is already in use by container/i.test(stderr) || /Conflict.*The container name/i.test(stderr);\n\n/** Port conflict — used by container resume-fallback path. */\nexport const isPortConflictStderr = (stderr: string): boolean =>\n\t/port is already allocated/i.test(stderr) || /bind.*address already in use/i.test(stderr);\n\n/** \"No such container\" — TOCTOU recovery signal. */\nexport const isNoSuchContainerStderr = (stderr: string): boolean =>\n\t/No such container/i.test(stderr) ||\n\t/Error response from daemon: No such container/i.test(stderr) ||\n\t/no such object/i.test(stderr);\n\n/** Network attach idempotency — \"already exists in network\" is success. */\nexport const isAlreadyInNetworkStderr = (stderr: string): boolean =>\n\t/already exists in network/i.test(stderr) || /endpoint with name .* already exists/i.test(stderr);\n\n/** Network-create collision — `docker network create` is NOT name-atomic\n *  and there is no per-name lock for networks, so two processes booting\n *  against the shared `devstack` bridge can both pass the inspect-miss and\n *  both run `create`; the loser sees this stderr. Matches the daemon's\n *  canonical wording `network with name <name> already exists` plus the\n *  `Conflict` (409) envelope libnetwork returns for the same condition.\n *  Distinct from `isAlreadyInNetworkStderr` (the connect-side\n *  endpoint-already-attached case) — this is the network object itself\n *  already existing, the signal for `ensureNetwork`'s adopt-on-collision\n *  re-inspect. */\nexport const isNetworkAlreadyExistsStderr = (stderr: string): boolean =>\n\t/network with name \\S+ already exists/i.test(stderr) ||\n\t/Conflict.*network/i.test(stderr) ||\n\t/network \\S+ already exists/i.test(stderr);\n\n/** Docker bridge IPAM exhaustion. This is a stale-network / missing\n *  explicit-subnet policy failure, not a daemon reachability failure. */\nexport const isNetworkAddressPoolExhaustedStderr = (stderr: string): boolean =>\n\t/all predefined address pools have been fully subnetted/i.test(stderr);\n\n/** Image not found — pull or inspect against an unknown ref. */\nexport const isImageNotFoundStderr = (stderr: string): boolean =>\n\t/pull access denied/i.test(stderr) ||\n\t/manifest .* not found/i.test(stderr) ||\n\t/repository .* not found/i.test(stderr) ||\n\t/No such image/i.test(stderr);\n\n/** Image missing — classifier for `docker image rm` / `docker tag`\n *  flows. Matches the daemon's canonical wording only — a bare\n *  `/not found/` alternation would misclassify permission-denied and\n *  registry-auth errors (e.g. `pull access denied … repository does\n *  not exist`) as \"missing\" and let sweep silently skip them. Distinct\n *  from `isImageNotFoundStderr` (pull-flow-specific) — this one is the\n *  union used by idempotent remove/tag paths. */\nexport const isMissingImageStderr = (stderr: string): boolean =>\n\t/no such image|reference does not exist/i.test(stderr);\n\n/** Network missing — idempotent classifier for `docker network rm` /\n *  `docker network inspect`. Matches the daemon's canonical wordings:\n *  `No such network: <name>` and `network <name> not found`. A bare\n *  `/not found/` alternation would misclassify auth / permission errors\n *  on shared docker hosts. */\nexport const isMissingNetworkStderr = (stderr: string): boolean =>\n\t/no such network|network \\S+ not found/i.test(stderr);\n\n/** Network in-use — `docker network rm` failed because endpoints are\n *  still attached. Inverse predicate of `isMissingNetworkStderr`; lives\n *  next to its siblings so the two evolve together. */\nexport const isNetworkInUseStderr = (stderr: string): boolean =>\n\t/active endpoints|has active endpoint|network .* is in use/i.test(stderr);\n\n// -----------------------------------------------------------------------------\n// Wrappers — translate CaptureError → typed DockerRuntimeError\n// -----------------------------------------------------------------------------\n\n/** Daemon-unreachable check is the universal short-circuit. Every\n *  wrapper runs this first. */\nconst checkDaemon = (err: CaptureError): DaemonUnreachable | null => {\n\tif (isDaemonUnreachableStderr(err.stderr)) {\n\t\treturn new DaemonUnreachable({\n\t\t\top: err.op,\n\t\t\tdetail: 'docker daemon unreachable',\n\t\t\tcause: err.cause,\n\t\t});\n\t}\n\tif (err.cause !== undefined && err.exitCode === undefined) {\n\t\treturn new DaemonUnreachable({\n\t\t\top: err.op,\n\t\t\tdetail: 'docker CLI spawn failed (binary missing or fork failure)',\n\t\t\tcause: err.cause,\n\t\t});\n\t}\n\treturn null;\n};\n\nexport const wrapPullError =\n\t(ref: string) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\tif (isImageNotFoundStderr(err.stderr)) {\n\t\t\treturn new ImageNotFound({ ref, detail: 'pull target not found' });\n\t\t}\n\t\treturn new ImagePullFailed({ ref, stderr: err.stderr, exitCode: err.exitCode });\n\t};\n\nexport const wrapBuildError =\n\t(contextPath: string, dockerfile: string | undefined) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\t// STUB: best-effort parse of `Step <n>/<m> : <line>` from a\n\t\t// buildkit / classic builder log. The architecture allows this\n\t\t// to be empty — the raw stderr is still surfaced in `detail`.\n\t\t// Follow-up: extract from buildkit's `#<n> ERROR: …` envelope.\n\t\tconst parsedStep = parseFailingBuildStep(err.stdout, err.stderr);\n\t\treturn new BuildFailed({\n\t\t\tcontextPath,\n\t\t\tdockerfile,\n\t\t\tstderr: err.stderr,\n\t\t\tparsedStep,\n\t\t\texitCode: err.exitCode,\n\t\t});\n\t};\n\nexport const wrapCreateError =\n\t(name: string) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\tif (isNameCollisionStderr(err.stderr)) {\n\t\t\t// Architecture §1: surface the collision typed so the\n\t\t\t// state machine can decide adopt vs typed-failure. The\n\t\t\t// `Unrecoverable` variant fires only AFTER the start-and-\n\t\t\t// adopt fallback has exhausted; here we signal the collision\n\t\t\t// for the caller to handle.\n\t\t\treturn new ContainerNameCollisionUnrecoverable({\n\t\t\t\tname,\n\t\t\t\tdetail: 'name collision; caller should attempt adopt fallback',\n\t\t\t});\n\t\t}\n\t\tif (isPortConflictStderr(err.stderr)) {\n\t\t\treturn new ContainerPortPublishConflict({\n\t\t\t\tname,\n\t\t\t\tstderr: err.stderr,\n\t\t\t\texitCode: err.exitCode,\n\t\t\t});\n\t\t}\n\t\treturn new ContainerCreateFailed({ name, stderr: err.stderr, exitCode: err.exitCode });\n\t};\n\nexport const wrapNetworkError =\n\t(op: 'create' | 'connect' | 'disconnect' | 'inspect' | 'remove', network: string) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\tif (op === 'create' && isNetworkAddressPoolExhaustedStderr(err.stderr)) {\n\t\t\treturn new NetworkAddressPoolExhausted({\n\t\t\t\tnetwork,\n\t\t\t\tstderr: err.stderr,\n\t\t\t\thint: 'Docker exhausted its predefined bridge address pools. Remove stale devstack networks with wipe/prune (for example `docker network prune`) or request an explicit non-overlapping subnet/gateway.',\n\t\t\t});\n\t\t}\n\t\treturn new NetworkOperationFailed({ op, network, stderr: err.stderr });\n\t};\n\nexport const wrapVolumeError =\n\t(op: 'create' | 'inspect' | 'remove', volume: string) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\treturn new VolumeOperationFailed({ op, volume, stderr: err.stderr });\n\t};\n\n/** Generic wrapper for op surfaces (`docker logs`, `docker inspect`,\n *  etc.) where the only distinct failure mode is daemon down. */\nexport const wrapGeneric =\n\t(op: string) =>\n\t(err: CaptureError): DockerRuntimeError =>\n\t\tcheckDaemon(err) ??\n\t\tnew DaemonUnreachable({\n\t\t\top,\n\t\t\tdetail: err.stderr || `${op} failed (exit ${err.exitCode ?? '?'})`,\n\t\t\tcause: err.cause,\n\t\t});\n\n// -----------------------------------------------------------------------------\n// Helpers\n// -----------------------------------------------------------------------------\n\n/** STUB: extract a \"failing step\" line from build output. The\n *  buildkit envelope shape is documented; classic builder shape is\n *  `Step N/M : <directive>`. Returning `undefined` is fine — the raw\n *  stderr is still in the BuildFailed envelope. */\nconst parseFailingBuildStep = (stdout: string, stderr: string): string | undefined => {\n\tconst combined = `${stderr}\\n${stdout}`;\n\tconst classic = combined.match(/Step (\\d+)\\/(\\d+)\\s*:\\s*([^\\n]+)/);\n\tif (classic) return `Step ${classic[1]}/${classic[2]} ${classic[3]}`;\n\tconst buildkit = combined.match(/#(\\d+)\\s+ERROR\\s*:\\s*([^\\n]+)/);\n\tif (buildkit) return `#${buildkit[1]} ${buildkit[2]}`;\n\treturn undefined;\n};\n\n/** Inspect a `CaptureResult`'s exit code; if non-zero return null\n *  (caller decides what to do). Used by the lifecycle state machine\n *  to classify stderr patterns WITHOUT promoting non-zero to failure\n *  via `nonZeroIsFailure`. */\nexport const classifyExit = (\n\tres: CaptureResult,\n): { readonly ok: boolean; readonly exitCode: number; readonly stderr: string } => ({\n\tok: res.exitCode === 0,\n\texitCode: res.exitCode,\n\tstderr: res.stderr,\n});\n"],"mappings":";;;;AAoCA,MAAa,6BAA6B,WACzC,uCAAuC,KAAK,OAAO,IACnD,kCAAkC,KAAK,OAAO,IAC9C,kBAAkB,KAAK,OAAO;;;AAI/B,MAAa,yBAAyB,WACrC,kCAAkC,KAAK,OAAO,IAAI,gCAAgC,KAAK,OAAO;;AAG/F,MAAa,wBAAwB,WACpC,6BAA6B,KAAK,OAAO,IAAI,gCAAgC,KAAK,OAAO;;AAG1F,MAAa,2BAA2B,WACvC,qBAAqB,KAAK,OAAO,IACjC,iDAAiD,KAAK,OAAO,IAC7D,kBAAkB,KAAK,OAAO;;AAG/B,MAAa,4BAA4B,WACxC,6BAA6B,KAAK,OAAO,IAAI,wCAAwC,KAAK,OAAO;;;;;;;;;;;AAYlG,MAAa,gCAAgC,WAC5C,wCAAwC,KAAK,OAAO,IACpD,qBAAqB,KAAK,OAAO,IACjC,8BAA8B,KAAK,OAAO;;;AAI3C,MAAa,uCAAuC,WACnD,0DAA0D,KAAK,OAAO;;AAGvE,MAAa,yBAAyB,WACrC,sBAAsB,KAAK,OAAO,IAClC,yBAAyB,KAAK,OAAO,IACrC,2BAA2B,KAAK,OAAO,IACvC,iBAAiB,KAAK,OAAO;;;;;;;;AAS9B,MAAa,wBAAwB,WACpC,0CAA0C,KAAK,OAAO;;;;;;AAOvD,MAAa,0BAA0B,WACtC,yCAAyC,KAAK,OAAO;;;;AAKtD,MAAa,wBAAwB,WACpC,6DAA6D,KAAK,OAAO;;;AAQ1E,MAAM,eAAe,QAAgD;AACpE,KAAI,0BAA0B,IAAI,OAAO,CACxC,QAAO,IAAI,kBAAkB;EAC5B,IAAI,IAAI;EACR,QAAQ;EACR,OAAO,IAAI;EACX,CAAC;AAEH,KAAI,IAAI,UAAU,KAAA,KAAa,IAAI,aAAa,KAAA,EAC/C,QAAO,IAAI,kBAAkB;EAC5B,IAAI,IAAI;EACR,QAAQ;EACR,OAAO,IAAI;EACX,CAAC;AAEH,QAAO;;AAGR,MAAa,iBACX,SACA,QAA0C;CAC1C,MAAM,IAAI,YAAY,IAAI;AAC1B,KAAI,EAAG,QAAO;AACd,KAAI,sBAAsB,IAAI,OAAO,CACpC,QAAO,IAAI,cAAc;EAAE;EAAK,QAAQ;EAAyB,CAAC;AAEnE,QAAO,IAAI,gBAAgB;EAAE;EAAK,QAAQ,IAAI;EAAQ,UAAU,IAAI;EAAU,CAAC;;AAGjF,MAAa,kBACX,aAAqB,gBACrB,QAA0C;CAC1C,MAAM,IAAI,YAAY,IAAI;AAC1B,KAAI,EAAG,QAAO;CAKd,MAAM,aAAa,sBAAsB,IAAI,QAAQ,IAAI,OAAO;AAChE,QAAO,IAAI,YAAY;EACtB;EACA;EACA,QAAQ,IAAI;EACZ;EACA,UAAU,IAAI;EACd,CAAC;;AAGJ,MAAa,mBACX,UACA,QAA0C;CAC1C,MAAM,IAAI,YAAY,IAAI;AAC1B,KAAI,EAAG,QAAO;AACd,KAAI,sBAAsB,IAAI,OAAO,CAMpC,QAAO,IAAI,oCAAoC;EAC9C;EACA,QAAQ;EACR,CAAC;AAEH,KAAI,qBAAqB,IAAI,OAAO,CACnC,QAAO,IAAI,6BAA6B;EACvC;EACA,QAAQ,IAAI;EACZ,UAAU,IAAI;EACd,CAAC;AAEH,QAAO,IAAI,sBAAsB;EAAE;EAAM,QAAQ,IAAI;EAAQ,UAAU,IAAI;EAAU,CAAC;;AAGxF,MAAa,oBACX,IAAgE,aAChE,QAA0C;CAC1C,MAAM,IAAI,YAAY,IAAI;AAC1B,KAAI,EAAG,QAAO;AACd,KAAI,OAAO,YAAY,oCAAoC,IAAI,OAAO,CACrE,QAAO,IAAI,4BAA4B;EACtC;EACA,QAAQ,IAAI;EACZ,MAAM;EACN,CAAC;AAEH,QAAO,IAAI,uBAAuB;EAAE;EAAI;EAAS,QAAQ,IAAI;EAAQ,CAAC;;AAGxE,MAAa,mBACX,IAAqC,YACrC,QAA0C;CAC1C,MAAM,IAAI,YAAY,IAAI;AAC1B,KAAI,EAAG,QAAO;AACd,QAAO,IAAI,sBAAsB;EAAE;EAAI;EAAQ,QAAQ,IAAI;EAAQ,CAAC;;;;AAKtE,MAAa,eACX,QACA,QACA,YAAY,IAAI,IAChB,IAAI,kBAAkB;CACrB;CACA,QAAQ,IAAI,UAAU,GAAG,GAAG,gBAAgB,IAAI,YAAY,IAAI;CAChE,OAAO,IAAI;CACX,CAAC;;;;;AAUJ,MAAM,yBAAyB,QAAgB,WAAuC;CACrF,MAAM,WAAW,GAAG,OAAO,IAAI;CAC/B,MAAM,UAAU,SAAS,MAAM,mCAAmC;AAClE,KAAI,QAAS,QAAO,QAAQ,QAAQ,GAAG,GAAG,QAAQ,GAAG,GAAG,QAAQ;CAChE,MAAM,WAAW,SAAS,MAAM,gCAAgC;AAChE,KAAI,SAAU,QAAO,IAAI,SAAS,GAAG,GAAG,SAAS;;;;;;AAQlD,MAAa,gBACZ,SACmF;CACnF,IAAI,IAAI,aAAa;CACrB,UAAU,IAAI;CACd,QAAQ,IAAI;CACZ"}
+{"version":3,"file":"wrap.mjs","names":[],"sources":["../../../src/runtime/docker/wrap.ts"],"sourcesContent":["// Subprocess-capture → typed docker-error translation.\n//\n// Instead of every plugin staring at stderr substrings, classification\n// happens in ONE place and surfaces typed errors. Plugins consume typed errors\n// (`ImageNotFound`, `BuildFailed`, …) and never see raw stderr text\n// outside the error envelope's `detail` field.\n//\n// Stderr classifiers are kept here, not scattered. New runtime\n// backends (podman / finch) ship their own dialect of the classifier\n// set; the typed-error surface is the same.\n\nimport type {\n\tCaptureError,\n\tCaptureResult,\n} from '../../substrate/runtime/observability/subprocess-capture.ts';\nimport {\n\tBuildFailed,\n\tContainerCreateFailed,\n\tContainerNameCollisionUnrecoverable,\n\tContainerPortPublishConflict,\n\tDaemonUnreachable,\n\ttype DockerRuntimeError,\n\tImageNotFound,\n\tImagePullFailed,\n\tNetworkAddressPoolExhausted,\n\tNetworkOperationFailed,\n\tVolumeOperationFailed,\n} from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Classifiers\n// -----------------------------------------------------------------------------\n\n/** Daemon unreachable — the connection itself failed. Highest-priority\n *  classifier; if this is true, no further classification is meaningful. */\nexport const isDaemonUnreachableStderr = (stderr: string): boolean =>\n\t/Cannot connect to the Docker daemon/i.test(stderr) ||\n\t/Is the docker daemon running\\?/i.test(stderr) ||\n\t/ENOENT.*docker/i.test(stderr);\n\n/** Name collision — `docker create` / `run -d` returns exit 125 with\n *  \"name is already in use\" wording. Architecture §1 — name-atomic create. */\nexport const isNameCollisionStderr = (stderr: string): boolean =>\n\t/is already in use by container/i.test(stderr) || /Conflict.*The container name/i.test(stderr);\n\n/** Port conflict — used by container resume-fallback path. */\nexport const isPortConflictStderr = (stderr: string): boolean =>\n\t/port is already allocated/i.test(stderr) || /bind.*address already in use/i.test(stderr);\n\n/** \"No such container\" — TOCTOU recovery signal. */\nexport const isNoSuchContainerStderr = (stderr: string): boolean =>\n\t/No such container/i.test(stderr) ||\n\t/Error response from daemon: No such container/i.test(stderr) ||\n\t/no such object/i.test(stderr);\n\n/** Network attach idempotency — \"already exists in network\" is success. */\nexport const isAlreadyInNetworkStderr = (stderr: string): boolean =>\n\t/already exists in network/i.test(stderr) || /endpoint with name .* already exists/i.test(stderr);\n\n/** Network-create collision — `docker network create` is NOT name-atomic\n *  and there is no per-name lock for networks, so two processes booting\n *  against the shared `devstack` bridge can both pass the inspect-miss and\n *  both run `create`; the loser sees this stderr. Matches the daemon's\n *  canonical wording `network with name <name> already exists` plus the\n *  `Conflict` (409) envelope libnetwork returns for the same condition.\n *  Distinct from `isAlreadyInNetworkStderr` (the connect-side\n *  endpoint-already-attached case) — this is the network object itself\n *  already existing, the signal for `ensureNetwork`'s adopt-on-collision\n *  re-inspect. */\nexport const isNetworkAlreadyExistsStderr = (stderr: string): boolean =>\n\t/network with name \\S+ already exists/i.test(stderr) ||\n\t/Conflict.*network/i.test(stderr) ||\n\t/network \\S+ already exists/i.test(stderr);\n\n/** Docker bridge IPAM exhaustion. This is a stale-network / missing\n *  explicit-subnet policy failure, not a daemon reachability failure. */\nexport const isNetworkAddressPoolExhaustedStderr = (stderr: string): boolean =>\n\t/all predefined address pools have been fully subnetted/i.test(stderr);\n\n/** Image not found — pull or inspect against an unknown ref. Also\n *  covers the implicit-pull-on-create case: `docker run` against a\n *  local-only image name that isn't present (an interrupted restore\n *  left the target image un-promoted, or a locally-built image was\n *  GC'd) tries an implicit registry pull and fails with `Unable to\n *  find image '<ref>' locally` followed by a `manifest unknown` /\n *  `pull access denied` line. Matching these here lets `wrapCreateError`\n *  surface a typed, recoverable `ImageNotFound` instead of an opaque\n *  fatal `ContainerCreateFailed`. */\nexport const isImageNotFoundStderr = (stderr: string): boolean =>\n\t/pull access denied/i.test(stderr) ||\n\t/manifest .* not found/i.test(stderr) ||\n\t/manifest unknown/i.test(stderr) ||\n\t/repository .* not found/i.test(stderr) ||\n\t/Unable to find image/i.test(stderr) ||\n\t/No such image/i.test(stderr);\n\n/** Image missing — classifier for `docker image rm` / `docker tag`\n *  flows. Matches the daemon's canonical wording only — a bare\n *  `/not found/` alternation would misclassify permission-denied and\n *  registry-auth errors (e.g. `pull access denied … repository does\n *  not exist`) as \"missing\" and let sweep silently skip them. Distinct\n *  from `isImageNotFoundStderr` (pull-flow-specific) — this one is the\n *  union used by idempotent remove/tag paths. */\nexport const isMissingImageStderr = (stderr: string): boolean =>\n\t/no such image|reference does not exist/i.test(stderr);\n\n/** Network missing — idempotent classifier for `docker network rm` /\n *  `docker network inspect`. Matches the daemon's canonical wordings:\n *  `No such network: <name>` and `network <name> not found`. A bare\n *  `/not found/` alternation would misclassify auth / permission errors\n *  on shared docker hosts. */\nexport const isMissingNetworkStderr = (stderr: string): boolean =>\n\t/no such network|network \\S+ not found/i.test(stderr);\n\n/** Network in-use — `docker network rm` failed because endpoints are\n *  still attached. Inverse predicate of `isMissingNetworkStderr`; lives\n *  next to its siblings so the two evolve together. */\nexport const isNetworkInUseStderr = (stderr: string): boolean =>\n\t/active endpoints|has active endpoint|network .* is in use/i.test(stderr);\n\n// -----------------------------------------------------------------------------\n// Wrappers — translate CaptureError → typed DockerRuntimeError\n// -----------------------------------------------------------------------------\n\n/** Daemon-unreachable check is the universal short-circuit. Every\n *  wrapper runs this first. */\nconst checkDaemon = (err: CaptureError): DaemonUnreachable | null => {\n\tif (isDaemonUnreachableStderr(err.stderr)) {\n\t\treturn new DaemonUnreachable({\n\t\t\top: err.op,\n\t\t\tdetail: 'docker daemon unreachable',\n\t\t\tcause: err.cause,\n\t\t});\n\t}\n\tif (err.cause !== undefined && err.exitCode === undefined) {\n\t\treturn new DaemonUnreachable({\n\t\t\top: err.op,\n\t\t\tdetail: 'docker CLI spawn failed (binary missing or fork failure)',\n\t\t\tcause: err.cause,\n\t\t});\n\t}\n\treturn null;\n};\n\nexport const wrapPullError =\n\t(ref: string) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\tif (isImageNotFoundStderr(err.stderr)) {\n\t\t\treturn new ImageNotFound({ ref, detail: 'pull target not found' });\n\t\t}\n\t\treturn new ImagePullFailed({ ref, stderr: err.stderr, exitCode: err.exitCode });\n\t};\n\nexport const wrapBuildError =\n\t(contextPath: string, dockerfile: string | undefined) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\t// STUB: best-effort parse of `Step <n>/<m> : <line>` from a\n\t\t// buildkit / classic builder log. The architecture allows this\n\t\t// to be empty — the raw stderr is still surfaced in `detail`.\n\t\t// Follow-up: extract from buildkit's `#<n> ERROR: …` envelope.\n\t\tconst parsedStep = parseFailingBuildStep(err.stdout, err.stderr);\n\t\treturn new BuildFailed({\n\t\t\tcontextPath,\n\t\t\tdockerfile,\n\t\t\tstderr: err.stderr,\n\t\t\tparsedStep,\n\t\t\texitCode: err.exitCode,\n\t\t});\n\t};\n\nexport const wrapCreateError =\n\t(name: string) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\tif (isNameCollisionStderr(err.stderr)) {\n\t\t\t// Architecture §1: surface the collision typed so the\n\t\t\t// state machine can decide adopt vs typed-failure. The\n\t\t\t// `Unrecoverable` variant fires only AFTER the start-and-\n\t\t\t// adopt fallback has exhausted; here we signal the collision\n\t\t\t// for the caller to handle.\n\t\t\treturn new ContainerNameCollisionUnrecoverable({\n\t\t\t\tname,\n\t\t\t\tdetail: 'name collision; caller should attempt adopt fallback',\n\t\t\t});\n\t\t}\n\t\tif (isPortConflictStderr(err.stderr)) {\n\t\t\treturn new ContainerPortPublishConflict({\n\t\t\t\tname,\n\t\t\t\tstderr: err.stderr,\n\t\t\t\texitCode: err.exitCode,\n\t\t\t});\n\t\t}\n\t\tif (isImageNotFoundStderr(err.stderr)) {\n\t\t\t// `docker run` against a local-only image name that isn't\n\t\t\t// present tries an implicit registry pull and fails. This is\n\t\t\t// RECOVERABLE (the dangling restored image still resolves by\n\t\t\t// digest, or restore can be re-run) — surface it typed so the\n\t\t\t// create path can try the digest fallback instead of a fatal\n\t\t\t// `ContainerCreateFailed`. `ref` carries the create name as the\n\t\t\t// best available identifier; the create caller knows the\n\t\t\t// concrete tag/digest it attempted.\n\t\t\treturn new ImageNotFound({ ref: name, detail: 'create target image not present locally' });\n\t\t}\n\t\treturn new ContainerCreateFailed({ name, stderr: err.stderr, exitCode: err.exitCode });\n\t};\n\nexport const wrapNetworkError =\n\t(op: 'create' | 'connect' | 'disconnect' | 'inspect' | 'remove', network: string) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\tif (op === 'create' && isNetworkAddressPoolExhaustedStderr(err.stderr)) {\n\t\t\treturn new NetworkAddressPoolExhausted({\n\t\t\t\tnetwork,\n\t\t\t\tstderr: err.stderr,\n\t\t\t\thint: 'Docker exhausted its predefined bridge address pools. Remove stale devstack networks with wipe/prune (for example `docker network prune`) or request an explicit non-overlapping subnet/gateway.',\n\t\t\t});\n\t\t}\n\t\treturn new NetworkOperationFailed({ op, network, stderr: err.stderr });\n\t};\n\nexport const wrapVolumeError =\n\t(op: 'create' | 'inspect' | 'remove', volume: string) =>\n\t(err: CaptureError): DockerRuntimeError => {\n\t\tconst d = checkDaemon(err);\n\t\tif (d) return d;\n\t\treturn new VolumeOperationFailed({ op, volume, stderr: err.stderr });\n\t};\n\n/** Generic wrapper for op surfaces (`docker logs`, `docker inspect`,\n *  etc.) where the only distinct failure mode is daemon down. */\nexport const wrapGeneric =\n\t(op: string) =>\n\t(err: CaptureError): DockerRuntimeError =>\n\t\tcheckDaemon(err) ??\n\t\tnew DaemonUnreachable({\n\t\t\top,\n\t\t\tdetail: err.stderr || `${op} failed (exit ${err.exitCode ?? '?'})`,\n\t\t\tcause: err.cause,\n\t\t});\n\n// -----------------------------------------------------------------------------\n// Helpers\n// -----------------------------------------------------------------------------\n\n/** STUB: extract a \"failing step\" line from build output. The\n *  buildkit envelope shape is documented; classic builder shape is\n *  `Step N/M : <directive>`. Returning `undefined` is fine — the raw\n *  stderr is still in the BuildFailed envelope. */\nconst parseFailingBuildStep = (stdout: string, stderr: string): string | undefined => {\n\tconst combined = `${stderr}\\n${stdout}`;\n\tconst classic = combined.match(/Step (\\d+)\\/(\\d+)\\s*:\\s*([^\\n]+)/);\n\tif (classic) return `Step ${classic[1]}/${classic[2]} ${classic[3]}`;\n\tconst buildkit = combined.match(/#(\\d+)\\s+ERROR\\s*:\\s*([^\\n]+)/);\n\tif (buildkit) return `#${buildkit[1]} ${buildkit[2]}`;\n\treturn undefined;\n};\n\n/** Inspect a `CaptureResult`'s exit code; if non-zero return null\n *  (caller decides what to do). Used by the lifecycle state machine\n *  to classify stderr patterns WITHOUT promoting non-zero to failure\n *  via `nonZeroIsFailure`. */\nexport const classifyExit = (\n\tres: CaptureResult,\n): { readonly ok: boolean; readonly exitCode: number; readonly stderr: string } => ({\n\tok: res.exitCode === 0,\n\texitCode: res.exitCode,\n\tstderr: res.stderr,\n});\n"],"mappings":"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"}

package/dist/substrate/brand.d.mts

@@ -7,18 +7,15 @@ type Brand<T, B extends string> = T & {
 type PluginKey = Brand<string, 'PluginKey'>;
 /** Opaque endpoint key — `(pluginKey, dispatchId)` digest, branded. */
 type EndpointKey = Brand<string, 'EndpointKey'>;
-/** Content-hash brand. Substrate folds chainId into the final cache key. */
+/** Content-hash brand. Substrate folds the chain string into the final cache key. */
 type ContentHash = Brand<string, 'ContentHash'>;
-/** Chain identity brand (e.g. `sui:mainnet`, `sui:fork@<height>`). */
-type ChainId = Brand<string, 'ChainId'>;
 /** Stack identity triple components. Validated once at boot. */
 type AppName = Brand<string, 'AppName'>;
 type StackName = Brand<string, 'StackName'>;
 declare const endpointKey: (s: string) => EndpointKey;
 declare const contentHash: (s: string) => ContentHash;
-declare const chainId: (s: string) => ChainId;
 declare const appName: (s: string) => AppName;
 declare const stackName: (s: string) => StackName;
 //#endregion
-export { AppName, Brand, ChainId, ContentHash, EndpointKey, PluginKey, StackName, appName, chainId, contentHash, endpointKey, stackName };
+export { AppName, Brand, ContentHash, EndpointKey, PluginKey, StackName, appName, contentHash, endpointKey, stackName };
 //# sourceMappingURL=brand.d.mts.map

package/dist/substrate/brand.mjs

@@ -5,10 +5,11 @@
 const pluginKey = (s) => s;
 const endpointKey = (s) => s;
 const contentHash = (s) => s;
-const chainId = (s) => s;
+const nodeInputId = (s) => s;
+const graphInputId = (s) => s;
 const appName = (s) => s;
 const stackName = (s) => s;
 //#endregion
-export { appName, chainId, contentHash, endpointKey, pluginKey, stackName };
+export { appName, contentHash, endpointKey, graphInputId, nodeInputId, pluginKey, stackName };
 
 //# sourceMappingURL=brand.mjs.map

package/dist/substrate/brand.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"brand.mjs","names":[],"sources":["../../src/substrate/brand.ts"],"sourcesContent":["// Branded primitives.\n//\n// One file owns the brand symbol so every primitive in this package\n// brands through the same shape. `Brand<T, B>` adds a unique-symbol\n// phantom so two strings with different brand tags are not\n// interchangeable.\n\ndeclare const _brand: unique symbol;\n\nexport type Brand<T, B extends string> = T & { readonly [_brand]: B };\n\n/** Opaque per-plugin-instance identity key. Substrate-blind. */\nexport type PluginKey = Brand<string, 'PluginKey'>;\n\n/** Opaque endpoint key — `(pluginKey, dispatchId)` digest, branded. */\nexport type EndpointKey = Brand<string, 'EndpointKey'>;\n\n/** Content-hash brand. Substrate folds chainId into the final cache key. */\nexport type ContentHash = Brand<string, 'ContentHash'>;\n\n/** Chain identity brand (e.g. `sui:mainnet`, `sui:fork@<height>`). */\nexport type ChainId = Brand<string, 'ChainId'>;\n\n/** Stack identity triple components. Validated once at boot. */\nexport type AppName = Brand<string, 'AppName'>;\nexport type StackName = Brand<string, 'StackName'>;\n\n/** Constructor helpers. These are the boundary where unbranded strings\n *  become branded; outside this file, callers should only see branded\n *  values. */\nexport const pluginKey = (s: string): PluginKey => s as PluginKey;\nexport const endpointKey = (s: string): EndpointKey => s as EndpointKey;\nexport const contentHash = (s: string): ContentHash => s as ContentHash;\nexport const chainId = (s: string): ChainId => s as ChainId;\nexport const appName = (s: string): AppName => s as AppName;\nexport const stackName = (s: string): StackName => s as StackName;\n"],"mappings":";;;;AA8BA,MAAa,aAAa,MAAyB;AACnD,MAAa,eAAe,MAA2B;AACvD,MAAa,eAAe,MAA2B;AACvD,MAAa,WAAW,MAAuB;AAC/C,MAAa,WAAW,MAAuB;AAC/C,MAAa,aAAa,MAAyB"}
+{"version":3,"file":"brand.mjs","names":[],"sources":["../../src/substrate/brand.ts"],"sourcesContent":["// Branded primitives.\n//\n// One file owns the brand symbol so every primitive in this package\n// brands through the same shape. `Brand<T, B>` adds a unique-symbol\n// phantom so two strings with different brand tags are not\n// interchangeable.\n\ndeclare const _brand: unique symbol;\n\nexport type Brand<T, B extends string> = T & { readonly [_brand]: B };\n\n/** Opaque per-plugin-instance identity key. Substrate-blind. */\nexport type PluginKey = Brand<string, 'PluginKey'>;\n\n/** Opaque endpoint key — `(pluginKey, dispatchId)` digest, branded. */\nexport type EndpointKey = Brand<string, 'EndpointKey'>;\n\n/** Content-hash brand. Substrate folds the chain string into the final cache key. */\nexport type ContentHash = Brand<string, 'ContentHash'>;\n\n/** Per-node input identity hash, computed from declared desired-state inputs. */\nexport type NodeInputId = Brand<string, 'NodeInputId'>;\n\n/** Aggregate graph input identity hash, computed from graph shape + node input ids. */\nexport type GraphInputId = Brand<string, 'GraphInputId'>;\n\n/** Stack identity triple components. Validated once at boot. */\nexport type AppName = Brand<string, 'AppName'>;\nexport type StackName = Brand<string, 'StackName'>;\n\n/** Constructor helpers. These are the boundary where unbranded strings\n *  become branded; outside this file, callers should only see branded\n *  values. */\nexport const pluginKey = (s: string): PluginKey => s as PluginKey;\nexport const endpointKey = (s: string): EndpointKey => s as EndpointKey;\nexport const contentHash = (s: string): ContentHash => s as ContentHash;\nexport const nodeInputId = (s: string): NodeInputId => s as NodeInputId;\nexport const graphInputId = (s: string): GraphInputId => s as GraphInputId;\nexport const appName = (s: string): AppName => s as AppName;\nexport const stackName = (s: string): StackName => s as StackName;\n"],"mappings":";;;;AAiCA,MAAa,aAAa,MAAyB;AACnD,MAAa,eAAe,MAA2B;AACvD,MAAa,eAAe,MAA2B;AACvD,MAAa,eAAe,MAA2B;AACvD,MAAa,gBAAgB,MAA4B;AACzD,MAAa,WAAW,MAAuB;AAC/C,MAAa,aAAa,MAAyB"}

package/dist/substrate/cross-process.mjs

@@ -12,23 +12,9 @@ const RosterHolderSchema = Schema.Struct({
 const RosterDocumentSchema = versionedDocSchema(1, { holders: Schema.Array(RosterHolderSchema) });
 const DEFAULT_SWEEP_POLICY = {
 	heartbeatIntervalMillis: 1e4,
-	staleAfterMillis: 3e4,
-	trustForeignHosts: true
+	staleAfterMillis: 3e4
 };
-/** Versioned schema — routed through `versionedDocSchema` so a v2
-*  migration can add a literal-tagged `Schema.Union` at one call site
-*  rather than hand-rolling a discriminator. `creatorStartTime` mirrors
-*  `RosterHolderSchema.startTime` (`NullOr(Number)`): when the creator
-*  couldn't probe its own startTime, write null and the sweep's
-*  liveness check short-circuits to "alive" rather than evicting on a
-*  literal `0` mismatch. */
-const SnapshotReservationSchema = versionedDocSchema(1, {
-	creatorPid: Schema.Number,
-	creatorStartTime: Schema.NullOr(Schema.Number),
-	createdAt: Schema.Number,
-	hostname: Schema.String
-});
 //#endregion
-export { DEFAULT_SWEEP_POLICY, RosterDocumentSchema, RosterHolderSchema, SnapshotReservationSchema };
+export { DEFAULT_SWEEP_POLICY, RosterDocumentSchema, RosterHolderSchema };
 
 //# sourceMappingURL=cross-process.mjs.map

package/dist/substrate/cross-process.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cross-process.mjs","names":[],"sources":["../../src/substrate/cross-process.ts"],"sourcesContent":["// Cross-process safety protocol.\n//\n// Architecture § Cross-process safety protocol. Core artifacts per\n// stack on disk under `<runtime-root>/stacks/<stack>/`:\n//\n//   - `stack.lock` — OS-advisory exclusive lock; short critical\n//     sections only.\n//   - `roster.json` — authoritative cross-process record of holders;\n//     mutated only under the lock.\n//   - `commands.ndjson` / `events.ndjson` — filesystem command\n//     channel between peer CLI commands and the live supervisor.\n//   - `snapshot.reservation` — present-or-absent file (O_EXCL create\n//     = acquire; unlink = release).\n\nimport { Schema } from 'effect';\n\nimport { versionedDocSchema } from './versioned-doc-schema.ts';\n\n/** Holder intent — `normal` for ordinary peers; `snapshot` while\n *  the holder is mid-capture (peers' commands defer). */\nexport type HolderIntent = 'normal' | 'snapshot';\n\n/** One holder entry in `roster.json`. PID + startTime liveness check\n *  is the industry-standard pattern referenced in the synthesis.\n *\n *  `startTime` is `number | null` — `null` means \"the platform could\n *  not probe a start-time stamp for this process at write time\" (an\n *  exotic platform, or `ps`/`tasklist` failed). Readers MUST treat\n *  `null` as the conservative branch (see `isOwnEntry` in `roster.ts`\n *  and `checkHolderLiveness` in `liveness.ts`): on a null recorded\n *  stamp the start-time comparison is skipped and the (pid, hostname)\n *  pair carries the identity. Writing `0` for \"unknown\" was the prior\n *  shape and caused a false-dead harvest: a later probe yielding a\n *  real stamp would mismatch the recorded `0`. */\nexport interface RosterHolder {\n\treadonly pid: number;\n\t/** Process start-time, used for PID-reuse-safe liveness. `null`\n\t *  means \"unprobable\" — see the interface doc above. */\n\treadonly startTime: number | null;\n\treadonly hostname: string;\n\treadonly claimedAt: number;\n\treadonly heartbeatAt: number;\n\treadonly intent: HolderIntent;\n}\n\n/** Roster document schema — versioned for forward compatibility. */\nexport interface RosterDocument {\n\treadonly version: 1;\n\treadonly holders: ReadonlyArray<RosterHolder>;\n}\n\nexport const RosterHolderSchema = Schema.Struct({\n\tpid: Schema.Number,\n\tstartTime: Schema.NullOr(Schema.Number),\n\thostname: Schema.String,\n\tclaimedAt: Schema.Number,\n\theartbeatAt: Schema.Number,\n\tintent: Schema.Literals(['normal', 'snapshot']),\n});\n\nexport const RosterDocumentSchema = versionedDocSchema(1, {\n\tholders: Schema.Array(RosterHolderSchema),\n});\n\n/** Sweep policy — peers older than `staleAfterMillis` AND failing\n *  the PID liveness check are evicted on the next claim under the\n *  exclusive lock. Foreign-host entries are treated as alive\n *  (NFS-safe conservative default). */\nexport interface RosterSweepPolicy {\n\treadonly heartbeatIntervalMillis: number;\n\treadonly staleAfterMillis: number;\n\treadonly trustForeignHosts: boolean;\n}\n\nexport const DEFAULT_SWEEP_POLICY: RosterSweepPolicy = {\n\theartbeatIntervalMillis: 10_000,\n\tstaleAfterMillis: 30_000,\n\ttrustForeignHosts: true,\n};\n\n/** Snapshot reservation file — presence-or-absence semaphore. The\n *  reservation's creator pid is encoded in the JSON body for the\n *  orphan sweep.\n *\n *  `hostname` is carried so the orphan sweep can skip foreign-host\n *  reservations on shared filesystems (NFS): a peer on host B writing\n *  the reservation would be falsely declared \"dead\" by host A's kernel\n *  probe (`kill(pid, 0)` only meaningful on the local host). The sweep\n *  treats foreign-host reservations as alive (conservative — matches\n *  the roster's `trustForeignHosts` policy). */\nexport interface SnapshotReservation {\n\treadonly version: 1;\n\treadonly creatorPid: number;\n\treadonly creatorStartTime: number | null;\n\treadonly createdAt: number;\n\treadonly hostname: string;\n}\n\n/** Versioned schema — routed through `versionedDocSchema` so a v2\n *  migration can add a literal-tagged `Schema.Union` at one call site\n *  rather than hand-rolling a discriminator. `creatorStartTime` mirrors\n *  `RosterHolderSchema.startTime` (`NullOr(Number)`): when the creator\n *  couldn't probe its own startTime, write null and the sweep's\n *  liveness check short-circuits to \"alive\" rather than evicting on a\n *  literal `0` mismatch. */\nexport const SnapshotReservationSchema = versionedDocSchema(1, {\n\tcreatorPid: Schema.Number,\n\tcreatorStartTime: Schema.NullOr(Schema.Number),\n\tcreatedAt: Schema.Number,\n\thostname: Schema.String,\n});\n"],"mappings":";;;AAmDA,MAAa,qBAAqB,OAAO,OAAO;CAC/C,KAAK,OAAO;CACZ,WAAW,OAAO,OAAO,OAAO,OAAO;CACvC,UAAU,OAAO;CACjB,WAAW,OAAO;CAClB,aAAa,OAAO;CACpB,QAAQ,OAAO,SAAS,CAAC,UAAU,WAAW,CAAC;CAC/C,CAAC;AAEF,MAAa,uBAAuB,mBAAmB,GAAG,EACzD,SAAS,OAAO,MAAM,mBAAmB,EACzC,CAAC;AAYF,MAAa,uBAA0C;CACtD,yBAAyB;CACzB,kBAAkB;CAClB,mBAAmB;CACnB;;;;;;;;AA2BD,MAAa,4BAA4B,mBAAmB,GAAG;CAC9D,YAAY,OAAO;CACnB,kBAAkB,OAAO,OAAO,OAAO,OAAO;CAC9C,WAAW,OAAO;CAClB,UAAU,OAAO;CACjB,CAAC"}
+{"version":3,"file":"cross-process.mjs","names":[],"sources":["../../src/substrate/cross-process.ts"],"sourcesContent":["// Cross-process safety protocol.\n//\n// Architecture § Cross-process safety protocol. Core artifacts per\n// stack on disk under `<runtime-root>/stacks/<stack>/`:\n//\n//   - `stack.lock` — OS-advisory exclusive lock; short critical\n//     sections only.\n//   - `roster.json` — authoritative cross-process record of holders;\n//     mutated only under the lock.\n//   - `commands.ndjson` / `events.ndjson` — filesystem command\n//     channel between peer CLI commands and the live supervisor.\n//\n// The snapshot bounce holds `stack.lock` for the (bounded, whole-stack-\n// stopped) snapshot window — there is no separate snapshot-reservation file\n// (the lock subsumes the concurrency guard).\n\nimport { Schema } from 'effect';\n\nimport { versionedDocSchema } from './versioned-doc-schema.ts';\n\n/** Holder intent — `normal` for ordinary peers; `snapshot` while\n *  the holder is mid-capture (peers' commands defer). */\nexport type HolderIntent = 'normal' | 'snapshot';\n\n/** One holder entry in `roster.json`. PID + startTime distinguish live\n *  processes from PID reuse.\n *\n *  `startTime` is `number | null` — `null` means \"the platform could\n *  not probe a start-time stamp for this process at write time\" (an\n *  exotic platform, or `ps`/`tasklist` failed). Readers MUST treat\n *  `null` as the conservative branch (see `isOwnEntry` in `roster.ts`\n *  and `checkHolderLiveness` in `liveness.ts`): on a null recorded\n *  stamp the start-time comparison is skipped and the (pid, hostname)\n *  pair carries the identity. */\nexport interface RosterHolder {\n\treadonly pid: number;\n\t/** Process start-time, used for PID-reuse-safe liveness. `null`\n\t *  means \"unprobable\" — see the interface doc above. */\n\treadonly startTime: number | null;\n\treadonly hostname: string;\n\treadonly claimedAt: number;\n\treadonly heartbeatAt: number;\n\treadonly intent: HolderIntent;\n}\n\n/** Roster document schema — versioned for schema validation. */\nexport interface RosterDocument {\n\treadonly version: 1;\n\treadonly holders: ReadonlyArray<RosterHolder>;\n}\n\nexport const RosterHolderSchema = Schema.Struct({\n\tpid: Schema.Number,\n\tstartTime: Schema.NullOr(Schema.Number),\n\thostname: Schema.String,\n\tclaimedAt: Schema.Number,\n\theartbeatAt: Schema.Number,\n\tintent: Schema.Literals(['normal', 'snapshot']),\n});\n\nexport const RosterDocumentSchema = versionedDocSchema(1, {\n\tholders: Schema.Array(RosterHolderSchema),\n});\n\n/** Sweep policy — peers older than `staleAfterMillis` AND failing\n *  the PID liveness check are evicted on the next claim under the\n *  exclusive lock. */\nexport interface RosterSweepPolicy {\n\treadonly heartbeatIntervalMillis: number;\n\treadonly staleAfterMillis: number;\n}\n\nexport const DEFAULT_SWEEP_POLICY: RosterSweepPolicy = {\n\theartbeatIntervalMillis: 10_000,\n\tstaleAfterMillis: 30_000,\n};\n"],"mappings":";;;AAmDA,MAAa,qBAAqB,OAAO,OAAO;CAC/C,KAAK,OAAO;CACZ,WAAW,OAAO,OAAO,OAAO,MAAM;CACtC,UAAU,OAAO;CACjB,WAAW,OAAO;CAClB,aAAa,OAAO;CACpB,QAAQ,OAAO,SAAS,CAAC,UAAU,UAAU,CAAC;AAC/C,CAAC;AAED,MAAa,uBAAuB,mBAAmB,GAAG,EACzD,SAAS,OAAO,MAAM,kBAAkB,EACzC,CAAC;AAUD,MAAa,uBAA0C;CACtD,yBAAyB;CACzB,kBAAkB;AACnB"}

package/dist/substrate/event-time.mjs

@@ -16,8 +16,6 @@ const eventAtOrNull = (event) => {
 		case "restart.requested":
 		case "restart.completed":
 		case "shutdown.escalated":
-		case "snapshot.captureStarted":
-		case "snapshot.captureProgress":
 		case "snapshot.captureSkipped":
 		case "snapshot.captureFailed":
 		case "snapshot.captured":

package/dist/substrate/event-time.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"event-time.mjs","names":[],"sources":["../../src/substrate/event-time.ts"],"sourcesContent":["// Producer-time projection for `EngineEvent`.\n//\n// Every event variant carries an authoritative timestamp either at the\n// top level (`event.at`) or in a domain-specific nested field\n// (`endpoint.registered.endpoint.registeredAt`, `error.reported.error.at`,\n// `build.statusChanged.entry.startedAt`). The switch is intentionally\n// exhaustive so a newly-added variant must declare where its timestamp\n// lives — the compiler enforces it via the `never`-assignment default.\n//\n// Two shapes:\n//   - `eventAtOrNull` (substrate-layer consumers): returns `null` when\n//     the variant has no inherent timestamp, letting the caller fall\n//     back to whatever stale value preserves invariants (e.g. the\n//     projection update reducer keeps `state.lastEvent.at` on miss).\n//   - `eventAt` (UI consumers): wraps `eventAtOrNull` with a `Date.now()`\n//     fallback so log rendering always gets a number. Removing the\n//     historical dequeue-time fallback was load-bearing — under\n//     back-pressure (a queued event flushed late from the dispatcher)\n//     it back-dated or forward-dated the log entry, producing apparent\n//     event-time reordering in the rendered log. Pinning to the\n//     producer's record preserves the ordering tests assert.\n\nimport type { EngineEvent } from './events.ts';\n\nexport const eventAtOrNull = (event: EngineEvent): number | null => {\n\tswitch (event.tag) {\n\t\tcase 'endpoint.registered':\n\t\t\treturn event.endpoint.registeredAt;\n\t\tcase 'error.reported':\n\t\t\treturn event.error.at;\n\t\tcase 'build.statusChanged':\n\t\t\treturn event.entry.startedAt;\n\t\tcase 'lifecycle.statusChanged':\n\t\tcase 'lifecycle.phaseSet':\n\t\tcase 'log.appended':\n\t\tcase 'projection.updated':\n\t\tcase 'endpoint.released':\n\t\tcase 'strategy.registered':\n\t\tcase 'strategy.unregistered':\n\t\tcase 'manifest.flushed':\n\t\tcase 'codegen.emitted':\n\t\tcase 'restart.requested':\n\t\tcase 'restart.completed':\n\t\tcase 'shutdown.escalated':\n\t\tcase 'snapshot.captureStarted':\n\t\tcase 'snapshot.captureProgress':\n\t\tcase 'snapshot.captureSkipped':\n\t\tcase 'snapshot.captureFailed':\n\t\tcase 'snapshot.captured':\n\t\tcase 'snapshot.restored':\n\t\tcase 'engine.orchestrator.dispatchFailed':\n\t\t\treturn event.at;\n\t\tdefault: {\n\t\t\tconst _exhaustive: never = event;\n\t\t\tvoid _exhaustive;\n\t\t\treturn null;\n\t\t}\n\t}\n};\n\nexport const eventAt = (event: EngineEvent): number => eventAtOrNull(event) ?? Date.now();\n"],"mappings":";AAwBA,MAAa,iBAAiB,UAAsC;AACnE,SAAQ,MAAM,KAAd;EACC,KAAK,sBACJ,QAAO,MAAM,SAAS;EACvB,KAAK,iBACJ,QAAO,MAAM,MAAM;EACpB,KAAK,sBACJ,QAAO,MAAM,MAAM;EACpB,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,qCACJ,QAAO,MAAM;EACd,QAGC,QAAO;;;AAKV,MAAa,WAAW,UAA+B,cAAc,MAAM,IAAI,KAAK,KAAK"}
+{"version":3,"file":"event-time.mjs","names":[],"sources":["../../src/substrate/event-time.ts"],"sourcesContent":["// Producer-time projection for `EngineEvent`.\n//\n// Every event variant carries an authoritative timestamp either at the\n// top level (`event.at`) or in a domain-specific nested field\n// (`endpoint.registered.endpoint.registeredAt`, `error.reported.error.at`,\n// `build.statusChanged.entry.startedAt`). The switch is intentionally\n// exhaustive so a newly-added variant must declare where its timestamp\n// lives — the compiler enforces it via the `never`-assignment default.\n//\n// Two shapes:\n//   - `eventAtOrNull` (substrate-layer consumers): returns `null` when\n//     the variant has no inherent timestamp, letting the caller fall\n//     back to whatever stale value preserves invariants (e.g. the\n//     projection update reducer keeps `state.lastEvent.at` on miss).\n//   - `eventAt` (UI consumers): wraps `eventAtOrNull` with a `Date.now()`\n//     fallback so log rendering always gets a number. It pins to the\n//     producer's record rather than a dequeue-time stamp: under back-\n//     pressure (a queued event flushed late from the dispatcher) a\n//     dequeue-time stamp would back-date or forward-date the log entry,\n//     producing apparent event-time reordering in the rendered log.\n//     Pinning to the producer's record preserves the ordering tests\n//     assert.\n\nimport type { EngineEvent } from './events.ts';\n\nexport const eventAtOrNull = (event: EngineEvent): number | null => {\n\tswitch (event.tag) {\n\t\tcase 'endpoint.registered':\n\t\t\treturn event.endpoint.registeredAt;\n\t\tcase 'error.reported':\n\t\t\treturn event.error.at;\n\t\tcase 'build.statusChanged':\n\t\t\treturn event.entry.startedAt;\n\t\tcase 'lifecycle.statusChanged':\n\t\tcase 'lifecycle.phaseSet':\n\t\tcase 'log.appended':\n\t\tcase 'projection.updated':\n\t\tcase 'endpoint.released':\n\t\tcase 'strategy.registered':\n\t\tcase 'strategy.unregistered':\n\t\tcase 'manifest.flushed':\n\t\tcase 'codegen.emitted':\n\t\tcase 'restart.requested':\n\t\tcase 'restart.completed':\n\t\tcase 'shutdown.escalated':\n\t\tcase 'snapshot.captureSkipped':\n\t\tcase 'snapshot.captureFailed':\n\t\tcase 'snapshot.captured':\n\t\tcase 'snapshot.restored':\n\t\tcase 'engine.orchestrator.dispatchFailed':\n\t\t\treturn event.at;\n\t\tdefault: {\n\t\t\tconst _exhaustive: never = event;\n\t\t\tvoid _exhaustive;\n\t\t\treturn null;\n\t\t}\n\t}\n};\n\nexport const eventAt = (event: EngineEvent): number => eventAtOrNull(event) ?? Date.now();\n"],"mappings":";AAyBA,MAAa,iBAAiB,UAAsC;CACnE,QAAQ,MAAM,KAAd;EACC,KAAK,uBACJ,OAAO,MAAM,SAAS;EACvB,KAAK,kBACJ,OAAO,MAAM,MAAM;EACpB,KAAK,uBACJ,OAAO,MAAM,MAAM;EACpB,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,sCACJ,OAAO,MAAM;EACd,SAGC,OAAO;CAET;AACD;AAEA,MAAa,WAAW,UAA+B,cAAc,KAAK,KAAK,KAAK,IAAI"}

package/dist/substrate/events.d.mts

@@ -4,7 +4,6 @@ import { BuildEntry, Endpoint, StructuredError } from "./projection.mjs";
 
 //#region src/substrate/events.d.ts
 type ShutdownSignal = 'SIGINT' | 'SIGTERM';
-type SnapshotCaptureProgressPhase = 'quiescing' | 'pausing' | 'paused' | 'capturing-containers' | 'saving-images' | 'capturing-host-tree' | 'saving-state' | 'saving-contributions' | 'writing-metadata' | 'resuming';
 /** Typed lifecycle event stream. Architecture-enumerated categories. */
 type EngineEvent = {
   readonly tag: 'lifecycle.statusChanged';
@@ -82,20 +81,6 @@ type EngineEvent = {
   readonly signal: ShutdownSignal;
   readonly exitCode: number;
   readonly at: number;
-} | {
-  readonly tag: 'snapshot.captureStarted';
-  readonly snapshotId?: string;
-  readonly name?: string;
-  readonly at: number;
-} | {
-  readonly tag: 'snapshot.captureProgress';
-  readonly snapshotId?: string;
-  readonly name?: string;
-  readonly phase: SnapshotCaptureProgressPhase;
-  readonly detail?: string;
-  readonly pausedContainers?: number;
-  readonly totalContainers?: number;
-  readonly at: number;
 } | {
   readonly tag: 'snapshot.captureSkipped';
   readonly reason: 'already-running';
@@ -132,6 +117,51 @@ type EngineEvent = {
   readonly causeType?: string;
   readonly at: number;
 };
+/** Typed command channel. Surfaces publish; the engine consumes.
+ *  Same shape regardless of producer (CLI argv / TUI keypress /
+ *  programmable API). */
+type EngineCommand = {
+  readonly tag: 'stack.start';
+} | {
+  readonly tag: 'stack.stop';
+} | {
+  readonly tag: 'stack.restart';
+} | {
+  readonly tag: 'apply.requested';
+  readonly pluginKey?: PluginKey;
+} | {
+  readonly tag: 'codegen.requested';
+} | {
+  readonly tag: 'snapshot.capture';
+  readonly snapshotId?: string;
+  readonly name?: string;
+  readonly replaceExisting?: boolean;
+} | {
+  readonly tag: 'snapshot.restore';
+  readonly snapshotId: string;
+} | {
+  readonly tag: 'snapshot.list';
+} | {
+  readonly tag: 'snapshot.delete';
+  readonly snapshotId: string;
+} | {
+  readonly tag: 'wipe.requested';
+} | {
+  readonly tag: 'prune.requested';
+} | {
+  readonly tag: 'advance-clock.requested';
+  readonly toMillis: number;
+} | {
+  readonly tag: 'shutdown.requested';
+} | {
+  readonly tag: 'shutdown.hardKillRequested';
+  readonly signal: ShutdownSignal;
+  readonly exitCode: number;
+  readonly at: number;
+} | {
+  readonly tag: 'selective-restart.requested';
+  readonly pluginKey: PluginKey;
+};
 //#endregion
-export { EngineEvent };
+export { EngineCommand, EngineEvent };
 //# sourceMappingURL=events.d.mts.map

package/dist/substrate/identity.d.mts

@@ -1,13 +1,19 @@
-import { AppName, ChainId, StackName } from "./brand.mjs";
+import { AppName, StackName } from "./brand.mjs";
 
 //#region src/substrate/identity.d.ts
-/** Closed identity triple. Architecture § Stack data model. */
+/** Closed identity tuple. Architecture § Stack data model. The substrate
+ *  is name-blind: it knows nothing about networks or modes. */
 interface Identity {
   readonly app: AppName;
   readonly stack: StackName;
-  /** Resolved chain identifier — threaded through Context from the
-   *  Sui plugin's resolved mode + `DevstackOptions.network`. */
-  readonly chain: ChainId;
+  /** Opaque identity label — a substrate-blind plain string the caller
+   *  supplies once at boot, threaded through Context as a generic
+   *  correlation/display label (supervisor labels, span attributes,
+   *  snapshot provenance meta). The substrate NEVER parses it or branches
+   *  on its value; it carries no network/mode semantics here. Callers
+   *  (CLI / `runStack`) happen to set it to a resolved network name, but
+   *  that is a producer concern, not a substrate primitive. */
+  readonly network: string;
 }
 //#endregion
 export { Identity };