@mysten-incubation/devstack 0.0.0

package/dist/substrate/runtime/port-broker/service.mjs

@@ -0,0 +1,319 @@
+import { RuntimeRoot } from "../paths.mjs";
+import { RosterHolderSchema } from "../../cross-process.mjs";
+import { checkHolderLiveness, ownHolder } from "../cross-process/liveness.mjs";
+import { PortBrokerError } from "../errors.mjs";
+import { decodeJsonTextSync } from "../runtime-decode.mjs";
+import { Context, Effect, Layer, Ref, Schema } from "effect";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { dirname, join } from "node:path";
+//#region src/substrate/runtime/port-broker/service.ts
+/** Allocation kind — drives the search-window starting port. Plugins
+*  pass a literal so a `wallet` allocation and a `rpc` allocation
+*  never collide on the same starting point.
+*
+*  Extend `PORT_RANGES` below to add a new kind. The literal type is
+*  closed deliberately — agnostic-naming would invite plugins to
+*  freelance kinds (and overlap window starts unintentionally).
+*
+*  Today's windows are sized for "tens of plugins per stack" with
+*  parallel-stack overhead headroom. Each window is 1000 ports; that's
+*  more than enough for any realistic in-process devstack, and the
+*  forward-scan only ever crosses a window boundary if EVERY port in
+*  the window is taken (effectively never on dev machines). */
+const PORT_KINDS = [
+	"wallet",
+	"http",
+	"rpc",
+	"misc"
+];
+/** Sequential search window per kind. The broker tries `preferredPort`
+*  first (if given), then `[start, start + window)` in order. */
+const PORT_RANGES = {
+	wallet: {
+		start: 39200,
+		window: 1e3
+	},
+	http: {
+		start: 5e4,
+		window: 1e3
+	},
+	rpc: {
+		start: 51e3,
+		window: 1e3
+	},
+	misc: {
+		start: 52e3,
+		window: 1e3
+	}
+};
+const PORT_RESERVATION_VERSION = 1;
+const PortReservationDocSchema = Schema.Struct({
+	version: Schema.Literal(PORT_RESERVATION_VERSION),
+	port: Schema.Number,
+	kind: Schema.Literals(PORT_KINDS),
+	ownerId: Schema.String,
+	holder: RosterHolderSchema
+});
+const portReservationPath = (root, port) => join(root, "port-locks", `${port}.json`);
+const parseReservationDoc = (raw) => {
+	try {
+		return decodeJsonTextSync(PortReservationDocSchema, raw, {
+			source: "port reservation",
+			mkError: (issue) => issue
+		});
+	} catch {
+		return null;
+	}
+};
+const tryWriteReservationSync = (path, doc) => {
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, `${JSON.stringify(doc)}\n`, {
+			flag: "wx",
+			mode: 384
+		});
+		return { _tag: "written" };
+	} catch (cause) {
+		if (cause.code !== "EEXIST") return {
+			_tag: "failed",
+			cause
+		};
+		if (!existsSync(path)) return { _tag: "race" };
+		try {
+			return {
+				_tag: "exists",
+				doc: parseReservationDoc(readFileSync(path, "utf8"))
+			};
+		} catch {
+			return {
+				_tag: "exists",
+				doc: null
+			};
+		}
+	}
+};
+const unlinkReservationIfOwnerSync = (path, ownerId) => {
+	try {
+		if (parseReservationDoc(readFileSync(path, "utf8"))?.ownerId === ownerId) unlinkSync(path);
+	} catch {}
+};
+const reclaimReservationIfOwnerSync = (path, ownerId) => {
+	try {
+		if (parseReservationDoc(readFileSync(path, "utf8"))?.ownerId !== ownerId) return false;
+		unlinkSync(path);
+		return true;
+	} catch {
+		return false;
+	}
+};
+const acquirePortReservation = (root, port, kind) => Effect.gen(function* () {
+	const path = portReservationPath(root, port);
+	const ownerId = `${process.pid}-${randomUUID().slice(0, 8)}`;
+	const doc = {
+		version: PORT_RESERVATION_VERSION,
+		port,
+		kind,
+		ownerId,
+		holder: ownHolder()
+	};
+	while (true) {
+		const attempt = tryWriteReservationSync(path, doc);
+		if (attempt._tag === "written") return {
+			_tag: "acquired",
+			reservation: {
+				path,
+				ownerId,
+				release: Effect.sync(() => unlinkReservationIfOwnerSync(path, ownerId))
+			}
+		};
+		if (attempt._tag === "race") continue;
+		if (attempt._tag === "failed") return {
+			_tag: "failed",
+			detail: `port reservation ${path} could not be written`,
+			cause: attempt.cause
+		};
+		if (attempt.doc === null) return { _tag: "busy" };
+		if ((yield* checkHolderLiveness(attempt.doc.holder).pipe(Effect.catch(() => Effect.succeed("alive")))) === "alive") return { _tag: "busy" };
+		if (!reclaimReservationIfOwnerSync(path, attempt.doc.ownerId)) return { _tag: "busy" };
+	}
+});
+var PortBrokerService = class extends Context.Service()("@devstack-rewrite/substrate/PortBroker") {};
+/**
+* Layer that materializes one `PortBroker` per stack scope.
+*
+* The broker's state lives in a `Ref` captured by the Layer's
+* `Effect.gen`; closing the Layer's scope drops every allocation.
+* Parallel stacks each get their own broker (Layer-driven), and they
+* coordinate cross-process via runtime-root reservation files plus the
+* kernel's bind table — never via shared in-process state.
+*/
+const layerPortBroker = Layer.effect(PortBrokerService, Effect.gen(function* () {
+	const reservationRoot = (yield* RuntimeRoot).root;
+	const state = yield* Ref.make(/* @__PURE__ */ new Map());
+	const tryReserve = (port, kind, owner) => Ref.modify(state, (current) => {
+		if (current.has(port)) return [false, current];
+		const next = new Map(current);
+		next.set(port, {
+			kind,
+			owner
+		});
+		return [true, next];
+	});
+	const drop = (port) => Ref.update(state, (current) => {
+		if (!current.has(port)) return current;
+		const next = new Map(current);
+		next.delete(port);
+		return next;
+	});
+	const allocate = (opts) => Effect.gen(function* () {
+		const range = PORT_RANGES[opts.kind];
+		const owner = opts.kind;
+		const probeHost = opts.probeHost ?? "127.0.0.1";
+		if (opts.preferredPort !== void 0) {
+			if (!(yield* tryReserve(opts.preferredPort, opts.kind, owner))) return yield* Effect.fail(new PortBrokerError({
+				reason: "preferred-busy",
+				detail: `preferred port ${opts.preferredPort} (${opts.kind}) is already held by another allocation in this stack`
+			}));
+			const reservation = yield* acquirePortReservation(reservationRoot, opts.preferredPort, opts.kind);
+			if (reservation._tag === "busy") yield* drop(opts.preferredPort);
+			else if (reservation._tag === "failed") {
+				yield* drop(opts.preferredPort);
+				return yield* Effect.fail(new PortBrokerError({
+					reason: "reservation-failed",
+					detail: reservation.detail,
+					cause: reservation.cause
+				}));
+			} else {
+				const ok = yield* probePort(opts.preferredPort, probeHost);
+				if (ok._tag === "ok") return yield* finishAllocation(opts.preferredPort, opts.kind, drop, reservation.reservation);
+				yield* reservation.reservation.release;
+				yield* drop(opts.preferredPort);
+				if (ok._tag === "probe-failed") return yield* Effect.fail(new PortBrokerError({
+					reason: "bind-probe-failed",
+					detail: `bind probe on preferred port ${opts.preferredPort} (${opts.kind}, host=${probeHost}) failed with non-EADDRINUSE error`,
+					cause: ok.cause
+				}));
+			}
+		}
+		for (let p = range.start; p < range.start + range.window; p++) {
+			if (!(yield* tryReserve(p, opts.kind, owner))) continue;
+			const reservation = yield* acquirePortReservation(reservationRoot, p, opts.kind);
+			if (reservation._tag === "busy") {
+				yield* drop(p);
+				continue;
+			}
+			if (reservation._tag === "failed") {
+				yield* drop(p);
+				return yield* Effect.fail(new PortBrokerError({
+					reason: "reservation-failed",
+					detail: reservation.detail,
+					cause: reservation.cause
+				}));
+			}
+			const ok = yield* probePort(p, probeHost);
+			if (ok._tag === "ok") return yield* finishAllocation(p, opts.kind, drop, reservation.reservation);
+			yield* reservation.reservation.release;
+			yield* drop(p);
+			if (ok._tag === "probe-failed") return yield* Effect.fail(new PortBrokerError({
+				reason: "bind-probe-failed",
+				detail: `bind probe on port ${p} (${opts.kind}, host=${probeHost}) failed with non-EADDRINUSE error`,
+				cause: ok.cause
+			}));
+		}
+		return yield* Effect.fail(new PortBrokerError({
+			reason: "no-free-port",
+			detail: `no free port found in [${range.start}, ${range.start + range.window}) for kind '${opts.kind}'`
+		}));
+	}).pipe(Effect.withSpan("substrate.portBroker.allocate", { attributes: {
+		kind: opts.kind,
+		preferredPort: opts.preferredPort ?? -1,
+		probeHost: opts.probeHost ?? "127.0.0.1"
+	} }));
+	const finishAllocation = (port, kind, dropFn, reservation) => Effect.gen(function* () {
+		const release = Effect.all([dropFn(port), reservation.release], { discard: true });
+		yield* Effect.addFinalizer(() => release.pipe(Effect.uninterruptible));
+		yield* Effect.annotateCurrentSpan({
+			"portBroker.port": port,
+			"portBroker.kind": kind
+		});
+		yield* Effect.logDebug(`port-broker allocated ${port} (kind=${kind})`);
+		return {
+			port,
+			kind,
+			release
+		};
+	});
+	return PortBrokerService.of({ allocate });
+}));
+/**
+* Bind a transient `net.Server` on `<host>:<port>` and close it.
+* The OS atomically rejects with `EADDRINUSE` if another process
+* already holds the port — that's our cross-process collision check.
+*
+* The default probe is loopback-only because the wallet binds
+* loopback. Docker-backed callers pass `0.0.0.0`; on Docker Desktop,
+* binding a transient Node server on `0.0.0.0` does not always reject
+* ports already held on `127.0.0.1`, even though Docker's publish step
+* will reject them. Wildcard probes therefore check loopback as well.
+*
+* Race window: between the probe-close and the caller's real `listen`,
+* a non-devstack process could still grab the port. Devstack peers are
+* blocked by the reservation file until the allocation scope releases.
+*/
+const probePort = (port, host) => host === "0.0.0.0" ? Effect.gen(function* () {
+	const loopback = yield* probeSinglePort(port, "127.0.0.1");
+	if (loopback._tag !== "ok") return loopback;
+	return yield* probeSinglePort(port, host);
+}).pipe(Effect.withSpan("substrate.portBroker.probe", { attributes: {
+	host,
+	port
+} })) : probeSinglePort(port, host).pipe(Effect.withSpan("substrate.portBroker.probe", { attributes: {
+	host,
+	port
+} }));
+const probeSinglePort = (port, host) => Effect.callback((resume) => {
+	let settled = false;
+	let server = null;
+	const settle = (r) => {
+		if (settled) return;
+		settled = true;
+		resume(Effect.succeed(r));
+	};
+	try {
+		server = createServer();
+		server.unref();
+		const onError = (err) => {
+			const code = err.code ?? "";
+			if (code === "EADDRINUSE" || code === "EACCES") settle({ _tag: "in-use" });
+			else settle({
+				_tag: "probe-failed",
+				cause: err
+			});
+			try {
+				server?.close();
+			} catch {}
+		};
+		server.once("error", onError);
+		server.listen(port, host, () => {
+			const addr = server?.address();
+			const ok = addr !== null && addr.port === port;
+			server?.close(() => {
+				settle(ok ? { _tag: "ok" } : { _tag: "in-use" });
+			});
+		});
+	} catch (cause) {
+		settle({
+			_tag: "probe-failed",
+			cause
+		});
+		try {
+			server?.close();
+		} catch {}
+	}
+});
+//#endregion
+export { PortBrokerService, layerPortBroker };
+
+//# sourceMappingURL=service.mjs.map

