@mysten-incubation/devstack 0.0.0

package/dist/runtime/docker/container.mjs

@@ -0,0 +1,562 @@
+import { StackPathsService } from "../../substrate/runtime/paths.mjs";
+import { decodeJsonArrayElementSync } from "../../substrate/runtime/runtime-decode.mjs";
+import { dockerRun, dockerRunOk } from "./client.mjs";
+import { addClaim, removeClaim } from "../../substrate/runtime/cross-process/roster.mjs";
+import { ContainerCreateFailed, ContainerNameCollisionUnrecoverable, DaemonUnreachable, DockerInspectDecodeFailed, DockerInspectFailed, ForeignDockerResource, RecreateRefused } from "./errors.mjs";
+import { LabelKey, expectedContainerOwnershipLabels, ownershipMismatchDetail, renderContainerLabels } from "./labels.mjs";
+import { classifyExit, isDaemonUnreachableStderr, isNameCollisionStderr, isNoSuchContainerStderr, wrapCreateError, wrapGeneric } from "./wrap.mjs";
+import { connect, readIps, waitForIp } from "./network.mjs";
+import { Deferred, Effect, Ref, Schema } from "effect";
+//#region src/runtime/docker/container.ts
+/** Pure decision: given the inspect facts (or null = missing), the
+*  desired image + host port bindings, and the policy, what action
+*  do we take?
+*
+*  Tested directly without the subprocess seam. */
+const decideRunAction = (facts, desiredImage, policy, desiredPortBindings = [], portBindingReconciliation = "exact", desiredConfigHash, desiredImageDigest) => {
+	if (facts === null) return { kind: "fresh" };
+	const imageMatches = facts.image === desiredImage || desiredImageDigest !== void 0 && (facts.image === desiredImageDigest || facts.imageDigest === desiredImageDigest);
+	const portsCompatible = sameBindings(facts.portBindings ?? [], desiredPortBindings) || portBindingReconciliation === "adopt-existing" && sameBindingContainerPorts(facts.portBindings ?? [], desiredPortBindings);
+	const configMatches = desiredConfigHash === void 0 || facts.labels?.[LabelKey.configHash] === desiredConfigHash;
+	if (facts.lifecycle.kind === "unknown") return routeRecreate({
+		kind: "recreate",
+		id: facts.id,
+		reason: "unknown-state"
+	}, policy);
+	if (facts.lifecycle.kind === "paused") return imageMatches && portsCompatible && configMatches ? {
+		kind: "unpause-adopt",
+		id: facts.id
+	} : routeRecreate({
+		kind: "recreate",
+		id: facts.id,
+		reason: imageMatches ? "config-mismatch" : "image-mismatch"
+	}, policy);
+	if (facts.lifecycle.kind === "running") return imageMatches && portsCompatible && configMatches ? {
+		kind: "adopt",
+		id: facts.id
+	} : routeRecreate({
+		kind: "recreate",
+		id: facts.id,
+		reason: imageMatches ? "config-mismatch" : "image-mismatch"
+	}, policy);
+	if (!imageMatches) return routeRecreate({
+		kind: "recreate",
+		id: facts.id,
+		reason: "image-mismatch"
+	}, policy);
+	if (!portsCompatible) return routeRecreate({
+		kind: "recreate",
+		id: facts.id,
+		reason: "config-mismatch"
+	}, policy);
+	if (!configMatches) return routeRecreate({
+		kind: "recreate",
+		id: facts.id,
+		reason: "config-mismatch"
+	}, policy);
+	if (facts.lifecycle.exitCode === 137) {
+		if (policy === "on-failure") return {
+			kind: "recreate",
+			id: facts.id,
+			reason: "unclean-shutdown"
+		};
+		if (policy === "never") return {
+			kind: "refuse",
+			reason: "unclean-shutdown"
+		};
+		return {
+			kind: "resume",
+			id: facts.id
+		};
+	}
+	return {
+		kind: "resume",
+		id: facts.id
+	};
+};
+/** Route a recreate-class decision through the policy. */
+const routeRecreate = (action, policy) => {
+	if (policy === "never") return {
+		kind: "refuse",
+		reason: action.reason
+	};
+	return action;
+};
+const canonicalPortBindings = (ports) => [...ports ?? []].map((p) => `${p.containerPort}/tcp=${normalizeHostIp(p.hostIp)}:${p.hostPort}`).sort();
+const sameBindings = (left, right) => left.length === right.length && left.every((value, index) => value === right[index]);
+const sameBindingContainerPorts = (left, right) => {
+	return sameBindings(left.map(bindingContainerKey).sort(), right.map(bindingContainerKey).sort());
+};
+const bindingContainerKey = (binding) => binding.split("=")[0] ?? binding;
+const normalizeHostIp = (hostIp) => hostIp === void 0 || hostIp === "" ? "0.0.0.0" : hostIp;
+const readPublishedPorts = (raw) => {
+	if (raw === null || typeof raw !== "object") return [];
+	const out = [];
+	for (const [container, bindings] of Object.entries(raw)) {
+		const containerPort = Number(container.split("/")[0]);
+		if (!Number.isInteger(containerPort) || containerPort <= 0) continue;
+		if (!Array.isArray(bindings)) continue;
+		for (const binding of bindings) {
+			if (binding === null || typeof binding !== "object") continue;
+			const hostPort = binding.HostPort;
+			if (typeof hostPort !== "string") continue;
+			const hostPortNumber = Number(hostPort);
+			if (!Number.isInteger(hostPortNumber) || hostPortNumber <= 0) continue;
+			const hostIp = binding.HostIp;
+			out.push({
+				containerPort,
+				hostPort: hostPortNumber,
+				...typeof hostIp === "string" ? { hostIp: normalizeHostIp(hostIp) } : {}
+			});
+		}
+	}
+	return out.sort((a, b) => {
+		if (a.containerPort !== b.containerPort) return a.containerPort - b.containerPort;
+		const hostIp = normalizeHostIp(a.hostIp).localeCompare(normalizeHostIp(b.hostIp));
+		return hostIp !== 0 ? hostIp : a.hostPort - b.hostPort;
+	});
+};
+const readMounts = (raw) => {
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const mount of raw) {
+		if (mount === null || typeof mount !== "object") continue;
+		const source = mount.Source;
+		const target = mount.Destination;
+		if (typeof source !== "string" || typeof target !== "string") continue;
+		const rw = mount.RW;
+		out.push({
+			source,
+			target,
+			...typeof rw === "boolean" ? { readOnly: !rw } : {}
+		});
+	}
+	return out;
+};
+const readStringArray = (raw) => {
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((value) => typeof value === "string");
+};
+const readLabels = (raw) => {
+	if (raw === null || typeof raw !== "object") return {};
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) if (typeof value === "string") out[key] = value;
+	return out;
+};
+const readNetworks = (raw) => {
+	if (raw === null || typeof raw !== "object") return [];
+	return Object.keys(raw).sort();
+};
+const readLifecycleState = (state) => {
+	if (state === void 0) return { kind: "unknown" };
+	if (state.Paused) return {
+		kind: "paused",
+		exitCode: state.ExitCode
+	};
+	if (state.Running) return {
+		kind: "running",
+		exitCode: state.ExitCode
+	};
+	return {
+		kind: "stopped",
+		exitCode: state.ExitCode
+	};
+};
+const InspectSchema = Schema.Struct({
+	Id: Schema.String,
+	Image: Schema.optional(Schema.String),
+	Mounts: Schema.optional(Schema.Unknown),
+	HostConfig: Schema.optional(Schema.Struct({ PortBindings: Schema.Unknown })),
+	State: Schema.optional(Schema.Struct({
+		Running: Schema.Boolean,
+		Paused: Schema.Boolean,
+		ExitCode: Schema.Number
+	})),
+	Config: Schema.Struct({
+		Image: Schema.String,
+		Cmd: Schema.optional(Schema.Unknown),
+		Labels: Schema.optional(Schema.Unknown)
+	}),
+	NetworkSettings: Schema.Struct({
+		Networks: Schema.Unknown,
+		Ports: Schema.optional(Schema.Unknown)
+	})
+});
+const inspectContainer = (name) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("container", ["inspect", name]).pipe(Effect.mapError(wrapGeneric("docker.container.inspect")));
+	if (res.exitCode !== 0) {
+		if (isNoSuchContainerStderr(res.stderr)) return null;
+		if (isDaemonUnreachableStderr(res.stderr)) return yield* Effect.fail(new DaemonUnreachable({
+			op: "docker.container.inspect",
+			detail: "docker daemon unreachable"
+		}));
+		return yield* Effect.fail(new DockerInspectFailed({
+			resource: "container",
+			name,
+			stderr: res.stderr,
+			exitCode: res.exitCode
+		}));
+	}
+	try {
+		const decoded = decodeJsonArrayElementSync(InspectSchema, res.stdout, {
+			source: `docker container inspect ${name}`,
+			missingMessage: "inspect returned an empty result",
+			mkError: (issue) => new DockerInspectDecodeFailed({
+				resource: "container",
+				name,
+				detail: issue.message === "inspect returned an empty result" ? issue.message : "inspect returned malformed container JSON",
+				cause: issue.cause
+			})
+		});
+		const lifecycle = readLifecycleState(decoded.State);
+		const effectivePorts = readPublishedPorts(decoded.NetworkSettings.Ports);
+		const ports = decoded.HostConfig === void 0 ? effectivePorts : readPublishedPorts(decoded.HostConfig.PortBindings);
+		const mounts = readMounts(decoded.Mounts);
+		const command = readStringArray(decoded.Config.Cmd);
+		const labels = readLabels(decoded.Config.Labels);
+		const networks = readNetworks(decoded.NetworkSettings.Networks);
+		return {
+			id: decoded.Id,
+			lifecycle,
+			running: lifecycle.kind === "running" || lifecycle.kind === "paused",
+			paused: lifecycle.kind === "paused",
+			exitCode: lifecycle.kind === "unknown" ? null : lifecycle.exitCode,
+			image: decoded.Config.Image,
+			...decoded.Image !== void 0 ? { imageDigest: decoded.Image } : {},
+			mounts,
+			portBindings: canonicalPortBindings(ports),
+			ports,
+			effectivePortBindings: canonicalPortBindings(effectivePorts),
+			effectivePorts,
+			command,
+			labels,
+			networks
+		};
+	} catch (cause) {
+		return yield* Effect.fail(cause);
+	}
+}).pipe(Effect.withSpan("runtime.docker.container.inspect"));
+const createArgv = (spec, cycle, imageRef) => {
+	const args = [
+		"-d",
+		"--name",
+		spec.name
+	];
+	const configLabels = spec.configHash === void 0 ? void 0 : { [LabelKey.configHash]: spec.configHash };
+	for (const label of renderContainerLabels(spec.labels, cycle, configLabels)) args.push("--label", label);
+	if (spec.env) for (const [k, v] of Object.entries(spec.env)) args.push("--env", `${k}=${v}`);
+	if (spec.ports) for (const p of spec.ports) {
+		const hostPrefix = p.hostIp === void 0 ? "" : `${p.hostIp}:`;
+		args.push("-p", `${hostPrefix}${p.hostPort}:${p.containerPort}`);
+	}
+	if (spec.mounts) for (const m of spec.mounts) {
+		const ro = m.readonly ? ",readonly" : "";
+		args.push("--mount", `type=bind,source=${m.source},target=${m.target}${ro}`);
+	}
+	if (spec.networkAttach && spec.networkAttach.length > 0) args.push("--network", spec.networkAttach[0]);
+	if (spec.extraHosts) for (const [host, ip] of Object.entries(spec.extraHosts)) args.push("--add-host", `${host}:${ip}`);
+	if (spec.entrypoint) args.push("--entrypoint", spec.entrypoint);
+	args.push(imageRef);
+	if (spec.command) args.push(...spec.command);
+	return args;
+};
+const handleOf = (id, name, imageName, status, ips, ports, labels) => ({
+	id,
+	name,
+	...labels !== void 0 ? { labels } : {},
+	imageName,
+	status,
+	ips,
+	...ports !== void 0 ? { ports } : {}
+});
+/** Force-remove by name. Used by recreate. Idempotent on
+*  "no such container". */
+const forceRemove = (name) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("rm", ["-f", name]).pipe(Effect.mapError(wrapGeneric("docker.rm")));
+	if (res.exitCode !== 0 && !isNoSuchContainerStderr(res.stderr)) yield* Effect.annotateCurrentSpan({ "docker.rm.warning": res.stderr });
+}).pipe(Effect.withSpan("runtime.docker.container.forceRemove"));
+const ownershipFailure = (name, expected, actual, detail) => new ForeignDockerResource({
+	resource: "container",
+	name,
+	expected,
+	actual,
+	detail
+});
+const assertOwnedFacts = (name, facts, labels) => Effect.gen(function* () {
+	const expected = expectedContainerOwnershipLabels(labels);
+	const actual = facts.labels ?? {};
+	const mismatch = ownershipMismatchDetail(expected, actual);
+	if (mismatch !== null) return yield* Effect.fail(ownershipFailure(name, expected, actual, mismatch));
+});
+const failUnknownCollisionLifecycle = (name, stage) => Effect.fail(new ContainerNameCollisionUnrecoverable({
+	name,
+	detail: `name collision recovery refused unknown lifecycle state ${stage}`
+}));
+const assertContainerHandleOwned = (handle) => Effect.gen(function* () {
+	if (handle.labels === void 0) return yield* Effect.fail(ownershipFailure(handle.name, {}, {}, "container handle has no ownership labels"));
+	const facts = yield* inspectContainer(handle.name);
+	const expected = expectedContainerOwnershipLabels(handle.labels);
+	if (facts === null) return yield* Effect.fail(ownershipFailure(handle.name, expected, {}, "container is missing"));
+	if (facts.id !== handle.id) return yield* Effect.fail(ownershipFailure(handle.name, expected, facts.labels ?? {}, `id changed to ${facts.id}`));
+	yield* assertOwnedFacts(handle.name, facts, handle.labels);
+}).pipe(Effect.withSpan("runtime.docker.container.assertOwned"));
+const forceRemoveOwned = (name, id, labels) => Effect.gen(function* () {
+	const current = yield* inspectContainer(name);
+	if (current === null) return;
+	if (current.id !== id) {
+		const expected = expectedContainerOwnershipLabels(labels);
+		return yield* Effect.fail(ownershipFailure(name, expected, current.labels ?? {}, `id changed to ${current.id}`));
+	}
+	yield* assertOwnedFacts(name, current, labels);
+	yield* forceRemove(name);
+});
+/** Single-shot start-and-adopt fallback after `docker create` exit-125
+*  with name-collision. Architecture §1 / G10 — one attempt; second
+*  collision is a typed failure. */
+const startAndAdopt = (name, labels) => Effect.gen(function* () {
+	const beforeStart = yield* inspectContainer(name);
+	if (beforeStart === null) return yield* Effect.fail(new ContainerNameCollisionUnrecoverable({
+		name,
+		detail: "name collision but inspect found no container"
+	}));
+	yield* assertOwnedFacts(name, beforeStart, labels);
+	if (beforeStart.lifecycle.kind === "unknown") return yield* failUnknownCollisionLifecycle(name, "before-start");
+	const cls = classifyExit(yield* dockerRunOk("start", [name]).pipe(Effect.mapError(wrapGeneric("docker.start"))));
+	if (cls.ok) {
+		const facts = yield* inspectContainer(name);
+		if (facts === null) return yield* Effect.fail(new ContainerNameCollisionUnrecoverable({
+			name,
+			detail: "peer collision + start succeeded + inspect missed"
+		}));
+		yield* assertOwnedFacts(name, facts, labels);
+		if (facts.lifecycle.kind === "unknown") return yield* failUnknownCollisionLifecycle(name, "after-start");
+		return facts.id;
+	}
+	if (isNoSuchContainerStderr(cls.stderr)) return yield* Effect.fail(new ContainerNameCollisionUnrecoverable({
+		name,
+		detail: "TOCTOU: start after collision found no container"
+	}));
+	return yield* Effect.fail(new ContainerNameCollisionUnrecoverable({
+		name,
+		detail: `start-and-adopt failed: ${cls.stderr}`
+	}));
+});
+const freshCreate = (spec, cycle) => Effect.gen(function* () {
+	return (yield* dockerRun("run", createArgv(spec, cycle, spec.image.tag ?? spec.image.digest)).pipe(Effect.mapError(wrapCreateError(spec.name)))).stdout.trim();
+});
+const resumeStart = (name) => Effect.gen(function* () {
+	const res = yield* dockerRunOk("start", [name]).pipe(Effect.mapError(wrapGeneric("docker.start")));
+	if (res.exitCode === 0) return { ok: true };
+	if (isDaemonUnreachableStderr(res.stderr)) return yield* Effect.fail(new DaemonUnreachable({
+		op: "docker.start",
+		detail: "docker daemon unreachable"
+	}));
+	return {
+		ok: false,
+		stderr: res.stderr
+	};
+});
+const recreateAfterResumeFailure = (id, spec, deps) => Effect.gen(function* () {
+	const routed = routeRecreate({
+		kind: "recreate",
+		id,
+		reason: "resume-failed"
+	}, spec.recreate);
+	if (routed.kind === "refuse") return yield* Effect.fail(new RecreateRefused({
+		name: spec.name,
+		reason: routed.reason
+	}));
+	yield* forceRemoveOwned(spec.name, id, spec.labels);
+	return yield* createWithCollisionRecovery(spec, deps);
+});
+const effectivePortsCompatible = (facts, spec) => {
+	const desired = canonicalPortBindings(spec.ports);
+	if (desired.length === 0) return true;
+	const actual = facts.effectivePortBindings ?? [];
+	if (sameBindings(actual, desired)) return true;
+	return (spec.portBindingReconciliation ?? "exact") === "adopt-existing" && sameBindingContainerPorts(actual, desired);
+};
+const ensureEffectivePublishedPorts = (id, spec, deps) => Effect.gen(function* () {
+	if ((spec.ports ?? []).length === 0) return id;
+	const facts = yield* inspectContainer(spec.name);
+	if (facts === null || facts.id !== id || facts.lifecycle.kind !== "running") return id;
+	yield* assertOwnedFacts(spec.name, facts, spec.labels);
+	if (effectivePortsCompatible(facts, spec)) return id;
+	const repairedId = yield* recreateAfterResumeFailure(id, spec, deps);
+	const repairedFacts = yield* inspectContainer(spec.name);
+	if (repairedFacts !== null && repairedFacts.id === repairedId && repairedFacts.lifecycle.kind === "running" && effectivePortsCompatible(repairedFacts, spec)) return repairedId;
+	return yield* Effect.fail(new ContainerCreateFailed({
+		name: spec.name,
+		stderr: `container is running but Docker did not publish requested ports: desired=${JSON.stringify(canonicalPortBindings(spec.ports))} actual=${JSON.stringify(repairedFacts?.effectivePortBindings ?? [])}`,
+		exitCode: 0
+	}));
+});
+const stopWithGrace = (name, graceSeconds, signal) => Effect.gen(function* () {
+	const args = [];
+	if (signal !== void 0) args.push("--signal", signal);
+	args.push("--time", String(Math.max(0, Math.floor(graceSeconds))));
+	args.push(name);
+	yield* dockerRunOk("stop", args).pipe(Effect.catch(() => Effect.void), Effect.asVoid);
+});
+/** Per-name lock acquire/release. The in-process serialization is the
+*  inspect→action window's invariant: two concurrent ensureContainer
+*  calls for the same name must not race between the read (inspect)
+*  and the write (create / start / recreate). Cross-process safety is
+*  separately the docker daemon's `--name` atomicity.
+*
+*  Implementation: a `Ref<Map<name, Deferred[]>>`. Acquire atomically
+*  claims the slot (free → enter with empty queue) or enqueues a fresh
+*  Deferred at the tail and awaits it. Release pops the head of the
+*  queue and completes that waiter — transferring ownership without a
+*  free intermediate window. Empty-queue release deletes the entry.
+*  No wall-clock polling: contention parks fibers on Deferred.await
+*  rather than spinning, so tests can use `it.effect` (TestClock) and
+*  contended-acquire ordering is FIFO by construction.
+*
+*  Exported for direct testing. */
+const acquirePerNameLock = (lock, name) => Effect.gen(function* () {
+	const waiter = yield* Deferred.make();
+	if (yield* Ref.modify(lock, (m) => {
+		const queue = m.get(name);
+		const next = new Map(m);
+		if (queue === void 0) {
+			next.set(name, []);
+			return [true, next];
+		}
+		next.set(name, [...queue, waiter]);
+		return [false, next];
+	})) return;
+	yield* Deferred.await(waiter).pipe(Effect.onInterrupt(() => Ref.update(lock, (m) => {
+		const queue = m.get(name);
+		if (queue === void 0) return m;
+		const filtered = queue.filter((d) => d !== waiter);
+		if (filtered.length === queue.length) return m;
+		const next = new Map(m);
+		next.set(name, filtered);
+		return next;
+	})));
+});
+const releasePerNameLock = (lock, name) => Effect.gen(function* () {
+	const head = yield* Ref.modify(lock, (m) => {
+		const queue = m.get(name);
+		if (queue === void 0) return [void 0, m];
+		const next = new Map(m);
+		if (queue.length === 0) {
+			next.delete(name);
+			return [void 0, next];
+		}
+		const [first, ...rest] = queue;
+		next.set(name, rest);
+		return [first, next];
+	});
+	if (head !== void 0) yield* Deferred.succeed(head, void 0);
+});
+/** Idempotent ensure: apply the state machine, register a scope
+*  finalizer that stops the container + releases the cross-process
+*  claim.
+*
+*  Returns the running container handle (id + name + status + ips). */
+const ensureContainer = (spec, deps) => Effect.gen(function* () {
+	const desiredImageRef = spec.image.tag ?? spec.image.digest;
+	const id = yield* Effect.acquireUseRelease(acquirePerNameLock(deps.perNameLock, spec.name), () => Effect.gen(function* () {
+		const facts = yield* inspectContainer(spec.name);
+		if (facts !== null) yield* assertOwnedFacts(spec.name, facts, spec.labels);
+		return yield* ensureEffectivePublishedPorts(yield* applyAction(decideRunAction(facts, desiredImageRef, spec.recreate, canonicalPortBindings(spec.ports), spec.portBindingReconciliation ?? "exact", spec.configHash, spec.image.digest), spec, deps), spec, deps);
+	}), () => releasePerNameLock(deps.perNameLock, spec.name));
+	yield* assertContainerHandleOwned({
+		id,
+		name: spec.name,
+		labels: spec.labels,
+		imageName: spec.image.tag ?? spec.image.digest,
+		status: "running",
+		ips: []
+	});
+	const secondaries = (spec.networkAttach ?? []).slice(1);
+	for (const net of secondaries) {
+		yield* connect(spec.name, net);
+		yield* waitForIp(spec.name, net);
+	}
+	const ips = yield* readIps(spec.name);
+	const refreshedFacts = yield* inspectContainer(spec.name);
+	const ports = refreshedFacts?.effectivePorts ?? refreshedFacts?.ports ?? spec.ports;
+	const paths = yield* StackPathsService;
+	const mapSubstrateError = (cause) => new DaemonUnreachable({
+		op: "cross-process.claim",
+		detail: `cross-process claim mutation failed: ${String(cause)}`,
+		cause
+	});
+	yield* addClaim({
+		stackLockFile: paths.stackLockFile,
+		rosterFile: paths.rosterFile
+	}, spec.name).pipe(Effect.mapError(mapSubstrateError));
+	yield* Effect.addFinalizer(() => Effect.gen(function* () {
+		if ((yield* inspectContainer(spec.name).pipe(Effect.catch(() => Effect.succeed(null))))?.id === id) yield* stopWithGrace(spec.name, spec.stopGraceSeconds ?? 10);
+		yield* removeClaim({
+			stackLockFile: paths.stackLockFile,
+			rosterFile: paths.rosterFile
+		}, spec.name).pipe(Effect.catch(() => Effect.succeed({ lastClaimReleased: false })));
+	}).pipe(Effect.uninterruptible));
+	return handleOf(id, spec.name, spec.image.tag ?? spec.image.digest, "running", ips, ports, spec.labels);
+}).pipe(Effect.withSpan("runtime.docker.container.ensure"));
+/** Apply the decided action. Recovers from name-collision via
+*  one-shot start-and-adopt; second collision surfaces typed. */
+const applyAction = (action, spec, deps) => Effect.gen(function* () {
+	switch (action.kind) {
+		case "adopt": return action.id;
+		case "unpause-adopt":
+			yield* assertContainerHandleOwned({
+				id: action.id,
+				name: spec.name,
+				labels: spec.labels,
+				imageName: spec.image.tag ?? spec.image.digest,
+				status: "paused",
+				ips: []
+			});
+			yield* unpause(spec.name);
+			return action.id;
+		case "resume":
+			yield* assertContainerHandleOwned({
+				id: action.id,
+				name: spec.name,
+				labels: spec.labels,
+				imageName: spec.image.tag ?? spec.image.digest,
+				status: "exited",
+				ips: []
+			});
+			if (!(yield* resumeStart(spec.name)).ok) return yield* recreateAfterResumeFailure(action.id, spec, deps);
+			return action.id;
+		case "recreate":
+			yield* forceRemoveOwned(spec.name, action.id, spec.labels);
+			return yield* createWithCollisionRecovery(spec, deps);
+		case "fresh": return yield* createWithCollisionRecovery(spec, deps);
+		case "refuse": return yield* Effect.fail(new RecreateRefused({
+			name: spec.name,
+			reason: action.reason
+		}));
+	}
+});
+/** `docker run -d` with single-shot start-and-adopt fallback on
+*  name-collision. */
+const createWithCollisionRecovery = (spec, deps) => freshCreate(spec, deps.cycle).pipe(Effect.catchTag("ContainerNameCollisionUnrecoverable", () => startAndAdopt(spec.name, spec.labels)), Effect.catchTag("ContainerCreateFailed", (err) => isNameCollisionStderr(err.stderr) ? startAndAdopt(spec.name, spec.labels) : Effect.fail(err)));
+const stop = (name, graceSeconds, signal) => stopWithGrace(name, graceSeconds, signal).pipe(Effect.asVoid);
+const pause = (name) => Effect.gen(function* () {
+	yield* dockerRun("pause", [name]).pipe(Effect.mapError(wrapGeneric("docker.pause")));
+}).pipe(Effect.withSpan("runtime.docker.container.pause"));
+const unpause = (name) => Effect.gen(function* () {
+	yield* dockerRun("unpause", [name]).pipe(Effect.mapError(wrapGeneric("docker.unpause")));
+}).pipe(Effect.withSpan("runtime.docker.container.unpause"));
+/** `docker commit <name> <tag>` — writable layer → image. Used by
+*  snapshot capture. */
+const commit = (name, tag) => Effect.gen(function* () {
+	const digest = (yield* dockerRun("commit", [name, tag]).pipe(Effect.mapError(wrapGeneric("docker.commit")))).stdout.trim();
+	if (digest.length === 0) return yield* Effect.fail(new ContainerCreateFailed({
+		name,
+		stderr: "commit returned empty digest",
+		exitCode: 0
+	}));
+	return digest;
+}).pipe(Effect.withSpan("runtime.docker.container.commit"));
+//#endregion
+export { assertContainerHandleOwned, commit, ensureContainer, inspectContainer, pause, stop, unpause };
+
+//# sourceMappingURL=container.mjs.map