@mysten-incubation/devstack 0.0.1 → 0.1.0

package/dist/runtime/docker/sweep.mjs

@@ -1,14 +1,26 @@
 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 { dockerRunOk } from "./client.mjs";
 import { ContainerRemoveFailed, DaemonUnreachable, ImageRemoveFailed, NetworkOperationFailed } from "./errors.mjs";
+import { isMissingImageStderr, isMissingNetworkStderr, isNetworkInUseStderr, isNoSuchContainerStderr, wrapGeneric } from "./wrap.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 { forceDisconnect, listAttachedContainers } from "./network.mjs";
+import { listContainers, listDevstackContainers, listDevstackContainersByKind, listDevstackImages, listDevstackNetworks, listDevstackVolumes, listImages, listNetworks, listVolumes } from "./inventory.mjs";
+import { NETWORK_REMOVE_RETRY_PROFILE, makeSpacedRetrySchedule } from "../../substrate/runtime/retry-policy.mjs";
 import { removeVolume } from "./volume.mjs";
 import { Effect } from "effect";
 //#region src/runtime/docker/sweep.ts
+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
+	}));
+});
 /** Sweep orphan containers matching the partial label tuple. Returns
 *  the number of containers removed.
 *
@@ -42,31 +54,21 @@ const sweepOrphans = (labelMatch) => Effect.gen(function* () {
 		yield* acquireStackLock(paths.stackLockFile).pipe(Effect.mapError(mapSubstrateError));
 		const doc = yield* readClaims({
 			stackLockFile: paths.stackLockFile,
-			rosterFile: paths.rosterFile
+			rosterFile: paths.rosterFile,
+			containerClaimsFile: paths.containerClaimsFile
 		}).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;
+		if (yield* removeManagedContainer(c.name).pipe(Effect.tapCause((cause) => Effect.logWarning("sweep: docker rm -f failed", {
+			name: c.name,
+			cause
+		})), Effect.catch(() => Effect.succeed(false)))) 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* () {
@@ -85,16 +87,18 @@ const removeDevstackContainers = (labelMatch) => Effect.gen(function* () {
 	}
 	return removed;
 }).pipe(Effect.withSpan("runtime.docker.removeDevstackContainers"));
-const removeDevstackRouterContainers = (containerName) => Effect.gen(function* () {
-	const containers = yield* listDevstackRouterContainers();
+/** Remove devstack-managed containers whose generic `kind` label matches
+*  AND whose name matches. The L1 helper is plugin-blind: orchestrators
+*  pass the kind value they themselves stamp at create time. */
+const removeDevstackContainersByKindAndName = (kind, containerName) => Effect.gen(function* () {
+	const containers = yield* listDevstackContainersByKind(kind);
 	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);
+}).pipe(Effect.withSpan("runtime.docker.removeDevstackContainersByKindAndName"));
 const removeManagedImage = (ref) => Effect.gen(function* () {
 	const res = yield* dockerRunOk("image", [
 		"rm",
@@ -115,6 +119,7 @@ const removeManagedImages = (labelMatch) => Effect.gen(function* () {
 	const seen = /* @__PURE__ */ new Set();
 	for (const image of images) {
 		const ref = image.tag;
+		if (ref.endsWith(":<none>")) continue;
 		if (seen.has(ref)) continue;
 		seen.add(ref);
 		if (yield* removeManagedImage(ref)) removed += 1;
@@ -135,7 +140,6 @@ const removeDevstackImages = (labelMatch) => Effect.gen(function* () {
 	}
 	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;
@@ -155,43 +159,110 @@ const removeManagedNetworks = (labelMatch) => Effect.gen(function* () {
 	}
 	return removed;
 }).pipe(Effect.withSpan("runtime.docker.removeManagedNetworks"));
-const isNetworkInUseStderr = (stderr) => /active endpoints|has active endpoint|network .* is in use/i.test(stderr);
+/** Parse `network X has active endpoints (name:"A" id:"B")` stderr —
+*  Docker enumerates each blocking endpoint as a `(name:"…" id:"…")`
+*  tuple. Returns an empty array on non-matching stderr. */
+const parseActiveEndpointsFromStderr = (stderr) => {
+	const out = [];
+	const re = /\(name:"([^"]+)"\s+id:"([^"]+)"\)/g;
+	let m;
+	while ((m = re.exec(stderr)) !== null) out.push({
+		name: m[1],
+		id: m[2]
+	});
+	return out;
+};
 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";
+	if (res.exitCode === 0) return { kind: "removed" };
+	if (isMissingNetworkStderr(res.stderr)) return { kind: "missing" };
+	if (isNetworkInUseStderr(res.stderr)) return {
+		kind: "in-use",
+		stderr: res.stderr
+	};
 	return yield* Effect.fail(new NetworkOperationFailed({
 		op: "remove",
 		network: name,
 		stderr: res.stderr
 	}));
 });
+/** Best-effort network removal that actively evicts our own endpoints
+*  before declaring "in-use". Strategy on first in-use response:
+*    1. inspect the network for attached endpoints
+*    2. for each endpoint we own (`devstack.managed=true`), force-
+*       disconnect it
+*    3. retry `network rm`
+*  Anything still holding the network after that is reported as a
+*  foreign holder — typically a non-devstack container, a test fixture,
+*  or a sibling stack we deliberately left alone. */
 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`);
+	const first = yield* removeManagedNetworkOnce(name);
+	if (first.kind !== "in-use") return first;
+	const attachments = yield* listAttachedContainers(name).pipe(Effect.catch(() => Effect.succeed([])));
+	if (attachments.length > 0) {
+		const ownedNames = /* @__PURE__ */ new Set();
+		const all = yield* listDevstackContainers().pipe(Effect.catch(() => Effect.succeed([])));
+		for (const c of all) ownedNames.add(c.name);
+		for (const attached of attachments) {
+			if (!ownedNames.has(attached.name)) continue;
+			yield* forceDisconnect(attached.name, name).pipe(Effect.tapCause((cause) => Effect.logDebug("prune: force-disconnect failed; will retry rm anyway", {
+				network: name,
+				container: attached.name,
+				cause
+			})), Effect.catch(() => Effect.void));
+		}
 	}
-	return "in-use";
+	const lastStep = yield* removeManagedNetworkOnce(name).pipe(Effect.repeat({
+		schedule: makeSpacedRetrySchedule(options.retryDelayMillis, options.retryAttempts),
+		until: (step) => step.kind !== "in-use"
+	}));
+	if (lastStep.kind === "removed") return { kind: "removed" };
+	if (lastStep.kind === "missing") return { kind: "missing" };
+	const lastStderr = lastStep.stderr;
+	const finalAttachments = yield* listAttachedContainers(name).pipe(Effect.catch(() => Effect.succeed([])));
+	const ownedNames = /* @__PURE__ */ new Set();
+	const all = yield* listDevstackContainers().pipe(Effect.catch(() => Effect.succeed([])));
+	for (const c of all) ownedNames.add(c.name);
+	const foreign = finalAttachments.filter((a) => !ownedNames.has(a.name));
+	const attachedNames = new Set(finalAttachments.map((a) => a.name));
+	return {
+		kind: "in-use",
+		foreignHolders: foreign,
+		staleEndpoints: parseActiveEndpointsFromStderr(lastStderr).filter((ep) => !attachedNames.has(ep.name))
+	};
 });
 const removeDevstackNetworksBestEffort = (labelMatch, options = {}) => Effect.gen(function* () {
 	const networks = yield* listDevstackNetworks();
 	const retryOptions = {
-		retryAttempts: options.retryAttempts ?? 6,
-		retryDelayMillis: options.retryDelayMillis ?? 250
+		retryAttempts: options.retryAttempts ?? NETWORK_REMOVE_RETRY_PROFILE.attempts,
+		retryDelayMillis: options.retryDelayMillis ?? NETWORK_REMOVE_RETRY_PROFILE.delayMs
 	};
 	let removed = 0;
 	let skippedInUse = 0;
+	const foreignHolders = [];
+	const staleEndpoints = [];
 	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;
+		if (outcome.kind === "removed") removed += 1;
+		else if (outcome.kind === "in-use") {
+			skippedInUse += 1;
+			for (const container of outcome.foreignHolders) foreignHolders.push({
+				network: network.name,
+				container
+			});
+			for (const ep of outcome.staleEndpoints) staleEndpoints.push({
+				network: network.name,
+				name: ep.name,
+				id: ep.id
+			});
+		}
 	}
 	return {
 		removed,
-		skippedInUse
+		skippedInUse,
+		foreignHolders,
+		staleEndpoints
 	};
 }).pipe(Effect.withSpan("runtime.docker.removeDevstackNetworksBestEffort"));
 const removeManagedVolumes = (labelMatch) => Effect.gen(function* () {
@@ -199,8 +270,10 @@ const removeManagedVolumes = (labelMatch) => Effect.gen(function* () {
 	let removed = 0;
 	for (const volume of volumes) {
 		if (volume.labels[LabelKey.volumeMarker] !== "true") continue;
-		yield* removeVolume(volume.name);
-		removed += 1;
+		if (yield* removeVolume(volume.name).pipe(Effect.tapCause((cause) => Effect.logWarning("sweep: docker volume rm failed", {
+			name: volume.name,
+			cause
+		})), Effect.as(true), Effect.catch(() => Effect.succeed(false)))) removed += 1;
 	}
 	return removed;
 }).pipe(Effect.withSpan("runtime.docker.removeManagedVolumes"));
@@ -209,12 +282,14 @@ const removeDevstackVolumes = (labelMatch) => Effect.gen(function* () {
 	let removed = 0;
 	for (const volume of volumes) {
 		if (!labelsMatchAppStack(volume.labels, labelMatch)) continue;
-		yield* removeVolume(volume.name);
-		removed += 1;
+		if (yield* removeVolume(volume.name).pipe(Effect.tapCause((cause) => Effect.logWarning("sweep: docker volume rm failed", {
+			name: volume.name,
+			cause
+		})), Effect.as(true), Effect.catch(() => Effect.succeed(false)))) removed += 1;
 	}
 	return removed;
 }).pipe(Effect.withSpan("runtime.docker.removeDevstackVolumes"));
 //#endregion
-export { removeDevstackContainers, removeDevstackImages, removeDevstackNetworksBestEffort, removeDevstackRouterContainers, removeDevstackVolumes, removeManagedContainers, removeManagedImages, removeManagedNetworks, removeManagedVolumes, sweepOrphans };
+export { removeDevstackContainers, removeDevstackContainersByKindAndName, removeDevstackImages, removeDevstackNetworksBestEffort, removeDevstackVolumes, removeManagedContainers, removeManagedImages, removeManagedNetworks, removeManagedVolumes, sweepOrphans };
 
 //# sourceMappingURL=sweep.mjs.map

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 { 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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"}
+{"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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"}

package/dist/runtime/docker/volume.mjs

@@ -1,6 +1,8 @@
 import { dockerRunOk } from "./client.mjs";
 import { VolumeOperationFailed } from "./errors.mjs";
 import { wrapVolumeError } from "./wrap.mjs";
+import "./inspect-and-decode.mjs";
+import "./labels.mjs";
 import { Effect, Schema } from "effect";
 Schema.Struct({
 	Name: Schema.String,

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 { 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"}
+{"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"}

package/dist/runtime/docker/wrap.mjs

@@ -12,11 +12,40 @@ const isPortConflictStderr = (stderr) => /port is already allocated/i.test(stder
 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);
+/** Network-create collision — `docker network create` is NOT name-atomic
+*  and there is no per-name lock for networks, so two processes booting
+*  against the shared `devstack` bridge can both pass the inspect-miss and
+*  both run `create`; the loser sees this stderr. Matches the daemon's
+*  canonical wording `network with name <name> already exists` plus the
+*  `Conflict` (409) envelope libnetwork returns for the same condition.
+*  Distinct from `isAlreadyInNetworkStderr` (the connect-side
+*  endpoint-already-attached case) — this is the network object itself
+*  already existing, the signal for `ensureNetwork`'s adopt-on-collision
+*  re-inspect. */
+const isNetworkAlreadyExistsStderr = (stderr) => /network with name \S+ already exists/i.test(stderr) || /Conflict.*network/i.test(stderr) || /network \S+ 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);
+/** 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
+*  registry-auth errors (e.g. `pull access denied … repository does
+*  not exist`) as "missing" and let sweep silently skip them. Distinct
+*  from `isImageNotFoundStderr` (pull-flow-specific) — this one is the
+*  union used by idempotent remove/tag paths. */
+const isMissingImageStderr = (stderr) => /no such image|reference does not exist/i.test(stderr);
+/** Network missing — idempotent classifier for `docker network rm` /
+*  `docker network inspect`. Matches the daemon's canonical wordings:
+*  `No such network: <name>` and `network <name> not found`. A bare
+*  `/not found/` alternation would misclassify auth / permission errors
+*  on shared docker hosts. */
+const isMissingNetworkStderr = (stderr) => /no such network|network \S+ not found/i.test(stderr);
+/** Network in-use — `docker network rm` failed because endpoints are
+*  still attached. Inverse predicate of `isMissingNetworkStderr`; lives
+*  next to its siblings so the two evolve together. */
+const isNetworkInUseStderr = (stderr) => /active endpoints|has active endpoint|network .* is in use/i.test(stderr);
 /** Daemon-unreachable check is the universal short-circuit. Every
 *  wrapper runs this first. */
 const checkDaemon = (err) => {
@@ -126,6 +155,6 @@ const classifyExit = (res) => ({
 	stderr: res.stderr
 });
 //#endregion
-export { classifyExit, isAlreadyInNetworkStderr, isDaemonUnreachableStderr, isImageNotFoundStderr, isNameCollisionStderr, isNoSuchContainerStderr, wrapBuildError, wrapCreateError, wrapGeneric, wrapNetworkError, wrapPullError, wrapVolumeError };
+export { classifyExit, isAlreadyInNetworkStderr, isDaemonUnreachableStderr, isImageNotFoundStderr, isMissingImageStderr, isMissingNetworkStderr, isNameCollisionStderr, isNetworkAlreadyExistsStderr, isNetworkInUseStderr, isNoSuchContainerStderr, isPortConflictStderr, wrapBuildError, wrapCreateError, wrapGeneric, wrapNetworkError, wrapPullError, wrapVolumeError };
 
 //# sourceMappingURL=wrap.mjs.map

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/** 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":";;;;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;;;AAIlG,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;;;AAQ9B,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// 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":"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"}

package/dist/substrate/cross-process.mjs

@@ -1,26 +1,32 @@
+import { versionedDocSchema } from "./versioned-doc-schema.mjs";
 import { Schema } from "effect";
 //#region src/substrate/cross-process.ts
 const RosterHolderSchema = Schema.Struct({
 	pid: Schema.Number,
-	startTime: Schema.Number,
+	startTime: Schema.NullOr(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 RosterDocumentSchema = versionedDocSchema(1, { holders: Schema.Array(RosterHolderSchema) });
 const DEFAULT_SWEEP_POLICY = {
 	heartbeatIntervalMillis: 1e4,
 	staleAfterMillis: 3e4,
 	trustForeignHosts: true
 };
-const SnapshotReservationSchema = Schema.Struct({
+/** 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.Number,
-	createdAt: Schema.Number
+	creatorStartTime: Schema.NullOr(Schema.Number),
+	createdAt: Schema.Number,
+	hostname: Schema.String
 });
 //#endregion
 export { DEFAULT_SWEEP_POLICY, RosterDocumentSchema, RosterHolderSchema, SnapshotReservationSchema };

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\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"}
+{"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"}