package/dist/substrate/runtime/port-broker/service.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.mjs","names":["createNetServer"],"sources":["../../../../src/substrate/runtime/port-broker/service.ts"],"sourcesContent":["// Port broker — substrate-level service.\n//\n// Architecture (`notes/redesign/architecture.md` § \"What's collapsed\"):\n// resource broker for host ports. Plugins that need to bind a host\n// HTTP server (wallet) or publish a container port on the host (Sui)\n// yield this service and call\n// `allocate({...})`. The broker:\n//\n//   1. Tracks in-process allocations in a `Ref<Map<port, Holder>>` so\n//      two sibling plugins in the same stack don't both pick the same\n//      port between bind-probe and `server.listen`.\n//   2. Claims a runtime-root scoped port reservation file before the\n//      bind probe. This closes the cross-process probe→listen race:\n//      two independent `devstack apply` processes sharing a state dir\n//      cannot both choose the same candidate while neither real server\n//      is listening yet.\n//   3. Verifies kernel-level availability by binding a transient\n//      `net.Server` on the candidate port and closing it.\n//      The OS's `EADDRINUSE` remains the final collision check for\n//      non-devstack processes and stale reservation gaps.\n//   4. Releases on scope close. The broker hands back a `release`\n//      Effect AND installs a scope finalizer; the architecture's\n//      \"scope-local, never module-level\" invariant is honoured by\n//      construction (the Layer is scope-local, the entries die with\n//      the scope).\n//\n// \"Kind-window\" sequential search: each `kind` has its own starting\n// port and window size (`PORT_RANGES`). The broker scans forward from\n// `start` up to `start + window` (and from `preferredPort` if\n// supplied) until a probe succeeds.\n//\n// Cross-process safety: the reservation file is scoped to the runtime\n// root, not the stack root, because host ports are machine-global. The\n// stack-scoped supervisor lock serializes acquires of the SAME stack;\n// these reservation files serialize host-port choices across DIFFERENT\n// stacks and apps that share a state dir.\n\nimport { randomUUID } from 'node:crypto';\nimport { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';\nimport {\n\tcreateServer as createNetServer,\n\ttype AddressInfo,\n\ttype Server as NetServer,\n} from 'node:net';\nimport { dirname, join } from 'node:path';\n\nimport { Context, Effect, Layer, Ref, Schema, Scope } from 'effect';\n\nimport { RosterHolderSchema, type RosterHolder } from '../../cross-process.ts';\nimport { checkHolderLiveness, ownHolder } from '../cross-process/liveness.ts';\nimport { PortBrokerError } from '../errors.ts';\nimport { RuntimeRoot } from '../paths.ts';\nimport { decodeJsonTextSync } from '../runtime-decode.ts';\n\n// ----------------------------------------------------------------------\n// Public shape\n// ----------------------------------------------------------------------\n\n/** Allocation kind — drives the search-window starting port. Plugins\n *  pass a literal so a `wallet` allocation and a `rpc` allocation\n *  never collide on the same starting point.\n *\n *  Extend `PORT_RANGES` below to add a new kind. The literal type is\n *  closed deliberately — agnostic-naming would invite plugins to\n *  freelance kinds (and overlap window starts unintentionally).\n *\n *  Today's windows are sized for \"tens of plugins per stack\" with\n *  parallel-stack overhead headroom. Each window is 1000 ports; that's\n *  more than enough for any realistic in-process devstack, and the\n *  forward-scan only ever crosses a window boundary if EVERY port in\n *  the window is taken (effectively never on dev machines). */\nconst PORT_KINDS = ['wallet', 'http', 'rpc', 'misc'] as const;\n\nexport type PortKind = (typeof PORT_KINDS)[number];\n\n/** Host interface used by the transient bind probe. Callers binding a\n *  real server on loopback should use the default. Callers that hand\n *  the port to Docker's all-interface publish path should pass\n *  `'0.0.0.0'` so the probe asks the same kernel question. */\nexport type PortProbeHost = '127.0.0.1' | '0.0.0.0';\n\n/** Sequential search window per kind. The broker tries `preferredPort`\n *  first (if given), then `[start, start + window)` in order. */\nconst PORT_RANGES: Readonly<Record<PortKind, { readonly start: number; readonly window: number }>> =\n\t{\n\t\t// 39200 — chosen to land between the wallet's legacy 39082 default\n\t\t// (still functional via `preferredPort`) and the high ephemeral\n\t\t// range. Stays clear of common dev-server defaults (3000-5173, 8000-\n\t\t// 8080) so a sibling Vite / Next.js process on the host doesn't\n\t\t// accidentally collide on the first probe.\n\t\twallet: { start: 39200, window: 1000 },\n\t\t// 50000 — well clear of postgres (5432), redis (6379), and the\n\t\t// Vite/Next dev-server cluster. Used by any plugin that just wants\n\t\t// \"a free HTTP port\".\n\t\thttp: { start: 50000, window: 1000 },\n\t\t// 51000 — reserved for RPC-shaped servers (graphql, custom RPC).\n\t\t// Kept distinct from `http` so the kind-window discrimination\n\t\t// surfaces in `ss -ltnp` listings during diagnosis.\n\t\trpc: { start: 51000, window: 1000 },\n\t\t// 52000 — escape hatch for plugins that don't fit the typed kinds.\n\t\tmisc: { start: 52000, window: 1000 },\n\t};\n\n/** Input to `allocate`. */\nexport interface AllocateOptions {\n\t/** Optional caller hint. The broker tries this FIRST; if the port is\n\t *  already held in-process the call FAILS with\n\t *  `reason: 'preferred-busy'` (the caller asked specifically for\n\t *  this port and got an obvious collision). If the bind-probe fails\n\t *  with EADDRINUSE the broker falls through to the kind-window\n\t *  scan — preferred is a HINT for the kernel-collision case, but a\n\t *  HARD CHOICE against in-process collision. */\n\treadonly preferredPort?: number;\n\t/** Interface to bind during the kernel probe. Defaults to\n\t *  `127.0.0.1`, matching host-loopback servers such as the wallet.\n\t *  Docker `-p host:container` publishes on all interfaces, so\n\t *  Docker-backed callers pass `0.0.0.0`. */\n\treadonly probeHost?: PortProbeHost;\n\t/** Allocation kind — drives the search window when no preferred is\n\t *  supplied (or when preferred is taken at the kernel level). */\n\treadonly kind: PortKind;\n}\n\n/** Successful allocation. `release` is provided in addition to the\n *  scope finalizer so tests / orchestrators can drive release\n *  explicitly without unwinding the whole scope. Calling `release`\n *  twice is a no-op. */\nexport interface AllocatedPort {\n\treadonly port: number;\n\treadonly kind: PortKind;\n\treadonly release: Effect.Effect<void>;\n}\n\n/** Service shape — what plugins yield from Context. */\nexport interface PortBroker {\n\t/**\n\t * Allocate a port for `kind`. The returned port is exclusive within\n\t * THIS process (the broker's `Ref` map) and best-effort-exclusive\n\t * across devstack processes that share a runtime root (port\n\t * reservation file), then verified against the kernel bind table\n\t * on `probeHost`.\n\t *\n\t * Scope-bound release: the broker installs a finalizer on the\n\t * surrounding scope; callers can additionally invoke\n\t * `result.release` explicitly.\n\t *\n\t * Failures (`PortBrokerError`):\n\t *   - `preferred-busy` — caller's `preferredPort` is held by another\n\t *     in-process allocation on the same stack.\n\t *   - `no-free-port` — the kind window was exhausted without a\n\t *     probe-pass candidate.\n\t *   - `bind-probe-failed` — non-EADDRINUSE error from the OS bind\n\t *     probe (EACCES on a privileged port etc.).\n\t *   - `reservation-failed` — port reservation file IO failed.\n\t */\n\treadonly allocate: (\n\t\topts: AllocateOptions,\n\t) => Effect.Effect<AllocatedPort, PortBrokerError, Scope.Scope>;\n}\n\n// ----------------------------------------------------------------------\n// Internal state\n// ----------------------------------------------------------------------\n\n/** In-process holder for a port. Carries the kind for diagnostics\n *  (e.g. surfaced in `no-free-port` errors). The `owner` is a\n *  free-form caller string used for log lines and the future cause\n *  walker; today every caller passes the literal `kind`. */\ninterface Holder {\n\treadonly kind: PortKind;\n\treadonly owner: string;\n}\n\ntype State = ReadonlyMap<number, Holder>;\n\nconst PORT_RESERVATION_VERSION = 1 as const;\n\nconst PortReservationDocSchema = Schema.Struct({\n\tversion: Schema.Literal(PORT_RESERVATION_VERSION),\n\tport: Schema.Number,\n\tkind: Schema.Literals(PORT_KINDS),\n\townerId: Schema.String,\n\tholder: RosterHolderSchema,\n});\n\ntype PortReservationDoc = Schema.Schema.Type<typeof PortReservationDocSchema>;\n\ninterface PortReservation {\n\treadonly path: string;\n\treadonly ownerId: string;\n\treadonly release: Effect.Effect<void>;\n}\n\ntype ReservationAttempt =\n\t| { readonly _tag: 'acquired'; readonly reservation: PortReservation }\n\t| { readonly _tag: 'busy' }\n\t| { readonly _tag: 'failed'; readonly detail: string; readonly cause: unknown };\n\ntype ReservationWriteAttempt =\n\t| { readonly _tag: 'written' }\n\t| { readonly _tag: 'race' }\n\t| { readonly _tag: 'exists'; readonly doc: PortReservationDoc | null }\n\t| { readonly _tag: 'failed'; readonly cause: unknown };\n\nconst portReservationPath = (root: string, port: number): string =>\n\tjoin(root, 'port-locks', `${port}.json`);\n\nconst parseReservationDoc = (raw: string): PortReservationDoc | null => {\n\ttry {\n\t\treturn decodeJsonTextSync(PortReservationDocSchema, raw, {\n\t\t\tsource: 'port reservation',\n\t\t\tmkError: (issue) => issue,\n\t\t});\n\t} catch {\n\t\treturn null;\n\t}\n};\n\nconst tryWriteReservationSync = (\n\tpath: string,\n\tdoc: PortReservationDoc,\n): ReservationWriteAttempt => {\n\ttry {\n\t\tmkdirSync(dirname(path), { recursive: true });\n\t\twriteFileSync(path, `${JSON.stringify(doc)}\\n`, { flag: 'wx', mode: 0o600 });\n\t\treturn { _tag: 'written' };\n\t} catch (cause) {\n\t\tconst code = (cause as NodeJS.ErrnoException).code;\n\t\tif (code !== 'EEXIST') return { _tag: 'failed', cause };\n\t\tif (!existsSync(path)) return { _tag: 'race' };\n\t\ttry {\n\t\t\treturn { _tag: 'exists', doc: parseReservationDoc(readFileSync(path, 'utf8')) };\n\t\t} catch {\n\t\t\treturn { _tag: 'exists', doc: null };\n\t\t}\n\t}\n};\n\nconst unlinkReservationIfOwnerSync = (path: string, ownerId: string): void => {\n\ttry {\n\t\tconst doc = parseReservationDoc(readFileSync(path, 'utf8'));\n\t\tif (doc?.ownerId === ownerId) {\n\t\t\tunlinkSync(path);\n\t\t}\n\t} catch {\n\t\t// Missing or unreadable: release is best-effort. A peer never\n\t\t// reclaims unreadable reservations; it simply skips that port.\n\t}\n};\n\nconst reclaimReservationIfOwnerSync = (path: string, ownerId: string): boolean => {\n\ttry {\n\t\tconst doc = parseReservationDoc(readFileSync(path, 'utf8'));\n\t\tif (doc?.ownerId !== ownerId) return false;\n\t\tunlinkSync(path);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n};\n\nconst acquirePortReservation = (\n\troot: string,\n\tport: number,\n\tkind: PortKind,\n): Effect.Effect<ReservationAttempt> =>\n\tEffect.gen(function* () {\n\t\tconst path = portReservationPath(root, port);\n\t\tconst ownerId = `${process.pid}-${randomUUID().slice(0, 8)}`;\n\t\tconst holder: RosterHolder = ownHolder();\n\t\tconst doc: PortReservationDoc = {\n\t\t\tversion: PORT_RESERVATION_VERSION,\n\t\t\tport,\n\t\t\tkind,\n\t\t\townerId,\n\t\t\tholder,\n\t\t};\n\n\t\twhile (true) {\n\t\t\tconst attempt = tryWriteReservationSync(path, doc);\n\t\t\tif (attempt._tag === 'written') {\n\t\t\t\treturn {\n\t\t\t\t\t_tag: 'acquired',\n\t\t\t\t\treservation: {\n\t\t\t\t\t\tpath,\n\t\t\t\t\t\townerId,\n\t\t\t\t\t\trelease: Effect.sync(() => unlinkReservationIfOwnerSync(path, ownerId)),\n\t\t\t\t\t},\n\t\t\t\t} as const;\n\t\t\t}\n\t\t\tif (attempt._tag === 'race') continue;\n\t\t\tif (attempt._tag === 'failed') {\n\t\t\t\treturn {\n\t\t\t\t\t_tag: 'failed',\n\t\t\t\t\tdetail: `port reservation ${path} could not be written`,\n\t\t\t\t\tcause: attempt.cause,\n\t\t\t\t} as const;\n\t\t\t}\n\t\t\tif (attempt.doc === null) return { _tag: 'busy' } as const;\n\n\t\t\tconst liveness = yield* checkHolderLiveness(attempt.doc.holder).pipe(\n\t\t\t\tEffect.catch(() => Effect.succeed('alive' as const)),\n\t\t\t);\n\t\t\tif (liveness === 'alive') return { _tag: 'busy' } as const;\n\t\t\tif (!reclaimReservationIfOwnerSync(path, attempt.doc.ownerId)) {\n\t\t\t\treturn { _tag: 'busy' } as const;\n\t\t\t}\n\t\t}\n\t});\n\n// ----------------------------------------------------------------------\n// Service tag + Layer\n// ----------------------------------------------------------------------\n\nexport class PortBrokerService extends Context.Service<PortBrokerService, PortBroker>()(\n\t'@devstack-rewrite/substrate/PortBroker',\n) {}\n\n/**\n * Layer that materializes one `PortBroker` per stack scope.\n *\n * The broker's state lives in a `Ref` captured by the Layer's\n * `Effect.gen`; closing the Layer's scope drops every allocation.\n * Parallel stacks each get their own broker (Layer-driven), and they\n * coordinate cross-process via runtime-root reservation files plus the\n * kernel's bind table — never via shared in-process state.\n */\nexport const layerPortBroker: Layer.Layer<PortBrokerService, never, RuntimeRoot> = Layer.effect(\n\tPortBrokerService,\n\tEffect.gen(function* () {\n\t\tconst runtimeRoot = yield* RuntimeRoot;\n\t\tconst reservationRoot = runtimeRoot.root;\n\t\tconst state = yield* Ref.make<State>(new Map());\n\n\t\tconst tryReserve = (port: number, kind: PortKind, owner: string): Effect.Effect<boolean> =>\n\t\t\tRef.modify<State, boolean>(state, (current) => {\n\t\t\t\tif (current.has(port)) return [false, current];\n\t\t\t\tconst next = new Map(current);\n\t\t\t\tnext.set(port, { kind, owner });\n\t\t\t\treturn [true, next];\n\t\t\t});\n\n\t\tconst drop = (port: number): Effect.Effect<void> =>\n\t\t\tRef.update(state, (current) => {\n\t\t\t\tif (!current.has(port)) return current;\n\t\t\t\tconst next = new Map(current);\n\t\t\t\tnext.delete(port);\n\t\t\t\treturn next;\n\t\t\t});\n\n\t\tconst allocate: PortBroker['allocate'] = (opts) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst range = PORT_RANGES[opts.kind];\n\t\t\t\tconst owner = opts.kind;\n\t\t\t\tconst probeHost = opts.probeHost ?? '127.0.0.1';\n\n\t\t\t\t// 1. Preferred-port path. The broker honours `preferredPort`\n\t\t\t\t//    as a strong hint, but refuses in-process collisions\n\t\t\t\t//    (architecture §6: same-stack siblings MUST NOT trample).\n\t\t\t\tif (opts.preferredPort !== undefined) {\n\t\t\t\t\tconst reserved = yield* tryReserve(opts.preferredPort, opts.kind, owner);\n\t\t\t\t\tif (!reserved) {\n\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\tnew PortBrokerError({\n\t\t\t\t\t\t\t\treason: 'preferred-busy',\n\t\t\t\t\t\t\t\tdetail:\n\t\t\t\t\t\t\t\t\t`preferred port ${opts.preferredPort} (${opts.kind}) is ` +\n\t\t\t\t\t\t\t\t\t`already held by another allocation in this stack`,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\t// Kernel-level probe. If a foreign process holds the\n\t\t\t\t\t// port, drop our reservation and FALL THROUGH to the\n\t\t\t\t\t// kind-window scan — the caller's preferred was a HINT\n\t\t\t\t\t// for cross-process collisions.\n\t\t\t\t\tconst reservation = yield* acquirePortReservation(\n\t\t\t\t\t\treservationRoot,\n\t\t\t\t\t\topts.preferredPort,\n\t\t\t\t\t\topts.kind,\n\t\t\t\t\t);\n\t\t\t\t\tif (reservation._tag === 'busy') {\n\t\t\t\t\t\tyield* drop(opts.preferredPort);\n\t\t\t\t\t} else if (reservation._tag === 'failed') {\n\t\t\t\t\t\tyield* drop(opts.preferredPort);\n\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\tnew PortBrokerError({\n\t\t\t\t\t\t\t\treason: 'reservation-failed',\n\t\t\t\t\t\t\t\tdetail: reservation.detail,\n\t\t\t\t\t\t\t\tcause: reservation.cause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tconst ok = yield* probePort(opts.preferredPort, probeHost);\n\t\t\t\t\t\tif (ok._tag === 'ok') {\n\t\t\t\t\t\t\treturn yield* finishAllocation(\n\t\t\t\t\t\t\t\topts.preferredPort,\n\t\t\t\t\t\t\t\topts.kind,\n\t\t\t\t\t\t\t\tdrop,\n\t\t\t\t\t\t\t\treservation.reservation,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tyield* reservation.reservation.release;\n\t\t\t\t\t\tyield* drop(opts.preferredPort);\n\t\t\t\t\t\tif (ok._tag === 'probe-failed') {\n\t\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\t\tnew PortBrokerError({\n\t\t\t\t\t\t\t\t\treason: 'bind-probe-failed',\n\t\t\t\t\t\t\t\t\tdetail:\n\t\t\t\t\t\t\t\t\t\t`bind probe on preferred port ${opts.preferredPort} ` +\n\t\t\t\t\t\t\t\t\t\t`(${opts.kind}, host=${probeHost}) failed with non-EADDRINUSE error`,\n\t\t\t\t\t\t\t\t\tcause: ok.cause,\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// `ok._tag === 'in-use'` — fall through to scan.\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\t// 2. Forward-scan the kind window.\n\t\t\t\tfor (let p = range.start; p < range.start + range.window; p++) {\n\t\t\t\t\tconst reserved = yield* tryReserve(p, opts.kind, owner);\n\t\t\t\t\tif (!reserved) continue;\n\t\t\t\t\tconst reservation = yield* acquirePortReservation(reservationRoot, p, opts.kind);\n\t\t\t\t\tif (reservation._tag === 'busy') {\n\t\t\t\t\t\tyield* drop(p);\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\tif (reservation._tag === 'failed') {\n\t\t\t\t\t\tyield* drop(p);\n\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\tnew PortBrokerError({\n\t\t\t\t\t\t\t\treason: 'reservation-failed',\n\t\t\t\t\t\t\t\tdetail: reservation.detail,\n\t\t\t\t\t\t\t\tcause: reservation.cause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tconst ok = yield* probePort(p, probeHost);\n\t\t\t\t\tif (ok._tag === 'ok') {\n\t\t\t\t\t\treturn yield* finishAllocation(p, opts.kind, drop, reservation.reservation);\n\t\t\t\t\t}\n\t\t\t\t\tyield* reservation.reservation.release;\n\t\t\t\t\tyield* drop(p);\n\t\t\t\t\tif (ok._tag === 'probe-failed') {\n\t\t\t\t\t\t// A privileged port (EACCES) in the middle of the\n\t\t\t\t\t\t// window is unrecoverable for this kind. Surface\n\t\t\t\t\t\t// immediately rather than thrash the whole window.\n\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\tnew PortBrokerError({\n\t\t\t\t\t\t\t\treason: 'bind-probe-failed',\n\t\t\t\t\t\t\t\tdetail:\n\t\t\t\t\t\t\t\t\t`bind probe on port ${p} (${opts.kind}, host=${probeHost}) failed ` +\n\t\t\t\t\t\t\t\t\t`with non-EADDRINUSE error`,\n\t\t\t\t\t\t\t\tcause: ok.cause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\t// In-use → next candidate.\n\t\t\t\t}\n\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew PortBrokerError({\n\t\t\t\t\t\treason: 'no-free-port',\n\t\t\t\t\t\tdetail:\n\t\t\t\t\t\t\t`no free port found in [${range.start}, ` +\n\t\t\t\t\t\t\t`${range.start + range.window}) for kind '${opts.kind}'`,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}).pipe(\n\t\t\t\tEffect.withSpan('substrate.portBroker.allocate', {\n\t\t\t\t\tattributes: {\n\t\t\t\t\t\tkind: opts.kind,\n\t\t\t\t\t\tpreferredPort: opts.preferredPort ?? -1,\n\t\t\t\t\t\tprobeHost: opts.probeHost ?? '127.0.0.1',\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t\t);\n\n\t\tconst finishAllocation = (\n\t\t\tport: number,\n\t\t\tkind: PortKind,\n\t\t\tdropFn: (p: number) => Effect.Effect<void>,\n\t\t\treservation: PortReservation,\n\t\t): Effect.Effect<AllocatedPort, never, Scope.Scope> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\t// Scope finalizer — drops the entry when the surrounding\n\t\t\t\t// scope closes. Uninterruptible so a Ctrl-C double-tap\n\t\t\t\t// doesn't leave the entry dangling in the broker's Ref.\n\t\t\t\tconst release = Effect.all([dropFn(port), reservation.release], {\n\t\t\t\t\tdiscard: true,\n\t\t\t\t});\n\t\t\t\tyield* Effect.addFinalizer(() => release.pipe(Effect.uninterruptible));\n\t\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t\t'portBroker.port': port,\n\t\t\t\t\t'portBroker.kind': kind,\n\t\t\t\t});\n\t\t\t\tyield* Effect.logDebug(`port-broker allocated ${port} (kind=${kind})`);\n\t\t\t\treturn {\n\t\t\t\t\tport,\n\t\t\t\t\tkind,\n\t\t\t\t\trelease,\n\t\t\t\t} satisfies AllocatedPort;\n\t\t\t});\n\n\t\treturn PortBrokerService.of({ allocate });\n\t}),\n);\n\n// ----------------------------------------------------------------------\n// Kernel-level bind probe\n// ----------------------------------------------------------------------\n\n/** Probe result. `'in-use'` is the recoverable case (try the next\n *  port); `'probe-failed'` is the unrecoverable case (caller's\n *  problem — surface). */\ntype ProbeResult =\n\t| { readonly _tag: 'ok' }\n\t| { readonly _tag: 'in-use' }\n\t| { readonly _tag: 'probe-failed'; readonly cause: unknown };\n\n/**\n * Bind a transient `net.Server` on `<host>:<port>` and close it.\n * The OS atomically rejects with `EADDRINUSE` if another process\n * already holds the port — that's our cross-process collision check.\n *\n * The default probe is loopback-only because the wallet binds\n * loopback. Docker-backed callers pass `0.0.0.0`; on Docker Desktop,\n * binding a transient Node server on `0.0.0.0` does not always reject\n * ports already held on `127.0.0.1`, even though Docker's publish step\n * will reject them. Wildcard probes therefore check loopback as well.\n *\n * Race window: between the probe-close and the caller's real `listen`,\n * a non-devstack process could still grab the port. Devstack peers are\n * blocked by the reservation file until the allocation scope releases.\n */\nconst probePort = (port: number, host: PortProbeHost): Effect.Effect<ProbeResult> =>\n\thost === '0.0.0.0'\n\t\t? Effect.gen(function* () {\n\t\t\t\tconst loopback = yield* probeSinglePort(port, '127.0.0.1');\n\t\t\t\tif (loopback._tag !== 'ok') return loopback;\n\t\t\t\treturn yield* probeSinglePort(port, host);\n\t\t\t}).pipe(Effect.withSpan('substrate.portBroker.probe', { attributes: { host, port } }))\n\t\t: probeSinglePort(port, host).pipe(\n\t\t\t\tEffect.withSpan('substrate.portBroker.probe', { attributes: { host, port } }),\n\t\t\t);\n\nconst probeSinglePort = (port: number, host: PortProbeHost): Effect.Effect<ProbeResult> =>\n\tEffect.callback<ProbeResult>((resume) => {\n\t\tlet settled = false;\n\t\tlet server: NetServer | null = null;\n\t\tconst settle = (r: ProbeResult): void => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tresume(Effect.succeed(r));\n\t\t};\n\t\ttry {\n\t\t\tserver = createNetServer();\n\t\t\tserver.unref();\n\t\t\tconst onError = (err: NodeJS.ErrnoException): void => {\n\t\t\t\tconst code = err.code ?? '';\n\t\t\t\tif (code === 'EADDRINUSE' || code === 'EACCES') {\n\t\t\t\t\t// EACCES on these hosts is exotic but treat as in-use\n\t\t\t\t\t// for non-privileged ports (our windows start at\n\t\t\t\t\t// 39200, well above 1024). Surfaces as probe-failed\n\t\t\t\t\t// only if it persists for every port in the window.\n\t\t\t\t\tsettle({ _tag: 'in-use' });\n\t\t\t\t} else {\n\t\t\t\t\tsettle({ _tag: 'probe-failed', cause: err });\n\t\t\t\t}\n\t\t\t\ttry {\n\t\t\t\t\tserver?.close();\n\t\t\t\t} catch {\n\t\t\t\t\t/* defensive */\n\t\t\t\t}\n\t\t\t};\n\t\t\tserver.once('error', onError);\n\t\t\tserver.listen(port, host, () => {\n\t\t\t\t// Verify the OS actually gave us THIS port (defensive —\n\t\t\t\t// asking for a specific port shouldn't ever surprise\n\t\t\t\t// us, but `address()` is the source of truth).\n\t\t\t\tconst addr = server?.address() as AddressInfo | null;\n\t\t\t\tconst ok = addr !== null && addr.port === port;\n\t\t\t\tserver?.close(() => {\n\t\t\t\t\tsettle(ok ? { _tag: 'ok' } : { _tag: 'in-use' });\n\t\t\t\t});\n\t\t\t});\n\t\t} catch (cause) {\n\t\t\tsettle({ _tag: 'probe-failed', cause });\n\t\t\ttry {\n\t\t\t\tserver?.close();\n\t\t\t} catch {\n\t\t\t\t/* defensive */\n\t\t\t}\n\t\t}\n\t});\n"],"mappings":"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"}

