@mysten-incubation/devstack 0.0.0

package/dist/runtime/docker/sweep.d.mts

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

package/dist/runtime/docker/sweep.mjs

@@ -0,0 +1,220 @@
+import { StackPathsService } from "../../substrate/runtime/paths.mjs";
+import { dockerRunOk } from "./client.mjs";
+import { acquireStackLock } from "../../substrate/runtime/cross-process/stack-lock.mjs";
+import { readClaims } from "../../substrate/runtime/cross-process/roster.mjs";
+import { ContainerRemoveFailed, DaemonUnreachable, ImageRemoveFailed, NetworkOperationFailed } from "./errors.mjs";
+import { LabelKey } from "./labels.mjs";
+import { isNoSuchContainerStderr, wrapGeneric } from "./wrap.mjs";
+import { listContainers, listDevstackContainers, listDevstackImages, listDevstackNetworks, listDevstackRouterContainers, listDevstackVolumes, listImages, listNetworks, listVolumes } from "./inventory.mjs";
+import { removeVolume } from "./volume.mjs";
+import { Effect } from "effect";
+//#region src/runtime/docker/sweep.ts
+/** Sweep orphan containers matching the partial label tuple. Returns
+*  the number of containers removed.
+*
+*  The sweep:
+*
+*    1. Lists all containers with the canonical `devstack.managed=true`
+*       + caller-supplied partial tuple (typically `{app, stack}`).
+*    2. Reads the container-claim ledger (the file held alongside
+*       roster.json; mutated only under stack.lock).
+*    3. Under stack.lock, removes any container whose name is NOT in
+*       the ledger.
+*
+*  Concurrent sweepers are serialized by stack.lock. The architecture
+*  says briefly here — we hold the lock only across the read + the
+*  remove decision; we DON'T hold it across the individual `docker
+*  rm` calls (which can be slow). The cost: a peer that registered a
+*  claim between our decision and our rm gets its container rm'd
+*  anyway. The mitigation: this only fires on the BOOT path before
+*  any plugin acquires, so the steady-state "peer just claimed" race
+*  is not in the picture. */
+const sweepOrphans = (labelMatch) => Effect.gen(function* () {
+	const paths = yield* StackPathsService;
+	const containers = yield* listContainers(labelMatch);
+	if (containers.length === 0) return 0;
+	const mapSubstrateError = (cause) => new DaemonUnreachable({
+		op: "cross-process.sweep",
+		detail: `sweep substrate read failed: ${String(cause)}`,
+		cause
+	});
+	const claimNames = yield* Effect.scoped(Effect.gen(function* () {
+		yield* acquireStackLock(paths.stackLockFile).pipe(Effect.mapError(mapSubstrateError));
+		const doc = yield* readClaims({
+			stackLockFile: paths.stackLockFile,
+			rosterFile: paths.rosterFile
+		}).pipe(Effect.mapError(mapSubstrateError));
+		return new Set(doc.claims.map((c) => c.containerKey));
+	}));
+	let removed = 0;
+	for (const c of containers) {
+		if (claimNames.has(c.name)) continue;
+		if ((yield* dockerRunOk("rm", ["-f", c.name]).pipe(Effect.catch(() => Effect.succeed({
+			exitCode: 1,
+			stdout: "",
+			stderr: "sweep rm spawn failed"
+		})))).exitCode === 0) removed += 1;
+	}
+	return removed;
+}).pipe(Effect.withSpan("runtime.docker.sweep"));
+const removeManagedContainer = (name) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("rm", ["-f", name]).pipe(Effect.mapError(wrapGeneric("docker.rm")));
+	if (res.exitCode === 0) return true;
+	if (isNoSuchContainerStderr(res.stderr)) return false;
+	return yield* Effect.fail(new ContainerRemoveFailed({
+		name,
+		stderr: res.stderr,
+		exitCode: res.exitCode
+	}));
+});
+/** Explicit teardown. Unlike `sweepOrphans`, this does not consult the
+*  claim ledger; wipe/restore are intentional destructive operations. */
+const removeManagedContainers = (labelMatch) => Effect.gen(function* () {
+	const containers = yield* listContainers(labelMatch);
+	let removed = 0;
+	for (const c of containers) if (yield* removeManagedContainer(c.name)) removed += 1;
+	return removed;
+}).pipe(Effect.withSpan("runtime.docker.removeManagedContainers"));
+const labelsMatchAppStack = (labels, match) => labels[LabelKey.app] === match.app && labels[LabelKey.stack] === match.stack;
+const removeDevstackContainers = (labelMatch) => Effect.gen(function* () {
+	const containers = yield* listDevstackContainers();
+	let removed = 0;
+	for (const c of containers) {
+		if (!labelsMatchAppStack(c.labels, labelMatch)) continue;
+		if (yield* removeManagedContainer(c.name)) removed += 1;
+	}
+	return removed;
+}).pipe(Effect.withSpan("runtime.docker.removeDevstackContainers"));
+const removeDevstackRouterContainers = (containerName) => Effect.gen(function* () {
+	const containers = yield* listDevstackRouterContainers();
+	let removed = 0;
+	for (const c of containers) {
+		if (c.name !== containerName) continue;
+		if (yield* removeManagedContainer(c.name)) removed += 1;
+	}
+	return removed;
+}).pipe(Effect.withSpan("runtime.docker.removeDevstackRouterContainers"));
+const isMissingImageStderr = (stderr) => /no such image|not found|reference does not exist/i.test(stderr);
+const removeManagedImage = (ref) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("image", [
+		"rm",
+		"-f",
+		ref
+	]).pipe(Effect.mapError(wrapGeneric("docker.image.rm")));
+	if (res.exitCode === 0) return true;
+	if (isMissingImageStderr(res.stderr)) return false;
+	return yield* Effect.fail(new ImageRemoveFailed({
+		ref,
+		stderr: res.stderr,
+		exitCode: res.exitCode
+	}));
+});
+const removeManagedImages = (labelMatch) => Effect.gen(function* () {
+	const images = yield* listImages(labelMatch);
+	let removed = 0;
+	const seen = /* @__PURE__ */ new Set();
+	for (const image of images) {
+		const ref = image.tag;
+		if (seen.has(ref)) continue;
+		seen.add(ref);
+		if (yield* removeManagedImage(ref)) removed += 1;
+	}
+	return removed;
+}).pipe(Effect.withSpan("runtime.docker.removeManagedImages"));
+const removeDevstackImages = (labelMatch) => Effect.gen(function* () {
+	const images = yield* listDevstackImages();
+	let removed = 0;
+	const seen = /* @__PURE__ */ new Set();
+	for (const image of images) {
+		if (!labelsMatchAppStack(image.labels, labelMatch)) continue;
+		const ref = image.tag;
+		if (ref.endsWith(":<none>")) continue;
+		if (seen.has(ref)) continue;
+		seen.add(ref);
+		if (yield* removeManagedImage(ref)) removed += 1;
+	}
+	return removed;
+}).pipe(Effect.withSpan("runtime.docker.removeDevstackImages"));
+const isMissingNetworkStderr = (stderr) => /no such network|network .* not found|not found/i.test(stderr);
+const removeManagedNetwork = (name) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("network", ["rm", name]).pipe(Effect.mapError(wrapGeneric("docker.network.rm")));
+	if (res.exitCode === 0) return true;
+	if (isMissingNetworkStderr(res.stderr)) return false;
+	return yield* Effect.fail(new NetworkOperationFailed({
+		op: "remove",
+		network: name,
+		stderr: res.stderr
+	}));
+});
+const removeManagedNetworks = (labelMatch) => Effect.gen(function* () {
+	const networks = yield* listNetworks(labelMatch);
+	let removed = 0;
+	for (const network of networks) {
+		if (network.labels[LabelKey.networkMarker] !== "true") continue;
+		if (yield* removeManagedNetwork(network.name)) removed += 1;
+	}
+	return removed;
+}).pipe(Effect.withSpan("runtime.docker.removeManagedNetworks"));
+const isNetworkInUseStderr = (stderr) => /active endpoints|has active endpoint|network .* is in use/i.test(stderr);
+const removeManagedNetworkOnce = (name) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("network", ["rm", name]).pipe(Effect.mapError(wrapGeneric("docker.network.rm")));
+	if (res.exitCode === 0) return "removed";
+	if (isMissingNetworkStderr(res.stderr)) return "missing";
+	if (isNetworkInUseStderr(res.stderr)) return "in-use";
+	return yield* Effect.fail(new NetworkOperationFailed({
+		op: "remove",
+		network: name,
+		stderr: res.stderr
+	}));
+});
+const removeManagedNetworkBestEffort = (name, options) => Effect.gen(function* () {
+	for (let attempt = 0; attempt < options.retryAttempts; attempt += 1) {
+		const outcome = yield* removeManagedNetworkOnce(name);
+		if (outcome !== "in-use") return outcome;
+		if (attempt < options.retryAttempts - 1) yield* Effect.sleep(`${options.retryDelayMillis} millis`);
+	}
+	return "in-use";
+});
+const removeDevstackNetworksBestEffort = (labelMatch, options = {}) => Effect.gen(function* () {
+	const networks = yield* listDevstackNetworks();
+	const retryOptions = {
+		retryAttempts: options.retryAttempts ?? 6,
+		retryDelayMillis: options.retryDelayMillis ?? 250
+	};
+	let removed = 0;
+	let skippedInUse = 0;
+	for (const network of networks) {
+		if (!labelsMatchAppStack(network.labels, labelMatch)) continue;
+		const outcome = yield* removeManagedNetworkBestEffort(network.name, retryOptions);
+		if (outcome === "removed") removed += 1;
+		if (outcome === "in-use") skippedInUse += 1;
+	}
+	return {
+		removed,
+		skippedInUse
+	};
+}).pipe(Effect.withSpan("runtime.docker.removeDevstackNetworksBestEffort"));
+const removeManagedVolumes = (labelMatch) => Effect.gen(function* () {
+	const volumes = yield* listVolumes(labelMatch);
+	let removed = 0;
+	for (const volume of volumes) {
+		if (volume.labels[LabelKey.volumeMarker] !== "true") continue;
+		yield* removeVolume(volume.name);
+		removed += 1;
+	}
+	return removed;
+}).pipe(Effect.withSpan("runtime.docker.removeManagedVolumes"));
+const removeDevstackVolumes = (labelMatch) => Effect.gen(function* () {
+	const volumes = yield* listDevstackVolumes();
+	let removed = 0;
+	for (const volume of volumes) {
+		if (!labelsMatchAppStack(volume.labels, labelMatch)) continue;
+		yield* removeVolume(volume.name);
+		removed += 1;
+	}
+	return removed;
+}).pipe(Effect.withSpan("runtime.docker.removeDevstackVolumes"));
+//#endregion
+export { removeDevstackContainers, removeDevstackImages, removeDevstackNetworksBestEffort, removeDevstackRouterContainers, removeDevstackVolumes, removeManagedContainers, removeManagedImages, removeManagedNetworks, removeManagedVolumes, sweepOrphans };
+
+//# sourceMappingURL=sweep.mjs.map

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