package/dist/substrate/runtime/post-acquire-tasks.d.mts

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

package/dist/substrate/runtime/post-acquire-tasks.mjs

@@ -0,0 +1,34 @@
+import { Context, Data, Effect, Layer, Ref, Scope } from "effect";
+//#region src/substrate/runtime/post-acquire-tasks.ts
+var PostAcquireTaskFailed = class extends Data.TaggedError("PostAcquireTaskFailed") {};
+var PostAcquireTasksService = class extends Context.Service()("@devstack-rewrite/substrate/PostAcquireTasks") {};
+const layerPostAcquireTasks = Layer.effect(PostAcquireTasksService, Effect.gen(function* () {
+	const tasksRef = yield* Ref.make([]);
+	const register = (task) => Effect.gen(function* () {
+		const scope = yield* Effect.scope;
+		const id = Symbol(task.label);
+		const registered = {
+			...task,
+			id,
+			scope
+		};
+		yield* Ref.update(tasksRef, (tasks) => [...tasks, registered]);
+		yield* Effect.addFinalizer(() => Ref.update(tasksRef, (tasks) => tasks.filter((candidate) => candidate.id !== id)));
+	});
+	const runAll = Effect.gen(function* () {
+		const tasks = yield* Ref.get(tasksRef);
+		for (const task of tasks) yield* Scope.provide(task.run, task.scope).pipe(Effect.mapError((cause) => new PostAcquireTaskFailed({
+			pluginKey: task.pluginKey,
+			label: task.label,
+			cause
+		})));
+	});
+	return PostAcquireTasksService.of({
+		register,
+		runAll
+	});
+}));
+//#endregion
+export { PostAcquireTaskFailed, PostAcquireTasksService, layerPostAcquireTasks };
+
+//# sourceMappingURL=post-acquire-tasks.mjs.map

package/dist/substrate/runtime/post-acquire-tasks.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-acquire-tasks.mjs","names":[],"sources":["../../../src/substrate/runtime/post-acquire-tasks.ts"],"sourcesContent":["import { Context, Data, Effect, Layer, Ref, Scope } from 'effect';\n\nimport type { PluginKey } from '../brand.ts';\n\nexport interface PostAcquireTask {\n\treadonly pluginKey: PluginKey;\n\treadonly label: string;\n\treadonly run: Effect.Effect<void, unknown, Scope.Scope>;\n}\n\nexport class PostAcquireTaskFailed extends Data.TaggedError('PostAcquireTaskFailed')<{\n\treadonly pluginKey: PluginKey;\n\treadonly label: string;\n\treadonly cause: unknown;\n}> {}\n\nexport interface PostAcquireTasksShape {\n\treadonly register: (task: PostAcquireTask) => Effect.Effect<void, never, Scope.Scope>;\n\treadonly runAll: Effect.Effect<void, PostAcquireTaskFailed, never>;\n}\n\nexport class PostAcquireTasksService extends Context.Service<\n\tPostAcquireTasksService,\n\tPostAcquireTasksShape\n>()('@devstack-rewrite/substrate/PostAcquireTasks') {}\n\ninterface RegisteredPostAcquireTask extends PostAcquireTask {\n\treadonly id: symbol;\n\treadonly scope: Scope.Scope;\n}\n\nexport const layerPostAcquireTasks: Layer.Layer<PostAcquireTasksService> = Layer.effect(\n\tPostAcquireTasksService,\n\tEffect.gen(function* () {\n\t\tconst tasksRef = yield* Ref.make<ReadonlyArray<RegisteredPostAcquireTask>>([]);\n\n\t\tconst register = (task: PostAcquireTask): Effect.Effect<void, never, Scope.Scope> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst scope = yield* Effect.scope;\n\t\t\t\tconst id = Symbol(task.label);\n\t\t\t\tconst registered: RegisteredPostAcquireTask = { ...task, id, scope };\n\t\t\t\tyield* Ref.update(tasksRef, (tasks) => [...tasks, registered]);\n\t\t\t\tyield* Effect.addFinalizer(() =>\n\t\t\t\t\tRef.update(tasksRef, (tasks) => tasks.filter((candidate) => candidate.id !== id)),\n\t\t\t\t);\n\t\t\t});\n\n\t\tconst runAll: Effect.Effect<void, PostAcquireTaskFailed, never> = Effect.gen(function* () {\n\t\t\tconst tasks = yield* Ref.get(tasksRef);\n\t\t\tfor (const task of tasks) {\n\t\t\t\tyield* Scope.provide(task.run, task.scope).pipe(\n\t\t\t\t\tEffect.mapError(\n\t\t\t\t\t\t(cause) =>\n\t\t\t\t\t\t\tnew PostAcquireTaskFailed({\n\t\t\t\t\t\t\t\tpluginKey: task.pluginKey,\n\t\t\t\t\t\t\t\tlabel: task.label,\n\t\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t}\n\t\t});\n\n\t\treturn PostAcquireTasksService.of({ register, runAll });\n\t}),\n);\n"],"mappings":";;AAUA,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAIjF;AAOH,IAAa,0BAAb,cAA6C,QAAQ,SAGlD,CAAC,+CAA+C,CAAC;AAOpD,MAAa,wBAA8D,MAAM,OAChF,yBACA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,IAAI,KAA+C,EAAE,CAAC;CAE9E,MAAM,YAAY,SACjB,OAAO,IAAI,aAAa;EACvB,MAAM,QAAQ,OAAO,OAAO;EAC5B,MAAM,KAAK,OAAO,KAAK,MAAM;EAC7B,MAAM,aAAwC;GAAE,GAAG;GAAM;GAAI;GAAO;AACpE,SAAO,IAAI,OAAO,WAAW,UAAU,CAAC,GAAG,OAAO,WAAW,CAAC;AAC9D,SAAO,OAAO,mBACb,IAAI,OAAO,WAAW,UAAU,MAAM,QAAQ,cAAc,UAAU,OAAO,GAAG,CAAC,CACjF;GACA;CAEH,MAAM,SAA4D,OAAO,IAAI,aAAa;EACzF,MAAM,QAAQ,OAAO,IAAI,IAAI,SAAS;AACtC,OAAK,MAAM,QAAQ,MAClB,QAAO,MAAM,QAAQ,KAAK,KAAK,KAAK,MAAM,CAAC,KAC1C,OAAO,UACL,UACA,IAAI,sBAAsB;GACzB,WAAW,KAAK;GAChB,OAAO,KAAK;GACZ;GACA,CAAC,CACH,CACD;GAED;AAEF,QAAO,wBAAwB,GAAG;EAAE;EAAU;EAAQ,CAAC;EACtD,CACF"}

package/dist/substrate/runtime/probes.d.mts

@@ -0,0 +1,51 @@
+import { Effect } from "effect";
+import * as _$effect_Types0 from "effect/Types";
+import * as _$effect_Cause0 from "effect/Cause";
+
+//#region src/substrate/runtime/probes.d.ts
+declare namespace probes_d_exports {
+  export { ExitCodeProbeResult, ProbeAttemptResult, ProbeAttemptTimeoutError, ProbeOptions, ProbeTimeoutError, exitCodeProbeResult, waitForProbe };
+}
+type ProbeAttemptResult = void | boolean | {
+  readonly ready: boolean;
+  readonly detail?: unknown;
+};
+interface ProbeOptions<E = unknown, R = never> {
+  readonly label: string;
+  readonly timeoutMs: number;
+  readonly intervalMs?: number;
+  readonly attemptTimeoutMs?: number;
+  readonly probe: () => Effect.Effect<ProbeAttemptResult, E, R>;
+  readonly isRetryableError?: (error: E) => boolean;
+}
+declare const ProbeAttemptTimeoutError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "ProbeAttemptTimeoutError";
+} & Readonly<A>;
+declare class ProbeAttemptTimeoutError extends ProbeAttemptTimeoutError_base<{
+  readonly label: string;
+  readonly attemptTimeoutMs: number;
+  readonly message: string;
+}> {}
+declare const ProbeTimeoutError_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "ProbeTimeoutError";
+} & Readonly<A>;
+declare class ProbeTimeoutError extends ProbeTimeoutError_base<{
+  readonly label: string;
+  readonly timeoutMs: number;
+  readonly intervalMs: number;
+  readonly attemptTimeoutMs?: number;
+  readonly attempts: number;
+  readonly message: string;
+  readonly lastError?: unknown;
+  readonly lastNotReady?: unknown;
+}> {}
+declare const waitForProbe: <E, R = never>(options: ProbeOptions<E, R>) => Effect.Effect<void, E | ProbeTimeoutError, R>;
+interface ExitCodeProbeResult {
+  readonly exitCode: number;
+  readonly stdout?: string;
+  readonly stderr?: string;
+}
+declare const exitCodeProbeResult: (result: ExitCodeProbeResult) => ProbeAttemptResult;
+//#endregion
+export { probes_d_exports };
+//# sourceMappingURL=probes.d.mts.map