@@ -0,0 +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 { 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\tlistDevstackImages,\n\tlistDevstackNetworks,\n\tlistDevstackRouterContainers,\n\tlistDevstackVolumes,\n\tlistImages,\n\tlistNetworks,\n\tlistVolumes,\n} from './inventory.ts';\nimport { LabelKey } from './labels.ts';\nimport { removeVolume } from './volume.ts';\nimport { isNoSuchContainerStderr, wrapGeneric } from './wrap.ts';\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}).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.\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 res = yield* dockerRunOk('rm', ['-f', c.name]).pipe(\n\t\t\t\tEffect.catch(() =>\n\t\t\t\t\tEffect.succeed({ exitCode: 1, stdout: '', stderr: 'sweep rm spawn failed' }),\n\t\t\t\t),\n\t\t\t);\n\t\t\tif (res.exitCode === 0) removed += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.sweep'));\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. 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\nexport const removeDevstackRouterContainers = (\n\tcontainerName: string,\n): Effect.Effect<number, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tconst containers = yield* listDevstackRouterContainers();\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.removeDevstackRouterContainers'));\n\nconst isMissingImageStderr = (stderr: string): boolean =>\n\t/no such image|not found|reference does not exist/i.test(stderr);\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 (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 isMissingNetworkStderr = (stderr: string): boolean =>\n\t/no such network|network .* not found|not found/i.test(stderr);\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\nconst isNetworkInUseStderr = (stderr: string): boolean =>\n\t/active endpoints|has active endpoint|network .* is in use/i.test(stderr);\n\ntype NetworkRemoveOutcome = 'removed' | 'missing' | 'in-use';\n\nexport interface DevstackNetworkRemovalSummary {\n\treadonly removed: number;\n\treadonly skippedInUse: number;\n}\n\ninterface DevstackNetworkRemovalOptions {\n\treadonly retryAttempts?: number;\n\treadonly retryDelayMillis?: number;\n}\n\nconst removeManagedNetworkOnce = (\n\tname: string,\n): Effect.Effect<NetworkRemoveOutcome, 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 'removed' as const;\n\t\tif (isMissingNetworkStderr(res.stderr)) return 'missing' as const;\n\t\tif (isNetworkInUseStderr(res.stderr)) return 'in-use' as const;\n\t\treturn yield* Effect.fail(\n\t\t\tnew NetworkOperationFailed({ op: 'remove', network: name, stderr: res.stderr }),\n\t\t);\n\t});\n\nconst removeManagedNetworkBestEffort = (\n\tname: string,\n\toptions: Required<DevstackNetworkRemovalOptions>,\n): Effect.Effect<NetworkRemoveOutcome, DockerRuntimeError, DockerHost | DockerSpawner> =>\n\tEffect.gen(function* () {\n\t\tfor (let attempt = 0; attempt < options.retryAttempts; attempt += 1) {\n\t\t\tconst outcome = yield* removeManagedNetworkOnce(name);\n\t\t\tif (outcome !== 'in-use') return outcome;\n\t\t\tif (attempt < options.retryAttempts - 1) {\n\t\t\t\tyield* Effect.sleep(`${options.retryDelayMillis} millis`);\n\t\t\t}\n\t\t}\n\t\treturn 'in-use' as const;\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 ?? 6,\n\t\t\tretryDelayMillis: options.retryDelayMillis ?? 250,\n\t\t};\n\t\tlet removed = 0;\n\t\tlet skippedInUse = 0;\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 === 'removed') removed += 1;\n\t\t\tif (outcome === 'in-use') skippedInUse += 1;\n\t\t}\n\t\treturn { removed, skippedInUse };\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\tyield* removeVolume(volume.name);\n\t\t\tremoved += 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\tyield* removeVolume(volume.name);\n\t\t\tremoved += 1;\n\t\t}\n\t\treturn removed;\n\t}).pipe(Effect.withSpan('runtime.docker.removeDevstackVolumes'));\n"],"mappings":"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"}