package/dist/substrate/runtime/probes.mjs

@@ -0,0 +1,84 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.mjs";
+import { Data, Duration, Effect } from "effect";
+//#region src/substrate/runtime/probes.ts
+var probes_exports = /* @__PURE__ */ __exportAll({
+	ProbeAttemptTimeoutError: () => ProbeAttemptTimeoutError,
+	ProbeTimeoutError: () => ProbeTimeoutError,
+	exitCodeProbeResult: () => exitCodeProbeResult,
+	waitForProbe: () => waitForProbe
+});
+var ProbeAttemptTimeoutError = class extends Data.TaggedError("ProbeAttemptTimeoutError") {};
+var ProbeTimeoutError = class extends Data.TaggedError("ProbeTimeoutError") {};
+const DEFAULT_INTERVAL_MS = 250;
+const normalizeAttempt = (result) => {
+	if (result === void 0 || result === true) return { ready: true };
+	if (result === false) return { ready: false };
+	return result;
+};
+const withAttemptTimeout = (effect, options) => {
+	if (options.attemptTimeoutMs === void 0) return effect;
+	const timeoutMs = Math.max(1, Math.min(options.attemptTimeoutMs, options.remainingMs));
+	return effect.pipe(Effect.timeoutOrElse({
+		duration: Duration.millis(timeoutMs),
+		orElse: () => Effect.fail(new ProbeAttemptTimeoutError({
+			label: options.label,
+			attemptTimeoutMs: timeoutMs,
+			message: `Probe ${options.label} attempt did not complete within ${timeoutMs}ms`
+		}))
+	}));
+};
+const waitForProbe = (options) => Effect.gen(function* () {
+	const timeoutMs = options.timeoutMs;
+	const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+	const deadline = Date.now() + timeoutMs;
+	let attempts = 0;
+	let lastError;
+	let lastNotReady;
+	for (;;) {
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) return yield* Effect.fail(new ProbeTimeoutError({
+			label: options.label,
+			timeoutMs,
+			intervalMs,
+			...options.attemptTimeoutMs === void 0 ? {} : { attemptTimeoutMs: options.attemptTimeoutMs },
+			attempts,
+			message: `Probe ${options.label} did not become ready within ${timeoutMs}ms`,
+			...lastError === void 0 ? {} : { lastError },
+			...lastNotReady === void 0 ? {} : { lastNotReady }
+		}));
+		attempts += 1;
+		if (yield* withAttemptTimeout(options.probe(), {
+			label: options.label,
+			attemptTimeoutMs: options.attemptTimeoutMs,
+			remainingMs
+		}).pipe(Effect.matchEffect({
+			onFailure: (error) => {
+				if (!(error instanceof ProbeAttemptTimeoutError) && options.isRetryableError?.(error) === false) return Effect.fail(error);
+				lastError = error;
+				return Effect.succeed(false);
+			},
+			onSuccess: (result) => {
+				const normalized = normalizeAttempt(result);
+				if (!normalized.ready) lastNotReady = normalized.detail ?? false;
+				return Effect.succeed(normalized.ready);
+			}
+		}))) return;
+		const sleepMs = Math.min(intervalMs, Math.max(1, deadline - Date.now()));
+		yield* Effect.sleep(Duration.millis(sleepMs));
+	}
+});
+const exitCodeProbeResult = (result) => {
+	if (result.exitCode === 0) return true;
+	return {
+		ready: false,
+		detail: {
+			exitCode: result.exitCode,
+			...result.stdout === void 0 ? {} : { stdout: result.stdout },
+			...result.stderr === void 0 ? {} : { stderr: result.stderr }
+		}
+	};
+};
+//#endregion
+export { ProbeTimeoutError, exitCodeProbeResult, probes_exports, waitForProbe };
+
+//# sourceMappingURL=probes.mjs.map

package/dist/substrate/runtime/probes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"probes.mjs","names":[],"sources":["../../../src/substrate/runtime/probes.ts"],"sourcesContent":["import { Data, Duration, Effect } from 'effect';\n\nexport type ProbeAttemptResult =\n\t| void\n\t| boolean\n\t| {\n\t\t\treadonly ready: boolean;\n\t\t\treadonly detail?: unknown;\n\t  };\n\nexport interface ProbeOptions<E = unknown, R = never> {\n\treadonly label: string;\n\treadonly timeoutMs: number;\n\treadonly intervalMs?: number;\n\treadonly attemptTimeoutMs?: number;\n\treadonly probe: () => Effect.Effect<ProbeAttemptResult, E, R>;\n\treadonly isRetryableError?: (error: E) => boolean;\n}\n\nexport class ProbeAttemptTimeoutError extends Data.TaggedError('ProbeAttemptTimeoutError')<{\n\treadonly label: string;\n\treadonly attemptTimeoutMs: number;\n\treadonly message: string;\n}> {}\n\nexport class ProbeTimeoutError extends Data.TaggedError('ProbeTimeoutError')<{\n\treadonly label: string;\n\treadonly timeoutMs: number;\n\treadonly intervalMs: number;\n\treadonly attemptTimeoutMs?: number;\n\treadonly attempts: number;\n\treadonly message: string;\n\treadonly lastError?: unknown;\n\treadonly lastNotReady?: unknown;\n}> {}\n\nconst DEFAULT_INTERVAL_MS = 250;\n\nconst normalizeAttempt = (\n\tresult: ProbeAttemptResult,\n): { readonly ready: boolean; readonly detail?: unknown } => {\n\tif (result === undefined || result === true) return { ready: true };\n\tif (result === false) return { ready: false };\n\treturn result;\n};\n\nconst withAttemptTimeout = <A, E, R>(\n\teffect: Effect.Effect<A, E, R>,\n\toptions: {\n\t\treadonly label: string;\n\t\treadonly attemptTimeoutMs?: number;\n\t\treadonly remainingMs: number;\n\t},\n): Effect.Effect<A, E | ProbeAttemptTimeoutError, R> => {\n\tif (options.attemptTimeoutMs === undefined) return effect;\n\tconst timeoutMs = Math.max(1, Math.min(options.attemptTimeoutMs, options.remainingMs));\n\treturn effect.pipe(\n\t\tEffect.timeoutOrElse({\n\t\t\tduration: Duration.millis(timeoutMs),\n\t\t\torElse: () =>\n\t\t\t\tEffect.fail(\n\t\t\t\t\tnew ProbeAttemptTimeoutError({\n\t\t\t\t\t\tlabel: options.label,\n\t\t\t\t\t\tattemptTimeoutMs: timeoutMs,\n\t\t\t\t\t\tmessage: `Probe ${options.label} attempt did not complete within ${timeoutMs}ms`,\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t}),\n\t);\n};\n\nexport const waitForProbe = <E, R = never>(\n\toptions: ProbeOptions<E, R>,\n): Effect.Effect<void, E | ProbeTimeoutError, R> =>\n\tEffect.gen(function* () {\n\t\tconst timeoutMs = options.timeoutMs;\n\t\tconst intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;\n\t\tconst started = Date.now();\n\t\tconst deadline = started + timeoutMs;\n\t\tlet attempts = 0;\n\t\tlet lastError: unknown;\n\t\tlet lastNotReady: unknown;\n\n\t\tfor (;;) {\n\t\t\tconst remainingMs = deadline - Date.now();\n\t\t\tif (remainingMs <= 0) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew ProbeTimeoutError({\n\t\t\t\t\t\tlabel: options.label,\n\t\t\t\t\t\ttimeoutMs,\n\t\t\t\t\t\tintervalMs,\n\t\t\t\t\t\t...(options.attemptTimeoutMs === undefined\n\t\t\t\t\t\t\t? {}\n\t\t\t\t\t\t\t: { attemptTimeoutMs: options.attemptTimeoutMs }),\n\t\t\t\t\t\tattempts,\n\t\t\t\t\t\tmessage: `Probe ${options.label} did not become ready within ${timeoutMs}ms`,\n\t\t\t\t\t\t...(lastError === undefined ? {} : { lastError }),\n\t\t\t\t\t\t...(lastNotReady === undefined ? {} : { lastNotReady }),\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tattempts += 1;\n\t\t\tconst ready = yield* withAttemptTimeout(options.probe(), {\n\t\t\t\tlabel: options.label,\n\t\t\t\tattemptTimeoutMs: options.attemptTimeoutMs,\n\t\t\t\tremainingMs,\n\t\t\t}).pipe(\n\t\t\t\tEffect.matchEffect({\n\t\t\t\t\tonFailure: (error) => {\n\t\t\t\t\t\tif (\n\t\t\t\t\t\t\t!(error instanceof ProbeAttemptTimeoutError) &&\n\t\t\t\t\t\t\toptions.isRetryableError?.(error as E) === false\n\t\t\t\t\t\t) {\n\t\t\t\t\t\t\treturn Effect.fail(error as E);\n\t\t\t\t\t\t}\n\t\t\t\t\t\tlastError = error;\n\t\t\t\t\t\treturn Effect.succeed(false);\n\t\t\t\t\t},\n\t\t\t\t\tonSuccess: (result) => {\n\t\t\t\t\t\tconst normalized = normalizeAttempt(result);\n\t\t\t\t\t\tif (!normalized.ready) lastNotReady = normalized.detail ?? false;\n\t\t\t\t\t\treturn Effect.succeed(normalized.ready);\n\t\t\t\t\t},\n\t\t\t\t}),\n\t\t\t);\n\t\t\tif (ready) return;\n\n\t\t\tconst sleepMs = Math.min(intervalMs, Math.max(1, deadline - Date.now()));\n\t\t\tyield* Effect.sleep(Duration.millis(sleepMs));\n\t\t}\n\t});\n\nexport interface ExitCodeProbeResult {\n\treadonly exitCode: number;\n\treadonly stdout?: string;\n\treadonly stderr?: string;\n}\n\nexport const exitCodeProbeResult = (result: ExitCodeProbeResult): ProbeAttemptResult => {\n\tif (result.exitCode === 0) return true;\n\treturn {\n\t\tready: false,\n\t\tdetail: {\n\t\t\texitCode: result.exitCode,\n\t\t\t...(result.stdout === undefined ? {} : { stdout: result.stdout }),\n\t\t\t...(result.stderr === undefined ? {} : { stderr: result.stderr }),\n\t\t},\n\t};\n};\n"],"mappings":";;;;;;;;;AAmBA,IAAa,2BAAb,cAA8C,KAAK,YAAY,2BAA2B,CAIvF;AAEH,IAAa,oBAAb,cAAuC,KAAK,YAAY,oBAAoB,CASzE;AAEH,MAAM,sBAAsB;AAE5B,MAAM,oBACL,WAC4D;AAC5D,KAAI,WAAW,KAAA,KAAa,WAAW,KAAM,QAAO,EAAE,OAAO,MAAM;AACnE,KAAI,WAAW,MAAO,QAAO,EAAE,OAAO,OAAO;AAC7C,QAAO;;AAGR,MAAM,sBACL,QACA,YAKuD;AACvD,KAAI,QAAQ,qBAAqB,KAAA,EAAW,QAAO;CACnD,MAAM,YAAY,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ,kBAAkB,QAAQ,YAAY,CAAC;AACtF,QAAO,OAAO,KACb,OAAO,cAAc;EACpB,UAAU,SAAS,OAAO,UAAU;EACpC,cACC,OAAO,KACN,IAAI,yBAAyB;GAC5B,OAAO,QAAQ;GACf,kBAAkB;GAClB,SAAS,SAAS,QAAQ,MAAM,mCAAmC,UAAU;GAC7E,CAAC,CACF;EACF,CAAC,CACF;;AAGF,MAAa,gBACZ,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,YAAY,QAAQ;CAC1B,MAAM,aAAa,QAAQ,cAAc;CAEzC,MAAM,WADU,KAAK,KACG,GAAG;CAC3B,IAAI,WAAW;CACf,IAAI;CACJ,IAAI;AAEJ,UAAS;EACR,MAAM,cAAc,WAAW,KAAK,KAAK;AACzC,MAAI,eAAe,EAClB,QAAO,OAAO,OAAO,KACpB,IAAI,kBAAkB;GACrB,OAAO,QAAQ;GACf;GACA;GACA,GAAI,QAAQ,qBAAqB,KAAA,IAC9B,EAAE,GACF,EAAE,kBAAkB,QAAQ,kBAAkB;GACjD;GACA,SAAS,SAAS,QAAQ,MAAM,+BAA+B,UAAU;GACzE,GAAI,cAAc,KAAA,IAAY,EAAE,GAAG,EAAE,WAAW;GAChD,GAAI,iBAAiB,KAAA,IAAY,EAAE,GAAG,EAAE,cAAc;GACtD,CAAC,CACF;AAGF,cAAY;AAwBZ,MAAI,OAvBiB,mBAAmB,QAAQ,OAAO,EAAE;GACxD,OAAO,QAAQ;GACf,kBAAkB,QAAQ;GAC1B;GACA,CAAC,CAAC,KACF,OAAO,YAAY;GAClB,YAAY,UAAU;AACrB,QACC,EAAE,iBAAiB,6BACnB,QAAQ,mBAAmB,MAAW,KAAK,MAE3C,QAAO,OAAO,KAAK,MAAW;AAE/B,gBAAY;AACZ,WAAO,OAAO,QAAQ,MAAM;;GAE7B,YAAY,WAAW;IACtB,MAAM,aAAa,iBAAiB,OAAO;AAC3C,QAAI,CAAC,WAAW,MAAO,gBAAe,WAAW,UAAU;AAC3D,WAAO,OAAO,QAAQ,WAAW,MAAM;;GAExC,CAAC,CACF,CACU;EAEX,MAAM,UAAU,KAAK,IAAI,YAAY,KAAK,IAAI,GAAG,WAAW,KAAK,KAAK,CAAC,CAAC;AACxE,SAAO,OAAO,MAAM,SAAS,OAAO,QAAQ,CAAC;;EAE7C;AAQH,MAAa,uBAAuB,WAAoD;AACvF,KAAI,OAAO,aAAa,EAAG,QAAO;AAClC,QAAO;EACN,OAAO;EACP,QAAQ;GACP,UAAU,OAAO;GACjB,GAAI,OAAO,WAAW,KAAA,IAAY,EAAE,GAAG,EAAE,QAAQ,OAAO,QAAQ;GAChE,GAAI,OAAO,WAAW,KAAA,IAAY,EAAE,GAAG,EAAE,QAAQ,OAAO,QAAQ;GAChE;EACD"}