package/dist/runtime/docker/volume.d.mts

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

package/dist/runtime/docker/volume.mjs

@@ -0,0 +1,24 @@
+import { dockerRunOk } from "./client.mjs";
+import { VolumeOperationFailed } from "./errors.mjs";
+import { wrapVolumeError } from "./wrap.mjs";
+import { Effect, Schema } from "effect";
+Schema.Struct({
+	Name: Schema.String,
+	Labels: Schema.optional(Schema.Unknown)
+});
+const removeVolume = (name) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("volume", [
+		"rm",
+		"--force",
+		name
+	]).pipe(Effect.mapError(wrapVolumeError("remove", name)));
+	if (res.exitCode !== 0 && !/no such volume/i.test(res.stderr)) return yield* Effect.fail(new VolumeOperationFailed({
+		op: "remove",
+		volume: name,
+		stderr: res.stderr
+	}));
+}).pipe(Effect.withSpan("runtime.docker.volume.remove"));
+//#endregion
+export { removeVolume };
+
+//# sourceMappingURL=volume.mjs.map

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

@@ -0,0 +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 { decodeJsonArrayElementSync } from '../../substrate/runtime/runtime-decode.ts';\nimport { DockerHost, DockerSpawner, dockerRun, dockerRunOk } from './client.ts';\nimport {\n\tDockerInspectDecodeFailed,\n\tDockerInspectFailed,\n\tDaemonUnreachable,\n\ttype DockerRuntimeError,\n\tForeignDockerResource,\n\tVolumeOperationFailed,\n} from './errors.ts';\nimport {\n\texpectedVolumeOwnershipLabels,\n\townershipMismatchDetail,\n\trenderVolumeLabels,\n} from './labels.ts';\nimport { isDaemonUnreachableStderr, 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 readLabels = (raw: unknown): Readonly<Record<string, string>> => {\n\tif (raw === null || typeof raw !== 'object') return {};\n\tconst out: Record<string, string> = {};\n\tfor (const [key, value] of Object.entries(raw)) {\n\t\tif (typeof value === 'string') out[key] = value;\n\t}\n\treturn out;\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 res = yield* dockerRunOk('volume', ['inspect', name]).pipe(\n\t\t\tEffect.mapError(wrapVolumeError('inspect', name)),\n\t\t);\n\t\tif (res.exitCode !== 0) {\n\t\t\tif (isNoSuchVolumeStderr(res.stderr)) return null;\n\t\t\tif (isDaemonUnreachableStderr(res.stderr)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew DaemonUnreachable({\n\t\t\t\t\t\top: 'docker.volume.inspect',\n\t\t\t\t\t\tdetail: 'docker daemon unreachable',\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew DockerInspectFailed({\n\t\t\t\t\tresource: 'volume',\n\t\t\t\t\tname,\n\t\t\t\t\tstderr: res.stderr,\n\t\t\t\t\texitCode: res.exitCode,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\ttry {\n\t\t\tconst decoded = decodeJsonArrayElementSync(VolumeInspectSchema, res.stdout, {\n\t\t\t\tsource: `docker volume inspect ${name}`,\n\t\t\t\tmissingMessage: 'inspect returned an empty result',\n\t\t\t\tmkError: (issue) =>\n\t\t\t\t\tnew DockerInspectDecodeFailed({\n\t\t\t\t\t\tresource: 'volume',\n\t\t\t\t\t\tname,\n\t\t\t\t\t\tdetail:\n\t\t\t\t\t\t\tissue.message === 'inspect returned an empty result'\n\t\t\t\t\t\t\t\t? issue.message\n\t\t\t\t\t\t\t\t: 'inspect returned malformed volume JSON',\n\t\t\t\t\t\tcause: issue.cause,\n\t\t\t\t\t}),\n\t\t\t});\n\t\t\treturn { name: decoded.Name, labels: readLabels(decoded.Labels) };\n\t\t} catch (cause) {\n\t\t\treturn yield* Effect.fail(cause as DockerRuntimeError);\n\t\t}\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":";;;;AAgC4B,OAAO,OAAO;CACzC,MAAM,OAAO;CACb,QAAQ,OAAO,SAAS,OAAO,QAAQ;CACvC,CAAC;AAoGF,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"}

package/dist/runtime/docker/wrap.d.mts

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

package/dist/runtime/docker/wrap.mjs

@@ -0,0 +1,131 @@
+import { BuildFailed, ContainerCreateFailed, ContainerNameCollisionUnrecoverable, ContainerPortPublishConflict, DaemonUnreachable, ImageNotFound, ImagePullFailed, NetworkAddressPoolExhausted, NetworkOperationFailed, VolumeOperationFailed } from "./errors.mjs";
+//#region src/runtime/docker/wrap.ts
+/** Daemon unreachable — the connection itself failed. Highest-priority
+*  classifier; if this is true, no further classification is meaningful. */
+const isDaemonUnreachableStderr = (stderr) => /Cannot connect to the Docker daemon/i.test(stderr) || /Is the docker daemon running\?/i.test(stderr) || /ENOENT.*docker/i.test(stderr);
+/** Name collision — `docker create` / `run -d` returns exit 125 with
+*  "name is already in use" wording. Architecture §1 — name-atomic create. */
+const isNameCollisionStderr = (stderr) => /is already in use by container/i.test(stderr) || /Conflict.*The container name/i.test(stderr);
+/** Port conflict — used by container resume-fallback path. */
+const isPortConflictStderr = (stderr) => /port is already allocated/i.test(stderr) || /bind.*address already in use/i.test(stderr);
+/** "No such container" — TOCTOU recovery signal. */
+const isNoSuchContainerStderr = (stderr) => /No such container/i.test(stderr) || /Error response from daemon: No such container/i.test(stderr) || /no such object/i.test(stderr);
+/** Network attach idempotency — "already exists in network" is success. */
+const isAlreadyInNetworkStderr = (stderr) => /already exists in network/i.test(stderr) || /endpoint with name .* already exists/i.test(stderr);
+/** 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);
+/** Daemon-unreachable check is the universal short-circuit. Every
+*  wrapper runs this first. */
+const checkDaemon = (err) => {
+	if (isDaemonUnreachableStderr(err.stderr)) return new DaemonUnreachable({
+		op: err.op,
+		detail: "docker daemon unreachable",
+		cause: err.cause
+	});
+	if (err.cause !== void 0 && err.exitCode === void 0) return new DaemonUnreachable({
+		op: err.op,
+		detail: "docker CLI spawn failed (binary missing or fork failure)",
+		cause: err.cause
+	});
+	return null;
+};
+const wrapPullError = (ref) => (err) => {
+	const d = checkDaemon(err);
+	if (d) return d;
+	if (isImageNotFoundStderr(err.stderr)) return new ImageNotFound({
+		ref,
+		detail: "pull target not found"
+	});
+	return new ImagePullFailed({
+		ref,
+		stderr: err.stderr,
+		exitCode: err.exitCode
+	});
+};
+const wrapBuildError = (contextPath, dockerfile) => (err) => {
+	const d = checkDaemon(err);
+	if (d) return d;
+	const parsedStep = parseFailingBuildStep(err.stdout, err.stderr);
+	return new BuildFailed({
+		contextPath,
+		dockerfile,
+		stderr: err.stderr,
+		parsedStep,
+		exitCode: err.exitCode
+	});
+};
+const wrapCreateError = (name) => (err) => {
+	const d = checkDaemon(err);
+	if (d) return d;
+	if (isNameCollisionStderr(err.stderr)) return new ContainerNameCollisionUnrecoverable({
+		name,
+		detail: "name collision; caller should attempt adopt fallback"
+	});
+	if (isPortConflictStderr(err.stderr)) return new ContainerPortPublishConflict({
+		name,
+		stderr: err.stderr,
+		exitCode: err.exitCode
+	});
+	return new ContainerCreateFailed({
+		name,
+		stderr: err.stderr,
+		exitCode: err.exitCode
+	});
+};
+const wrapNetworkError = (op, network) => (err) => {
+	const d = checkDaemon(err);
+	if (d) return d;
+	if (op === "create" && isNetworkAddressPoolExhaustedStderr(err.stderr)) return new NetworkAddressPoolExhausted({
+		network,
+		stderr: err.stderr,
+		hint: "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."
+	});
+	return new NetworkOperationFailed({
+		op,
+		network,
+		stderr: err.stderr
+	});
+};
+const wrapVolumeError = (op, volume) => (err) => {
+	const d = checkDaemon(err);
+	if (d) return d;
+	return new VolumeOperationFailed({
+		op,
+		volume,
+		stderr: err.stderr
+	});
+};
+/** Generic wrapper for op surfaces (`docker logs`, `docker inspect`,
+*  etc.) where the only distinct failure mode is daemon down. */
+const wrapGeneric = (op) => (err) => checkDaemon(err) ?? new DaemonUnreachable({
+	op,
+	detail: err.stderr || `${op} failed (exit ${err.exitCode ?? "?"})`,
+	cause: err.cause
+});
+/** STUB: extract a "failing step" line from build output. The
+*  buildkit envelope shape is documented; classic builder shape is
+*  `Step N/M : <directive>`. Returning `undefined` is fine — the raw
+*  stderr is still in the BuildFailed envelope. */
+const parseFailingBuildStep = (stdout, stderr) => {
+	const combined = `${stderr}\n${stdout}`;
+	const classic = combined.match(/Step (\d+)\/(\d+)\s*:\s*([^\n]+)/);
+	if (classic) return `Step ${classic[1]}/${classic[2]} ${classic[3]}`;
+	const buildkit = combined.match(/#(\d+)\s+ERROR\s*:\s*([^\n]+)/);
+	if (buildkit) return `#${buildkit[1]} ${buildkit[2]}`;
+};
+/** Inspect a `CaptureResult`'s exit code; if non-zero return null
+*  (caller decides what to do). Used by the lifecycle state machine
+*  to classify stderr patterns WITHOUT promoting non-zero to failure
+*  via `nonZeroIsFailure`. */
+const classifyExit = (res) => ({
+	ok: res.exitCode === 0,
+	exitCode: res.exitCode,
+	stderr: res.stderr
+});
+//#endregion
+export { classifyExit, isAlreadyInNetworkStderr, isDaemonUnreachableStderr, isImageNotFoundStderr, isNameCollisionStderr, isNoSuchContainerStderr, wrapBuildError, wrapCreateError, wrapGeneric, wrapNetworkError, wrapPullError, wrapVolumeError };
+
+//# sourceMappingURL=wrap.mjs.map

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

@@ -0,0 +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/** 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// -----------------------------------------------------------------------------\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":"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"}

package/dist/substrate/brand.d.mts

@@ -0,0 +1,24 @@
+//#region src/substrate/brand.d.ts
+declare const _brand: unique symbol;
+type Brand<T, B extends string> = T & {
+  readonly [_brand]: B;
+};
+/** Opaque per-plugin-instance identity key. Substrate-blind. */
+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. */
+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 };
+//# sourceMappingURL=brand.d.mts.map

package/dist/substrate/brand.mjs

@@ -0,0 +1,14 @@
+//#region src/substrate/brand.ts
+/** Constructor helpers. These are the boundary where unbranded strings
+*  become branded; outside this file, callers should only see branded
+*  values. */
+const pluginKey = (s) => s;
+const endpointKey = (s) => s;
+const contentHash = (s) => s;
+const chainId = (s) => s;
+const appName = (s) => s;
+const stackName = (s) => s;
+//#endregion
+export { appName, chainId, contentHash, endpointKey, pluginKey, stackName };
+
+//# sourceMappingURL=brand.mjs.map

package/dist/substrate/brand.mjs.map

@@ -0,0 +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"}

package/dist/substrate/cross-process.d.mts

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

package/dist/substrate/cross-process.mjs

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+//#region src/substrate/cross-process.ts
+const RosterHolderSchema = Schema.Struct({
+	pid: Schema.Number,
+	startTime: Schema.Number,
+	hostname: Schema.String,
+	claimedAt: Schema.Number,
+	heartbeatAt: Schema.Number,
+	intent: Schema.Literals(["normal", "snapshot"])
+});
+const RosterDocumentSchema = Schema.Struct({
+	version: Schema.Literal(1),
+	holders: Schema.Array(RosterHolderSchema)
+});
+const DEFAULT_SWEEP_POLICY = {
+	heartbeatIntervalMillis: 1e4,
+	staleAfterMillis: 3e4,
+	trustForeignHosts: true
+};
+const SnapshotReservationSchema = Schema.Struct({
+	creatorPid: Schema.Number,
+	creatorStartTime: Schema.Number,
+	createdAt: Schema.Number
+});
+//#endregion
+export { DEFAULT_SWEEP_POLICY, RosterDocumentSchema, RosterHolderSchema, SnapshotReservationSchema };
+
+//# sourceMappingURL=cross-process.mjs.map

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

@@ -0,0 +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\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. */\nexport interface RosterHolder {\n\treadonly pid: number;\n\t/** Process start-time, used for PID-reuse-safe liveness. */\n\treadonly startTime: number;\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.Number,\n\thostname: Schema.String,\n\tclaimedAt: Schema.Number,\n\theartbeatAt: Schema.Number,\n\tintent: Schema.Literals(['normal', 'snapshot']),\n});\n\nexport const RosterDocumentSchema = Schema.Struct({\n\tversion: Schema.Literal(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. */\nexport interface SnapshotReservation {\n\treadonly creatorPid: number;\n\treadonly creatorStartTime: number;\n\treadonly createdAt: number;\n}\n\nexport const SnapshotReservationSchema = Schema.Struct({\n\tcreatorPid: Schema.Number,\n\tcreatorStartTime: Schema.Number,\n\tcreatedAt: Schema.Number,\n});\n"],"mappings":";;AAsCA,MAAa,qBAAqB,OAAO,OAAO;CAC/C,KAAK,OAAO;CACZ,WAAW,OAAO;CAClB,UAAU,OAAO;CACjB,WAAW,OAAO;CAClB,aAAa,OAAO;CACpB,QAAQ,OAAO,SAAS,CAAC,UAAU,WAAW,CAAC;CAC/C,CAAC;AAEF,MAAa,uBAAuB,OAAO,OAAO;CACjD,SAAS,OAAO,QAAQ,EAAE;CAC1B,SAAS,OAAO,MAAM,mBAAmB;CACzC,CAAC;AAYF,MAAa,uBAA0C;CACtD,yBAAyB;CACzB,kBAAkB;CAClB,mBAAmB;CACnB;AAWD,MAAa,4BAA4B,OAAO,OAAO;CACtD,YAAY,OAAO;CACnB,kBAAkB,OAAO;CACzB,WAAW,OAAO;CAClB,CAAC"}