package/dist/substrate/runtime/process-supervisor.d.mts

@@ -0,0 +1,57 @@
+import { Effect } from "effect";
+import { Readable } from "node:stream";
+
+//#region src/substrate/runtime/process-supervisor.d.ts
+declare namespace process_supervisor_d_exports {
+  export { AwaitManagedProcessReadyOptions, ManagedProcessChild, ManagedProcessExitStatus, ManagedProcessSpawnOptions, ManagedProcessSpawner, TerminateManagedProcessOptions, awaitManagedProcessReady, awaitProcessExit, describeProcessExitStatus, getProcessExitStatus, nodeProcessSpawner, onceProcessError, onceProcessExit, terminateManagedProcess, waitForProcessExitOrTimeout };
+}
+interface ManagedProcessExitStatus {
+  readonly code: number | null;
+  readonly signal: NodeJS.Signals | null;
+}
+interface ManagedProcessChild {
+  readonly pid?: number;
+  readonly stdout?: Readable | null;
+  readonly stderr?: Readable | null;
+  readonly exitCode?: number | null;
+  readonly signalCode?: NodeJS.Signals | null;
+  kill(signal?: NodeJS.Signals): boolean;
+  on(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+  on(event: 'error', listener: (cause: Error) => void): this;
+  once(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+  once(event: 'error', listener: (cause: Error) => void): this;
+  off(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;
+  off(event: 'error', listener: (cause: Error) => void): this;
+}
+interface ManagedProcessSpawnOptions {
+  readonly cwd: string;
+  readonly env: NodeJS.ProcessEnv;
+  readonly stdio: 'pipe';
+  readonly detached?: boolean;
+}
+type ManagedProcessSpawner = (command: string, args: ReadonlyArray<string>, options: ManagedProcessSpawnOptions) => ManagedProcessChild;
+declare const nodeProcessSpawner: ManagedProcessSpawner;
+declare const describeProcessExitStatus: (status: ManagedProcessExitStatus) => string;
+declare const onceProcessExit: (child: ManagedProcessChild) => Promise<ManagedProcessExitStatus>;
+declare const getProcessExitStatus: (child: ManagedProcessChild) => ManagedProcessExitStatus | null;
+declare const awaitProcessExit: (child: ManagedProcessChild) => Promise<ManagedProcessExitStatus>;
+declare const onceProcessError: (child: ManagedProcessChild) => Promise<unknown>;
+declare const waitForProcessExitOrTimeout: (child: ManagedProcessChild, timeoutMs: number) => Promise<ManagedProcessExitStatus | null>;
+interface TerminateManagedProcessOptions {
+  readonly graceMs: number;
+  readonly killTimeoutMs?: number;
+  readonly processGroup?: boolean;
+  readonly onEscalate?: () => Effect.Effect<void>;
+}
+declare const terminateManagedProcess: (child: ManagedProcessChild, options: TerminateManagedProcessOptions) => Effect.Effect<void>;
+interface AwaitManagedProcessReadyOptions<E, R = never> {
+  readonly ready: Effect.Effect<void, E, R>;
+  readonly exit: Promise<ManagedProcessExitStatus>;
+  readonly processError: Promise<unknown>;
+  readonly onExitBeforeReady: (status: ManagedProcessExitStatus) => E;
+  readonly onProcessErrorBeforeReady: (cause: unknown) => E;
+}
+declare const awaitManagedProcessReady: <E, R = never>(options: AwaitManagedProcessReadyOptions<E, R>) => Effect.Effect<void, E, R>;
+//#endregion
+export { process_supervisor_d_exports };
+//# sourceMappingURL=process-supervisor.d.mts.map