@mysten-incubation/devstack 0.1.1 → 0.2.0

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

@@ -1,15 +1,15 @@
-import { RuntimeRoot } from "../paths.mjs";
+import { decodeJsonTextSync } from "../runtime-decode.mjs";
 import { versionedDocSchema } from "../../versioned-doc-schema.mjs";
+import { RosterHolderSchema } from "../../cross-process.mjs";
 import { selfPid } from "../cross-process/self-pid.mjs";
 import { PortBrokerError } from "../errors.mjs";
 import { atomicWriteFileExclusiveSync } from "../atomic-write.mjs";
-import { decodeJsonTextSync } from "../runtime-decode.mjs";
-import { RosterHolderSchema } from "../../cross-process.mjs";
 import { checkHolderLiveness, ownHolder } from "../cross-process/liveness.mjs";
+import { RuntimeRoot } from "../paths.mjs";
 import { Context, Effect, Layer, Ref, Schema } from "effect";
 import { readFileSync, unlinkSync } from "node:fs";
-import { randomUUID } from "node:crypto";
 import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 import { createServer } from "node:net";
 //#region src/substrate/runtime/port-broker/service.ts
 /** Default scan window. Sized for "tens of plugins per stack" with
@@ -172,11 +172,10 @@ const layerPortBroker = Layer.effect(PortBrokerService, Effect.gen(function* ()
 	*  interrupt, typed failure, or a non-`kept` success outcome.
 	*  Without this, an interrupt landing between the reservation write
 	*  (in `acquirePortReservation`) and the finalizer arm (in
-	*  `finishAllocation`) left the file on disk while the old release
-	*  only dropped the in-process slot — leaking
-	*  `port-locks/<port>.json`. Its `holder` is this still-alive
-	*  process, so every future `allocate` of that port then saw
-	*  `checkHolderLiveness` report `alive`, marking it busy for the
+	*  `finishAllocation`) would leave `port-locks/<port>.json` on disk
+	*  while only dropping the in-process slot. Its `holder` is this
+	*  still-alive process, so every future `allocate` of that port then
+	*  sees `checkHolderLiveness` report `alive`, marking it busy for the
 	*  whole supervisor lifetime.
 	*
 	*  The only path that intentionally KEEPS both the slot and the
@@ -264,20 +263,10 @@ const layerPortBroker = Layer.effect(PortBrokerService, Effect.gen(function* ()
 			reason: "no-free-port",
 			detail: `no free port found in [${windowStart}, ${windowStart + windowSize}) for owner '${owner}'`
 		}));
-	}).pipe(Effect.withSpan("substrate.portBroker.allocate", { attributes: {
-		owner: opts.owner ?? DEFAULT_OWNER,
-		preferredPort: opts.preferredPort ?? -1,
-		probeHost: opts.probeHost ?? "127.0.0.1",
-		windowStart: opts.windowHint?.start ?? DEFAULT_PORT_WINDOW.start,
-		windowSize: opts.windowHint?.size ?? DEFAULT_PORT_WINDOW.size
-	} }));
+	});
 	const finishAllocation = (port, owner, 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.owner": owner
-		});
 		yield* Effect.logDebug(`port-broker allocated ${port} (owner=${owner})`);
 		return {
 			port,
@@ -305,13 +294,7 @@ 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
-} }));
+}) : probeSinglePort(port, host);
 const probeSinglePort = (port, host) => Effect.callback((resume) => {
 	let settled = false;
 	let server = null;

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

@@ -1 +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 or publish a container port on the host yield this\n// service and call `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// Sequential search: callers may pass `preferredPort` (tried first) and\n// an optional `windowHint: { start, size }` (the scan window if\n// preferred is busy or absent). The default window —\n// `DEFAULT_PORT_WINDOW` below — is intentionally wide enough for any\n// realistic in-process devstack; plugins do NOT freelance per-kind\n// window starts. The substrate stays name-blind: there is no `PortKind`\n// literal; plugins are opaque port-holders from the broker's view.\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 { readFileSync, unlinkSync } from 'node:fs';\nimport {\n\tcreateServer as createNetServer,\n\ttype AddressInfo,\n\ttype Server as NetServer,\n} from 'node:net';\nimport { join } from 'node:path';\n\nimport { Context, Effect, Layer, Ref, Schema, Scope } from 'effect';\n\nimport { RosterHolderSchema, type RosterHolder } from '../../cross-process.ts';\nimport { atomicWriteFileExclusiveSync } from '../atomic-write.ts';\nimport { checkHolderLiveness, ownHolder } from '../cross-process/liveness.ts';\nimport { selfPid } from '../cross-process/self-pid.ts';\nimport { PortBrokerError } from '../errors.ts';\nimport { RuntimeRoot } from '../paths.ts';\nimport { decodeJsonTextSync } from '../runtime-decode.ts';\nimport { versionedDocSchema } from '../../versioned-doc-schema.ts';\n\n// ----------------------------------------------------------------------\n// Public shape\n// ----------------------------------------------------------------------\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/** Optional per-call window override. The broker scans\n *  `[start, start + size)` in order when `preferredPort` is busy or\n *  absent. Plugins with UX-pinned ports (e.g. a dev wallet whose\n *  legacy adapters auto-connect to a specific range) pass this so the\n *  fall-back range stays predictable; everyone else gets the default. */\nexport interface PortAllocationWindow {\n\treadonly start: number;\n\treadonly size?: number;\n}\n\n/** Default scan window. Sized for \"tens of plugins per stack\" with\n *  parallel-stack overhead headroom. 1000 ports is more than enough for\n *  any realistic in-process devstack; the forward-scan only ever\n *  reaches the end if EVERY port in the window is taken (effectively\n *  never on dev machines). Start chosen to land between common dev\n *  defaults (3000-5173, 8000-8080) and the ephemeral range so a\n *  sibling Vite/Next process doesn't accidentally collide on the\n *  first probe. */\nexport const DEFAULT_PORT_WINDOW: Required<PortAllocationWindow> = {\n\tstart: 39200,\n\tsize: 1000,\n};\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 window scan —\n\t *  preferred is a HINT for the kernel-collision case, but a HARD\n\t *  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. Docker\n\t *  `-p host:container` publishes on all interfaces, so Docker-backed\n\t *  callers pass `0.0.0.0`. */\n\treadonly probeHost?: PortProbeHost;\n\t/** Optional per-call window override; defaults to\n\t *  `DEFAULT_PORT_WINDOW`. */\n\treadonly windowHint?: PortAllocationWindow;\n\t/** Optional free-form owner label for diagnostics (`no-free-port`\n\t *  error detail). The broker treats this as opaque; pass something\n\t *  short and human-readable like `'wallet'` or `'sui:rpc'`. */\n\treadonly owner?: string;\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 release: Effect.Effect<void>;\n}\n\n/** Service shape — what plugins yield from Context. */\nexport interface PortBroker {\n\t/**\n\t * Allocate a port. The returned port is exclusive within THIS\n\t * process (the broker's `Ref` map) and best-effort-exclusive across\n\t * devstack processes that share a runtime root (port reservation\n\t * file), then verified against the kernel bind table 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 scan 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\nconst DEFAULT_OWNER = 'unknown';\n\n/** In-process holder for a port. Carries the owner string for\n *  diagnostics (e.g. surfaced in `no-free-port` errors). */\ninterface Holder {\n\treadonly owner: string;\n}\n\ntype State = ReadonlyMap<number, Holder>;\n\n// Reservation-doc shape. NOTE: this changed incompatibly from an\n// earlier `{ version: 1, kind, ... }` to `{ version: 1, owner, ... }`\n// without bumping the version. A version bump alone would NOT recover\n// a SIGKILL'd prior-version leftover (an old body still fails decode\n// under any new schema and would block its port forever). Instead the\n// recovery is behavioural: `acquirePortReservation` treats an EEXIST\n// file it cannot decode as a stale artifact and self-heals it\n// (best-effort unlink + retry), so a leftover incompatible reservation\n// clears itself on the next allocate of that port.\nconst PORT_RESERVATION_VERSION = 1 as const;\n\nconst PortReservationDocSchema = versionedDocSchema(PORT_RESERVATION_VERSION, {\n\tport: Schema.Number,\n\towner: Schema.String,\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\t// `atomicWriteFileExclusiveSync` writes a tempfile under O_EXCL +\n\t// fsync, then `linkSync`s it onto the final path. POSIX `link(2)`\n\t// is atomic AND fails with `EEXIST` if the target exists — that is\n\t// the exclusive-create primitive `rename` lacks (rename clobbers).\n\t// A sibling pid that wins the race becomes the canonical reservation\n\t// at `path`; we observe it via the EEXIST error and surface the\n\t// winner's doc to the caller (`acquirePortReservation`), which then\n\t// decides busy-vs-stale based on the holder's liveness.\n\ttry {\n\t\tatomicWriteFileExclusiveSync(path, `${JSON.stringify(doc)}\\n`, { 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') {\n\t\t\ttry {\n\t\t\t\treturn { _tag: 'exists', doc: parseReservationDoc(readFileSync(path, 'utf8')) };\n\t\t\t} catch {\n\t\t\t\t// The winning reservation file was removed between our\n\t\t\t\t// link-EEXIST and our read (a peer raced release). Retry.\n\t\t\t\treturn { _tag: 'race' };\n\t\t\t}\n\t\t}\n\t\treturn { _tag: 'failed', cause };\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\n/** Best-effort removal of an EXISTING reservation file whose body\n *  cannot be decoded (a leftover from an incompatible-version\n *  supervisor, or a torn write). Such a file carries no readable\n *  `ownerId`/`holder`, so neither `reclaimReservationIfOwnerSync` nor\n *  liveness can ever clear it; without this it would skip that one\n *  port for every future process for the supervisor's lifetime. We\n *  treat an undecodable body as a stale artifact and unlink it so the\n *  next exclusive-create can win. Returns whether the unlink ran\n *  (false if the file vanished first, i.e. a peer already cleared it)\n *  so the caller can bound its retry. */\nconst reclaimUndecodableReservationSync = (path: string): boolean => {\n\ttry {\n\t\tunlinkSync(path);\n\t\treturn true;\n\t} catch {\n\t\t// Already gone (peer reclaimed it) or unremovable; either way\n\t\t// the next loop turn re-evaluates via exclusive-create.\n\t\treturn false;\n\t}\n};\n\nconst acquirePortReservation = (\n\troot: string,\n\tport: number,\n\towner: string,\n): Effect.Effect<ReservationAttempt> =>\n\tEffect.gen(function* () {\n\t\tconst path = portReservationPath(root, port);\n\t\tconst ownerId = `${selfPid()}-${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\towner,\n\t\t\townerId,\n\t\t\tholder,\n\t\t};\n\n\t\t// Bounds the self-heal: an undecodable EEXIST body is reclaimed at\n\t\t// most once. If we see another undecodable body after that (a peer\n\t\t// keeps rewriting garbage), give up with `busy` rather than spin.\n\t\tlet reclaimedUndecodable = false;\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) {\n\t\t\t\t// EEXIST file we cannot decode (stale incompatible-version\n\t\t\t\t// leftover or torn write). Self-heal once: unlink it and retry\n\t\t\t\t// the exclusive-create so a live port is not lost permanently.\n\t\t\t\tif (!reclaimedUndecodable && reclaimUndecodableReservationSync(path)) {\n\t\t\t\t\treclaimedUndecodable = true;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\treturn { _tag: 'busy' } as const;\n\t\t\t}\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/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, 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, { 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\t/** Outcome of one candidate-port attempt.\n\t\t *\n\t\t *  `kept` means `finishAllocation` armed its scope finalizer; the\n\t\t *  in-process slot is now owned by that finalizer and we MUST\n\t\t *  NOT drop it on this critical region's exit. Any other outcome\n\t\t *  (busy / probe-in-use / probe-failed / reservation-failed)\n\t\t *  must release the slot before we hand control back to the\n\t\t *  caller. */\n\t\ttype SlotOutcome =\n\t\t\t| { readonly _tag: 'kept'; readonly allocated: AllocatedPort }\n\t\t\t| { readonly _tag: 'busy' }\n\t\t\t| {\n\t\t\t\t\treadonly _tag: 'reservation-failed';\n\t\t\t\t\treadonly detail: string;\n\t\t\t\t\treadonly cause: unknown;\n\t\t\t  }\n\t\t\t| { readonly _tag: 'probe-failed'; readonly cause: unknown };\n\n\t\t/** Reserve `port` in the in-process Map, run the probe+reservation\n\t\t *  chain through to either (a) `finishAllocation` arming its scope\n\t\t *  finalizer or (b) a clean release of BOTH the in-process slot\n\t\t *  AND the on-disk reservation file.\n\t\t *\n\t\t *  Interrupt safety: the critical region is wrapped in\n\t\t *  `Effect.acquireUseRelease`, whose `release` step is\n\t\t *  uninterruptible while its `use` step is NOT (Effect v4). The\n\t\t *  acquired `PortReservation` is created INSIDE `use` (after the\n\t\t *  on-disk file is written), so the `use` body stashes it in\n\t\t *  `reservationCell`; the uninterruptible `release` reads that cell\n\t\t *  and unlinks the reservation file on ANY non-`kept` exit —\n\t\t *  interrupt, typed failure, or a non-`kept` success outcome.\n\t\t *  Without this, an interrupt landing between the reservation write\n\t\t *  (in `acquirePortReservation`) and the finalizer arm (in\n\t\t *  `finishAllocation`) left the file on disk while the old release\n\t\t *  only dropped the in-process slot — leaking\n\t\t *  `port-locks/<port>.json`. Its `holder` is this still-alive\n\t\t *  process, so every future `allocate` of that port then saw\n\t\t *  `checkHolderLiveness` report `alive`, marking it busy for the\n\t\t *  whole supervisor lifetime.\n\t\t *\n\t\t *  The only path that intentionally KEEPS both the slot and the\n\t\t *  file is the `kept` outcome, where ownership transfers to the\n\t\t *  scope finalizer (see `finishAllocation`); `reservationCell` is\n\t\t *  cleared there so `release` is a no-op for it.\n\t\t *  (`unlinkReservationIfOwnerSync` is owner-id-guarded and\n\t\t *  idempotent, so a stray double-release is harmless — clearing\n\t\t *  the cell just avoids the redundant stat.)\n\t\t */\n\t\tconst attemptSlot = (\n\t\t\tport: number,\n\t\t\towner: string,\n\t\t\tprobeHost: PortProbeHost,\n\t\t): Effect.Effect<SlotOutcome | null, never, Scope.Scope> => {\n\t\t\t// Visible to BOTH the `use` body (fills it once the reservation\n\t\t\t// file exists) and the uninterruptible `release` callback\n\t\t\t// (unlinks it on any non-`kept` exit). On-disk analogue of the\n\t\t\t// in-process slot.\n\t\t\tlet reservationCell: PortReservation | null = null;\n\t\t\treturn Effect.acquireUseRelease(\n\t\t\t\ttryReserve(port, owner),\n\t\t\t\t(reserved): Effect.Effect<SlotOutcome | null, never, Scope.Scope> => {\n\t\t\t\t\tif (!reserved) return Effect.succeed(null);\n\t\t\t\t\treturn Effect.gen(function* () {\n\t\t\t\t\t\tconst reservation = yield* acquirePortReservation(reservationRoot, port, owner);\n\t\t\t\t\t\tif (reservation._tag === 'busy') return { _tag: 'busy' as const };\n\t\t\t\t\t\tif (reservation._tag === 'failed') {\n\t\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\t\t_tag: 'reservation-failed' as const,\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\t// File is now on disk. Hand it to the uninterruptible\n\t\t\t\t\t\t// `release` step so an interrupt at the `probePort` /\n\t\t\t\t\t\t// `finishAllocation` boundary cannot leak it.\n\t\t\t\t\t\treservationCell = reservation.reservation;\n\t\t\t\t\t\tconst ok = yield* probePort(port, probeHost);\n\t\t\t\t\t\tif (ok._tag === 'ok') {\n\t\t\t\t\t\t\tconst allocated = yield* finishAllocation(port, owner, drop, reservation.reservation);\n\t\t\t\t\t\t\t// Ownership transferred to the scope finalizer; the\n\t\t\t\t\t\t\t// `release` step must NOT also unlink the file.\n\t\t\t\t\t\t\treservationCell = null;\n\t\t\t\t\t\t\treturn { _tag: 'kept' as const, allocated };\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// Probe missed. The uninterruptible `release` step below\n\t\t\t\t\t\t// unlinks the reservation file (via `reservationCell`) and\n\t\t\t\t\t\t// drops the in-process slot, so a single owner cleans up\n\t\t\t\t\t\t// both even if an interrupt preempts us right here.\n\t\t\t\t\t\tif (ok._tag === 'probe-failed') {\n\t\t\t\t\t\t\treturn { _tag: 'probe-failed' as const, cause: ok.cause };\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn { _tag: 'busy' as const };\n\t\t\t\t\t});\n\t\t\t\t},\n\t\t\t\t(reserved, exit) => {\n\t\t\t\t\t// Slot + reservation release (uninterruptible). Drop the\n\t\t\t\t\t// in-process entry AND unlink the on-disk reservation\n\t\t\t\t\t// UNLESS we transferred ownership to a scope finalizer\n\t\t\t\t\t// (the `kept` outcome, which cleared `reservationCell`).\n\t\t\t\t\t// Interrupts, typed failures, and non-`kept` success\n\t\t\t\t\t// outcomes all flow through here, closing both the Map\n\t\t\t\t\t// leak and the port-locks/*.json leak (the latter\n\t\t\t\t\t// previously persisted until the supervisor exited).\n\t\t\t\t\tif (!reserved) return Effect.void;\n\t\t\t\t\tconst kept = exit._tag === 'Success' && exit.value?._tag === 'kept';\n\t\t\t\t\tif (kept) return Effect.void;\n\t\t\t\t\tconst releaseReservation =\n\t\t\t\t\t\treservationCell !== null ? reservationCell.release : Effect.void;\n\t\t\t\t\treturn Effect.all([drop(port), releaseReservation], { discard: true });\n\t\t\t\t},\n\t\t\t);\n\t\t};\n\n\t\tconst allocate: PortBroker['allocate'] = (opts = {}) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst owner = opts.owner ?? DEFAULT_OWNER;\n\t\t\t\tconst probeHost = opts.probeHost ?? '127.0.0.1';\n\t\t\t\tconst windowStart = opts.windowHint?.start ?? DEFAULT_PORT_WINDOW.start;\n\t\t\t\tconst windowSize = opts.windowHint?.size ?? DEFAULT_PORT_WINDOW.size;\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 outcome = yield* attemptSlot(opts.preferredPort, owner, probeHost);\n\t\t\t\t\tif (outcome === null) {\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} (owner=${owner}) 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\tif (outcome._tag === 'kept') return outcome.allocated;\n\t\t\t\t\tif (outcome._tag === 'reservation-failed') {\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: outcome.detail,\n\t\t\t\t\t\t\t\tcause: outcome.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\tif (outcome._tag === 'probe-failed') {\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 preferred port ${opts.preferredPort} ` +\n\t\t\t\t\t\t\t\t\t`(owner=${owner}, host=${probeHost}) failed with non-EADDRINUSE error`,\n\t\t\t\t\t\t\t\tcause: outcome.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// `busy` (either cross-process reservation held by a\n\t\t\t\t\t// live peer OR kernel-level in-use) — fall through to\n\t\t\t\t\t// the window scan; the caller's preferred was a HINT.\n\t\t\t\t}\n\n\t\t\t\t// 2. Forward-scan the window.\n\t\t\t\tfor (let p = windowStart; p < windowStart + windowSize; p++) {\n\t\t\t\t\tconst outcome = yield* attemptSlot(p, owner, probeHost);\n\t\t\t\t\tif (outcome === null) continue;\n\t\t\t\t\tif (outcome._tag === 'kept') return outcome.allocated;\n\t\t\t\t\tif (outcome._tag === 'reservation-failed') {\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: outcome.detail,\n\t\t\t\t\t\t\t\tcause: outcome.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\tif (outcome._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 scan. 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} (owner=${owner}, 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: outcome.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// `busy` — 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 [${windowStart}, ` +\n\t\t\t\t\t\t\t`${windowStart + windowSize}) for owner '${owner}'`,\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\towner: opts.owner ?? DEFAULT_OWNER,\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\twindowStart: opts.windowHint?.start ?? DEFAULT_PORT_WINDOW.start,\n\t\t\t\t\t\twindowSize: opts.windowHint?.size ?? DEFAULT_PORT_WINDOW.size,\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\towner: string,\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.owner': owner,\n\t\t\t\t});\n\t\t\t\tyield* Effect.logDebug(`port-broker allocated ${port} (owner=${owner})`);\n\t\t\t\treturn {\n\t\t\t\t\tport,\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 most servers bind\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 default window starts\n\t\t\t\t\t// at 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\t// Interrupt mid-`listen()` must close the transient server so the\n\t\t// probed port isn't held open by an orphaned handle.\n\t\treturn Effect.sync(() => {\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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"}
+{"version":3,"file":"service.mjs","names":["createNetServer"],"sources":["../../../../src/substrate/runtime/port-broker/service.ts"],"sourcesContent":["// Port broker — substrate-level service.\n//\n// Resource broker for host ports. Plugins that need to bind a host HTTP server\n// or publish a container port on the host 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// Sequential search: callers may pass `preferredPort` (tried first) and\n// an optional `windowHint: { start, size }` (the scan window if\n// preferred is busy or absent). The default window —\n// `DEFAULT_PORT_WINDOW` below — is intentionally wide enough for any\n// realistic in-process devstack; plugins do NOT freelance per-kind\n// window starts. The substrate stays name-blind: there is no `PortKind`\n// literal; plugins are opaque port-holders from the broker's view.\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 { readFileSync, unlinkSync } from 'node:fs';\nimport {\n\tcreateServer as createNetServer,\n\ttype AddressInfo,\n\ttype Server as NetServer,\n} from 'node:net';\nimport { join } from 'node:path';\n\nimport { Context, Effect, Layer, Ref, Schema, Scope } from 'effect';\n\nimport { RosterHolderSchema, type RosterHolder } from '../../cross-process.ts';\nimport { atomicWriteFileExclusiveSync } from '../atomic-write.ts';\nimport { checkHolderLiveness, ownHolder } from '../cross-process/liveness.ts';\nimport { selfPid } from '../cross-process/self-pid.ts';\nimport { PortBrokerError } from '../errors.ts';\nimport { RuntimeRoot } from '../paths.ts';\nimport { decodeJsonTextSync } from '../runtime-decode.ts';\nimport { versionedDocSchema } from '../../versioned-doc-schema.ts';\n\n// ----------------------------------------------------------------------\n// Public shape\n// ----------------------------------------------------------------------\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/** Optional per-call window override. The broker scans\n *  `[start, start + size)` in order when `preferredPort` is busy or\n *  absent. Plugins with UX-pinned ports (e.g. a dev wallet whose\n *  legacy adapters auto-connect to a specific range) pass this so the\n *  fall-back range stays predictable; everyone else gets the default. */\nexport interface PortAllocationWindow {\n\treadonly start: number;\n\treadonly size?: number;\n}\n\n/** Default scan window. Sized for \"tens of plugins per stack\" with\n *  parallel-stack overhead headroom. 1000 ports is more than enough for\n *  any realistic in-process devstack; the forward-scan only ever\n *  reaches the end if EVERY port in the window is taken (effectively\n *  never on dev machines). Start chosen to land between common dev\n *  defaults (3000-5173, 8000-8080) and the ephemeral range so a\n *  sibling Vite/Next process doesn't accidentally collide on the\n *  first probe. */\nexport const DEFAULT_PORT_WINDOW: Required<PortAllocationWindow> = {\n\tstart: 39200,\n\tsize: 1000,\n};\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 window scan —\n\t *  preferred is a HINT for the kernel-collision case, but a HARD\n\t *  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. Docker\n\t *  `-p host:container` publishes on all interfaces, so Docker-backed\n\t *  callers pass `0.0.0.0`. */\n\treadonly probeHost?: PortProbeHost;\n\t/** Optional per-call window override; defaults to\n\t *  `DEFAULT_PORT_WINDOW`. */\n\treadonly windowHint?: PortAllocationWindow;\n\t/** Optional free-form owner label for diagnostics (`no-free-port`\n\t *  error detail). The broker treats this as opaque; pass something\n\t *  short and human-readable like `'wallet'` or `'sui:rpc'`. */\n\treadonly owner?: string;\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 release: Effect.Effect<void>;\n}\n\n/** Service shape — what plugins yield from Context. */\nexport interface PortBroker {\n\t/**\n\t * Allocate a port. The returned port is exclusive within THIS\n\t * process (the broker's `Ref` map) and best-effort-exclusive across\n\t * devstack processes that share a runtime root (port reservation\n\t * file), then verified against the kernel bind table 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 scan 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\nconst DEFAULT_OWNER = 'unknown';\n\n/** In-process holder for a port. Carries the owner string for\n *  diagnostics (e.g. surfaced in `no-free-port` errors). */\ninterface Holder {\n\treadonly owner: string;\n}\n\ntype State = ReadonlyMap<number, Holder>;\n\n// Reservation-doc shape. Decode failures are treated as stale artifacts:\n// `acquirePortReservation` self-heals them with a best-effort unlink +\n// retry so one corrupt reservation file cannot block a port forever.\nconst PORT_RESERVATION_VERSION = 1 as const;\n\nconst PortReservationDocSchema = versionedDocSchema(PORT_RESERVATION_VERSION, {\n\tport: Schema.Number,\n\towner: Schema.String,\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\t// `atomicWriteFileExclusiveSync` writes a tempfile under O_EXCL +\n\t// fsync, then `linkSync`s it onto the final path. POSIX `link(2)`\n\t// is atomic AND fails with `EEXIST` if the target exists — that is\n\t// the exclusive-create primitive `rename` lacks (rename clobbers).\n\t// A sibling pid that wins the race becomes the canonical reservation\n\t// at `path`; we observe it via the EEXIST error and surface the\n\t// winner's doc to the caller (`acquirePortReservation`), which then\n\t// decides busy-vs-stale based on the holder's liveness.\n\ttry {\n\t\tatomicWriteFileExclusiveSync(path, `${JSON.stringify(doc)}\\n`, { 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') {\n\t\t\ttry {\n\t\t\t\treturn { _tag: 'exists', doc: parseReservationDoc(readFileSync(path, 'utf8')) };\n\t\t\t} catch {\n\t\t\t\t// The winning reservation file was removed between our\n\t\t\t\t// link-EEXIST and our read (a peer raced release). Retry.\n\t\t\t\treturn { _tag: 'race' };\n\t\t\t}\n\t\t}\n\t\treturn { _tag: 'failed', cause };\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\n/** Best-effort removal of an EXISTING reservation file whose body\n *  cannot be decoded (a leftover from an incompatible-version\n *  supervisor, or a torn write). Such a file carries no readable\n *  `ownerId`/`holder`, so neither `reclaimReservationIfOwnerSync` nor\n *  liveness can ever clear it; without this it would skip that one\n *  port for every future process for the supervisor's lifetime. We\n *  treat an undecodable body as a stale artifact and unlink it so the\n *  next exclusive-create can win. Returns whether the unlink ran\n *  (false if the file vanished first, i.e. a peer already cleared it)\n *  so the caller can bound its retry. */\nconst reclaimUndecodableReservationSync = (path: string): boolean => {\n\ttry {\n\t\tunlinkSync(path);\n\t\treturn true;\n\t} catch {\n\t\t// Already gone (peer reclaimed it) or unremovable; either way\n\t\t// the next loop turn re-evaluates via exclusive-create.\n\t\treturn false;\n\t}\n};\n\nconst acquirePortReservation = (\n\troot: string,\n\tport: number,\n\towner: string,\n): Effect.Effect<ReservationAttempt> =>\n\tEffect.gen(function* () {\n\t\tconst path = portReservationPath(root, port);\n\t\tconst ownerId = `${selfPid()}-${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\towner,\n\t\t\townerId,\n\t\t\tholder,\n\t\t};\n\n\t\t// Bounds the self-heal: an undecodable EEXIST body is reclaimed at\n\t\t// most once. If we see another undecodable body after that (a peer\n\t\t// keeps rewriting garbage), give up with `busy` rather than spin.\n\t\tlet reclaimedUndecodable = false;\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) {\n\t\t\t\t// EEXIST file we cannot decode (stale incompatible-version\n\t\t\t\t// leftover or torn write). Self-heal once: unlink it and retry\n\t\t\t\t// the exclusive-create so a live port is not lost permanently.\n\t\t\t\tif (!reclaimedUndecodable && reclaimUndecodableReservationSync(path)) {\n\t\t\t\t\treclaimedUndecodable = true;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\treturn { _tag: 'busy' } as const;\n\t\t\t}\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/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, 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, { 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\t/** Outcome of one candidate-port attempt.\n\t\t *\n\t\t *  `kept` means `finishAllocation` armed its scope finalizer; the\n\t\t *  in-process slot is now owned by that finalizer and we MUST\n\t\t *  NOT drop it on this critical region's exit. Any other outcome\n\t\t *  (busy / probe-in-use / probe-failed / reservation-failed)\n\t\t *  must release the slot before we hand control back to the\n\t\t *  caller. */\n\t\ttype SlotOutcome =\n\t\t\t| { readonly _tag: 'kept'; readonly allocated: AllocatedPort }\n\t\t\t| { readonly _tag: 'busy' }\n\t\t\t| {\n\t\t\t\t\treadonly _tag: 'reservation-failed';\n\t\t\t\t\treadonly detail: string;\n\t\t\t\t\treadonly cause: unknown;\n\t\t\t  }\n\t\t\t| { readonly _tag: 'probe-failed'; readonly cause: unknown };\n\n\t\t/** Reserve `port` in the in-process Map, run the probe+reservation\n\t\t *  chain through to either (a) `finishAllocation` arming its scope\n\t\t *  finalizer or (b) a clean release of BOTH the in-process slot\n\t\t *  AND the on-disk reservation file.\n\t\t *\n\t\t *  Interrupt safety: the critical region is wrapped in\n\t\t *  `Effect.acquireUseRelease`, whose `release` step is\n\t\t *  uninterruptible while its `use` step is NOT (Effect v4). The\n\t\t *  acquired `PortReservation` is created INSIDE `use` (after the\n\t\t *  on-disk file is written), so the `use` body stashes it in\n\t\t *  `reservationCell`; the uninterruptible `release` reads that cell\n\t\t *  and unlinks the reservation file on ANY non-`kept` exit —\n\t\t *  interrupt, typed failure, or a non-`kept` success outcome.\n\t\t *  Without this, an interrupt landing between the reservation write\n\t\t *  (in `acquirePortReservation`) and the finalizer arm (in\n\t\t *  `finishAllocation`) would leave `port-locks/<port>.json` on disk\n\t\t *  while only dropping the in-process slot. Its `holder` is this\n\t\t *  still-alive process, so every future `allocate` of that port then\n\t\t *  sees `checkHolderLiveness` report `alive`, marking it busy for the\n\t\t *  whole supervisor lifetime.\n\t\t *\n\t\t *  The only path that intentionally KEEPS both the slot and the\n\t\t *  file is the `kept` outcome, where ownership transfers to the\n\t\t *  scope finalizer (see `finishAllocation`); `reservationCell` is\n\t\t *  cleared there so `release` is a no-op for it.\n\t\t *  (`unlinkReservationIfOwnerSync` is owner-id-guarded and\n\t\t *  idempotent, so a stray double-release is harmless — clearing\n\t\t *  the cell just avoids the redundant stat.)\n\t\t */\n\t\tconst attemptSlot = (\n\t\t\tport: number,\n\t\t\towner: string,\n\t\t\tprobeHost: PortProbeHost,\n\t\t): Effect.Effect<SlotOutcome | null, never, Scope.Scope> => {\n\t\t\t// Visible to BOTH the `use` body (fills it once the reservation\n\t\t\t// file exists) and the uninterruptible `release` callback\n\t\t\t// (unlinks it on any non-`kept` exit). On-disk analogue of the\n\t\t\t// in-process slot.\n\t\t\tlet reservationCell: PortReservation | null = null;\n\t\t\treturn Effect.acquireUseRelease(\n\t\t\t\ttryReserve(port, owner),\n\t\t\t\t(reserved): Effect.Effect<SlotOutcome | null, never, Scope.Scope> => {\n\t\t\t\t\tif (!reserved) return Effect.succeed(null);\n\t\t\t\t\treturn Effect.gen(function* () {\n\t\t\t\t\t\tconst reservation = yield* acquirePortReservation(reservationRoot, port, owner);\n\t\t\t\t\t\tif (reservation._tag === 'busy') return { _tag: 'busy' as const };\n\t\t\t\t\t\tif (reservation._tag === 'failed') {\n\t\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\t\t_tag: 'reservation-failed' as const,\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\t// File is now on disk. Hand it to the uninterruptible\n\t\t\t\t\t\t// `release` step so an interrupt at the `probePort` /\n\t\t\t\t\t\t// `finishAllocation` boundary cannot leak it.\n\t\t\t\t\t\treservationCell = reservation.reservation;\n\t\t\t\t\t\tconst ok = yield* probePort(port, probeHost);\n\t\t\t\t\t\tif (ok._tag === 'ok') {\n\t\t\t\t\t\t\tconst allocated = yield* finishAllocation(port, owner, drop, reservation.reservation);\n\t\t\t\t\t\t\t// Ownership transferred to the scope finalizer; the\n\t\t\t\t\t\t\t// `release` step must NOT also unlink the file.\n\t\t\t\t\t\t\treservationCell = null;\n\t\t\t\t\t\t\treturn { _tag: 'kept' as const, allocated };\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// Probe missed. The uninterruptible `release` step below\n\t\t\t\t\t\t// unlinks the reservation file (via `reservationCell`) and\n\t\t\t\t\t\t// drops the in-process slot, so a single owner cleans up\n\t\t\t\t\t\t// both even if an interrupt preempts us right here.\n\t\t\t\t\t\tif (ok._tag === 'probe-failed') {\n\t\t\t\t\t\t\treturn { _tag: 'probe-failed' as const, cause: ok.cause };\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn { _tag: 'busy' as const };\n\t\t\t\t\t});\n\t\t\t\t},\n\t\t\t\t(reserved, exit) => {\n\t\t\t\t\t// Slot + reservation release (uninterruptible). Drop the\n\t\t\t\t\t// in-process entry AND unlink the on-disk reservation\n\t\t\t\t\t// UNLESS we transferred ownership to a scope finalizer\n\t\t\t\t\t// (the `kept` outcome, which cleared `reservationCell`).\n\t\t\t\t\t// Interrupts, typed failures, and non-`kept` success\n\t\t\t\t\t// outcomes all flow through here, closing both the Map\n\t\t\t\t\t// leak and the port-locks/*.json leak (the on-disk\n\t\t\t\t\t// reservation is unlinked here rather than persisting\n\t\t\t\t\t// until the supervisor exits).\n\t\t\t\t\tif (!reserved) return Effect.void;\n\t\t\t\t\tconst kept = exit._tag === 'Success' && exit.value?._tag === 'kept';\n\t\t\t\t\tif (kept) return Effect.void;\n\t\t\t\t\tconst releaseReservation =\n\t\t\t\t\t\treservationCell !== null ? reservationCell.release : Effect.void;\n\t\t\t\t\treturn Effect.all([drop(port), releaseReservation], { discard: true });\n\t\t\t\t},\n\t\t\t);\n\t\t};\n\n\t\tconst allocate: PortBroker['allocate'] = (opts = {}) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst owner = opts.owner ?? DEFAULT_OWNER;\n\t\t\t\tconst probeHost = opts.probeHost ?? '127.0.0.1';\n\t\t\t\tconst windowStart = opts.windowHint?.start ?? DEFAULT_PORT_WINDOW.start;\n\t\t\t\tconst windowSize = opts.windowHint?.size ?? DEFAULT_PORT_WINDOW.size;\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 outcome = yield* attemptSlot(opts.preferredPort, owner, probeHost);\n\t\t\t\t\tif (outcome === null) {\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} (owner=${owner}) 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\tif (outcome._tag === 'kept') return outcome.allocated;\n\t\t\t\t\tif (outcome._tag === 'reservation-failed') {\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: outcome.detail,\n\t\t\t\t\t\t\t\tcause: outcome.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\tif (outcome._tag === 'probe-failed') {\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 preferred port ${opts.preferredPort} ` +\n\t\t\t\t\t\t\t\t\t`(owner=${owner}, host=${probeHost}) failed with non-EADDRINUSE error`,\n\t\t\t\t\t\t\t\tcause: outcome.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// `busy` (either cross-process reservation held by a\n\t\t\t\t\t// live peer OR kernel-level in-use) — fall through to\n\t\t\t\t\t// the window scan; the caller's preferred was a HINT.\n\t\t\t\t}\n\n\t\t\t\t// 2. Forward-scan the window.\n\t\t\t\tfor (let p = windowStart; p < windowStart + windowSize; p++) {\n\t\t\t\t\tconst outcome = yield* attemptSlot(p, owner, probeHost);\n\t\t\t\t\tif (outcome === null) continue;\n\t\t\t\t\tif (outcome._tag === 'kept') return outcome.allocated;\n\t\t\t\t\tif (outcome._tag === 'reservation-failed') {\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: outcome.detail,\n\t\t\t\t\t\t\t\tcause: outcome.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\tif (outcome._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 scan. 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} (owner=${owner}, 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: outcome.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// `busy` — 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 [${windowStart}, ` +\n\t\t\t\t\t\t\t`${windowStart + windowSize}) for owner '${owner}'`,\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\towner: string,\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.logDebug(`port-broker allocated ${port} (owner=${owner})`);\n\t\t\t\treturn {\n\t\t\t\t\tport,\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 most servers bind\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})\n\t\t: probeSinglePort(port, host);\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 default window starts\n\t\t\t\t\t// at 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\t// Interrupt mid-`listen()` must close the transient server so the\n\t\t// probed port isn't held open by an orphaned handle.\n\t\treturn Effect.sync(() => {\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.mjs.map

@@ -1 +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/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,uCAAuC,CAAC;AAO5C,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"}
+{"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/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,uBAAuB,CAAC,CAIjF,CAAC;AAOJ,IAAa,0BAAb,cAA6C,QAAQ,QAGnD,CAAC,CAAC,sCAAsC,CAAC,CAAC,CAAC;AAO7C,MAAa,wBAA8D,MAAM,OAChF,yBACA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,OAAO,IAAI,KAA+C,CAAC,CAAC;CAE7E,MAAM,YAAY,SACjB,OAAO,IAAI,aAAa;EACvB,MAAM,QAAQ,OAAO,OAAO;EAC5B,MAAM,KAAK,OAAO,KAAK,KAAK;EAC5B,MAAM,aAAwC;GAAE,GAAG;GAAM;GAAI;EAAM;EACnE,OAAO,IAAI,OAAO,WAAW,UAAU,CAAC,GAAG,OAAO,UAAU,CAAC;EAC7D,OAAO,OAAO,mBACb,IAAI,OAAO,WAAW,UAAU,MAAM,QAAQ,cAAc,UAAU,OAAO,EAAE,CAAC,CACjF;CACD,CAAC;CAEF,MAAM,SAA4D,OAAO,IAAI,aAAa;EACzF,MAAM,QAAQ,OAAO,IAAI,IAAI,QAAQ;EACrC,KAAK,MAAM,QAAQ,OAClB,OAAO,MAAM,QAAQ,KAAK,KAAK,KAAK,KAAK,CAAC,CAAC,KAC1C,OAAO,UACL,UACA,IAAI,sBAAsB;GACzB,WAAW,KAAK;GAChB,OAAO,KAAK;GACZ;EACD,CAAC,CACH,CACD;CAEF,CAAC;CAED,OAAO,wBAAwB,GAAG;EAAE;EAAU;CAAO,CAAC;AACvD,CAAC,CACF"}

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

@@ -1,5 +1,4 @@
 import { Effect, Types } from "effect";
-import * as _$effect_Cause0 from "effect/Cause";
 
 //#region src/substrate/runtime/probes.d.ts
 declare namespace probes_d_exports {
@@ -17,7 +16,7 @@ interface ProbeOptions<E = unknown, R = never> {
   readonly probe: () => Effect.Effect<ProbeAttemptResult, E, R>;
   readonly isRetryableError?: (error: E) => boolean;
 }
-declare const ProbeAttemptTimeoutError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+declare const ProbeAttemptTimeoutError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "ProbeAttemptTimeoutError";
 } & Readonly<A>;
 declare class ProbeAttemptTimeoutError extends ProbeAttemptTimeoutError_base<{
@@ -25,7 +24,7 @@ declare class ProbeAttemptTimeoutError extends ProbeAttemptTimeoutError_base<{
   readonly attemptTimeoutMs: number;
   readonly message: string;
 }> {}
-declare const ProbeTimeoutError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+declare const ProbeTimeoutError_base: new <A extends Record<string, any> = {}>(args: Types.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
   readonly _tag: "ProbeTimeoutError";
 } & Readonly<A>;
 declare class ProbeTimeoutError extends ProbeTimeoutError_base<{

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

@@ -1 +1 @@
-{"version":3,"file":"probes.mjs","names":[],"sources":["../../../src/substrate/runtime/probes.ts"],"sourcesContent":["import { Data, Duration, Effect, Types } 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\n// ---------------------------------------------------------------------------\n// probeManyLenient — run a set of lenient `T | null` probes and surface\n// each probe's verdict so the caller can fold the array however it likes.\n// ---------------------------------------------------------------------------\n//\n// Lenient probes (per `ChainProbe`'s `'lenient'` contract) return `T | null`\n// where `null` is a non-authoritative \"not yet\" signal. Several plugins\n// (walrus deploy, deepbook deploy, pyth init) hand-roll a sequential loop\n// that early-returns `null` on the first non-ready probe. This helper\n// centralizes the iteration so the call sites collapse to a `.every()`\n// or `.find()` against the returned array.\n//\n// Concurrency defaults to `'unbounded'`. Callers that need sequential\n// short-circuit semantics (e.g. RPC backoff politeness) can pass\n// `concurrency: 1`. The return shape is the full array even when concurrency\n// is 1 — callers that want \"any null aborts and returns null\" should fold\n// with `.every((x) => x !== null) ? array : null` themselves.\n\nexport const probeManyLenient = <T, E, R>(\n\tprobes: ReadonlyArray<Effect.Effect<T | null, E, R>>,\n\toptions?: { readonly concurrency?: Types.Concurrency },\n): Effect.Effect<ReadonlyArray<T | null>, E, R> =>\n\tEffect.forEach(probes, (probe) => probe, {\n\t\tconcurrency: options?.concurrency ?? 'unbounded',\n\t});\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;;AAqBF,MAAa,oBACZ,QACA,YAEA,OAAO,QAAQ,SAAS,UAAU,OAAO,EACxC,aAAa,SAAS,eAAe,aACrC,CAAC"}
+{"version":3,"file":"probes.mjs","names":[],"sources":["../../../src/substrate/runtime/probes.ts"],"sourcesContent":["import { Data, Duration, Effect, Types } 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\n// ---------------------------------------------------------------------------\n// probeManyLenient — run a set of lenient `T | null` probes and surface\n// each probe's verdict so the caller can fold the array however it likes.\n// ---------------------------------------------------------------------------\n//\n// Lenient probes (per `ChainProbe`'s `'lenient'` contract) return `T | null`\n// where `null` is a non-authoritative \"not yet\" signal. Several plugins\n// (walrus deploy, deepbook deploy, pyth init) hand-roll a sequential loop\n// that early-returns `null` on the first non-ready probe. This helper\n// centralizes the iteration so the call sites collapse to a `.every()`\n// or `.find()` against the returned array.\n//\n// Concurrency defaults to `'unbounded'`. Callers that need sequential\n// short-circuit semantics (e.g. RPC backoff politeness) can pass\n// `concurrency: 1`. The return shape is the full array even when concurrency\n// is 1 — callers that want \"any null aborts and returns null\" should fold\n// with `.every((x) => x !== null) ? array : null` themselves.\n\nexport const probeManyLenient = <T, E, R>(\n\tprobes: ReadonlyArray<Effect.Effect<T | null, E, R>>,\n\toptions?: { readonly concurrency?: Types.Concurrency },\n): Effect.Effect<ReadonlyArray<T | null>, E, R> =>\n\tEffect.forEach(probes, (probe) => probe, {\n\t\tconcurrency: options?.concurrency ?? 'unbounded',\n\t});\n"],"mappings":";;;;;;;;;;AAmBA,IAAa,2BAAb,cAA8C,KAAK,YAAY,0BAA0B,CAAC,CAIvF,CAAC;AAEJ,IAAa,oBAAb,cAAuC,KAAK,YAAY,mBAAmB,CAAC,CASzE,CAAC;AAEJ,MAAM,sBAAsB;AAE5B,MAAM,oBACL,WAC4D;CAC5D,IAAI,WAAW,KAAA,KAAa,WAAW,MAAM,OAAO,EAAE,OAAO,KAAK;CAClE,IAAI,WAAW,OAAO,OAAO,EAAE,OAAO,MAAM;CAC5C,OAAO;AACR;AAEA,MAAM,sBACL,QACA,YAKuD;CACvD,IAAI,QAAQ,qBAAqB,KAAA,GAAW,OAAO;CACnD,MAAM,YAAY,KAAK,IAAI,GAAG,KAAK,IAAI,QAAQ,kBAAkB,QAAQ,WAAW,CAAC;CACrF,OAAO,OAAO,KACb,OAAO,cAAc;EACpB,UAAU,SAAS,OAAO,SAAS;EACnC,cACC,OAAO,KACN,IAAI,yBAAyB;GAC5B,OAAO,QAAQ;GACf,kBAAkB;GAClB,SAAS,SAAS,QAAQ,MAAM,mCAAmC,UAAU;EAC9E,CAAC,CACF;CACF,CAAC,CACF;AACD;AAEA,MAAa,gBACZ,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,YAAY,QAAQ;CAC1B,MAAM,aAAa,QAAQ,cAAc;CAEzC,MAAM,WADU,KAAK,IACE,IAAI;CAC3B,IAAI,WAAW;CACf,IAAI;CACJ,IAAI;CAEJ,SAAS;EACR,MAAM,cAAc,WAAW,KAAK,IAAI;EACxC,IAAI,eAAe,GAClB,OAAO,OAAO,OAAO,KACpB,IAAI,kBAAkB;GACrB,OAAO,QAAQ;GACf;GACA;GACA,GAAI,QAAQ,qBAAqB,KAAA,IAC9B,CAAC,IACD,EAAE,kBAAkB,QAAQ,iBAAiB;GAChD;GACA,SAAS,SAAS,QAAQ,MAAM,+BAA+B,UAAU;GACzE,GAAI,cAAc,KAAA,IAAY,CAAC,IAAI,EAAE,UAAU;GAC/C,GAAI,iBAAiB,KAAA,IAAY,CAAC,IAAI,EAAE,aAAa;EACtD,CAAC,CACF;EAGD,YAAY;EAwBZ,IAAI,OAvBiB,mBAAmB,QAAQ,MAAM,GAAG;GACxD,OAAO,QAAQ;GACf,kBAAkB,QAAQ;GAC1B;EACD,CAAC,CAAC,CAAC,KACF,OAAO,YAAY;GAClB,YAAY,UAAU;IACrB,IACC,EAAE,iBAAiB,6BACnB,QAAQ,mBAAmB,KAAU,MAAM,OAE3C,OAAO,OAAO,KAAK,KAAU;IAE9B,YAAY;IACZ,OAAO,OAAO,QAAQ,KAAK;GAC5B;GACA,YAAY,WAAW;IACtB,MAAM,aAAa,iBAAiB,MAAM;IAC1C,IAAI,CAAC,WAAW,OAAO,eAAe,WAAW,UAAU;IAC3D,OAAO,OAAO,QAAQ,WAAW,KAAK;GACvC;EACD,CAAC,CACF,GACW;EAEX,MAAM,UAAU,KAAK,IAAI,YAAY,KAAK,IAAI,GAAG,WAAW,KAAK,IAAI,CAAC,CAAC;EACvE,OAAO,OAAO,MAAM,SAAS,OAAO,OAAO,CAAC;CAC7C;AACD,CAAC;AAQF,MAAa,uBAAuB,WAAoD;CACvF,IAAI,OAAO,aAAa,GAAG,OAAO;CAClC,OAAO;EACN,OAAO;EACP,QAAQ;GACP,UAAU,OAAO;GACjB,GAAI,OAAO,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,OAAO,OAAO;GAC/D,GAAI,OAAO,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,OAAO,OAAO;EAChE;CACD;AACD;AAoBA,MAAa,oBACZ,QACA,YAEA,OAAO,QAAQ,SAAS,UAAU,OAAO,EACxC,aAAa,SAAS,eAAe,YACtC,CAAC"}

package/dist/substrate/runtime/process-supervisor.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"process-supervisor.mjs","names":[],"sources":["../../../src/substrate/runtime/process-supervisor.ts"],"sourcesContent":["import { spawn } from 'node:child_process';\nimport type { Readable } from 'node:stream';\n\nimport { Effect } from 'effect';\n\nexport interface ManagedProcessExitStatus {\n\treadonly code: number | null;\n\treadonly signal: NodeJS.Signals | null;\n}\n\nexport interface ManagedProcessChild {\n\treadonly pid?: number;\n\treadonly stdout?: Readable | null;\n\treadonly stderr?: Readable | null;\n\treadonly exitCode?: number | null;\n\treadonly signalCode?: NodeJS.Signals | null;\n\tkill(signal?: NodeJS.Signals): boolean;\n\ton(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;\n\ton(event: 'error', listener: (cause: Error) => void): this;\n\tonce(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;\n\tonce(event: 'error', listener: (cause: Error) => void): this;\n\toff(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;\n\toff(event: 'error', listener: (cause: Error) => void): this;\n}\n\nexport interface ManagedProcessSpawnOptions {\n\treadonly cwd: string;\n\treadonly env: NodeJS.ProcessEnv;\n\treadonly stdio: 'pipe';\n\treadonly detached?: boolean;\n}\n\nexport type ManagedProcessSpawner = (\n\tcommand: string,\n\targs: ReadonlyArray<string>,\n\toptions: ManagedProcessSpawnOptions,\n) => ManagedProcessChild;\n\nexport const nodeProcessSpawner: ManagedProcessSpawner = (command, args, options) =>\n\tspawn(command, [...args], {\n\t\tcwd: options.cwd,\n\t\tenv: options.env,\n\t\tstdio: options.stdio,\n\t\tdetached: options.detached,\n\t}) as ManagedProcessChild;\n\nexport const describeProcessExitStatus = (status: ManagedProcessExitStatus): string => {\n\tif (status.code !== null) return `exit code ${status.code}`;\n\tif (status.signal !== null) return `signal ${status.signal}`;\n\treturn 'unknown exit status';\n};\n\nexport const onceProcessExit = (child: ManagedProcessChild): Promise<ManagedProcessExitStatus> =>\n\tnew Promise((resolveExit) => {\n\t\tchild.once('exit', (code, signal) => resolveExit({ code, signal }));\n\t});\n\nexport const getProcessExitStatus = (\n\tchild: ManagedProcessChild,\n): ManagedProcessExitStatus | null => {\n\tif (child.exitCode !== undefined && child.exitCode !== null) {\n\t\treturn { code: child.exitCode, signal: null };\n\t}\n\tif (child.signalCode !== undefined && child.signalCode !== null) {\n\t\treturn { code: null, signal: child.signalCode };\n\t}\n\treturn null;\n};\n\nexport const awaitProcessExit = (child: ManagedProcessChild): Promise<ManagedProcessExitStatus> =>\n\tPromise.resolve(getProcessExitStatus(child) ?? onceProcessExit(child));\n\nexport const onceProcessError = (child: ManagedProcessChild): Promise<unknown> =>\n\tnew Promise((resolveError) => {\n\t\tchild.once('error', (cause) => resolveError(cause));\n\t});\n\nexport const waitForProcessExitOrTimeout = (\n\tchild: ManagedProcessChild,\n\ttimeoutMs: number,\n): Promise<ManagedProcessExitStatus | null> =>\n\tPromise.race([\n\t\tonceProcessExit(child),\n\t\tnew Promise<null>((resolveTimeout) => setTimeout(() => resolveTimeout(null), timeoutMs)),\n\t]);\n\nexport interface TerminateManagedProcessOptions {\n\treadonly graceMs: number;\n\treadonly killTimeoutMs?: number;\n\treadonly processGroup?: boolean;\n\treadonly onEscalate?: () => Effect.Effect<void>;\n}\n\nconst signalManagedProcess = (\n\tchild: ManagedProcessChild,\n\tsignal: NodeJS.Signals,\n\tprocessGroup: boolean,\n): void => {\n\tif (processGroup && process.platform !== 'win32' && child.pid !== undefined) {\n\t\ttry {\n\t\t\tprocess.kill(-child.pid, signal);\n\t\t\treturn;\n\t\t} catch {\n\t\t\t// Fall back to the direct child signal below. This covers races\n\t\t\t// where the group has already exited and tests with fake pids.\n\t\t}\n\t}\n\tchild.kill(signal);\n};\n\nexport const terminateManagedProcess = (\n\tchild: ManagedProcessChild,\n\toptions: TerminateManagedProcessOptions,\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst exited = waitForProcessExitOrTimeout(child, options.graceMs);\n\t\tyield* Effect.sync(() => {\n\t\t\tsignalManagedProcess(child, 'SIGTERM', options.processGroup === true);\n\t\t});\n\t\tconst first = yield* Effect.promise(() => exited);\n\t\tif (first !== null) return;\n\t\tif (options.onEscalate !== undefined) {\n\t\t\tyield* options.onEscalate().pipe(Effect.ignore);\n\t\t}\n\t\tconst killed = waitForProcessExitOrTimeout(child, options.killTimeoutMs ?? 1_000);\n\t\tyield* Effect.sync(() => {\n\t\t\tsignalManagedProcess(child, 'SIGKILL', options.processGroup === true);\n\t\t});\n\t\tyield* Effect.promise(() => killed);\n\t});\n\nexport interface AwaitManagedProcessReadyOptions<E, R = never> {\n\treadonly ready: Effect.Effect<void, E, R>;\n\treadonly exit: Promise<ManagedProcessExitStatus>;\n\treadonly processError: Promise<unknown>;\n\treadonly onExitBeforeReady: (status: ManagedProcessExitStatus) => E;\n\treadonly onProcessErrorBeforeReady: (cause: unknown) => E;\n}\n\nexport const awaitManagedProcessReady = <E, R = never>(\n\toptions: AwaitManagedProcessReadyOptions<E, R>,\n): Effect.Effect<void, E, R> =>\n\tEffect.raceFirst(\n\t\toptions.ready,\n\t\tEffect.raceFirst(\n\t\t\tEffect.promise(() => options.exit).pipe(\n\t\t\t\tEffect.flatMap((status) => Effect.fail(options.onExitBeforeReady(status))),\n\t\t\t),\n\t\t\tEffect.promise(() => options.processError).pipe(\n\t\t\t\tEffect.flatMap((cause) => Effect.fail(options.onProcessErrorBeforeReady(cause))),\n\t\t\t),\n\t\t),\n\t);\n"],"mappings":";;;;;;;;;;;;;;;AAsCA,MAAa,sBAA6C,SAAS,MAAM,YACxE,MAAM,SAAS,CAAC,GAAG,KAAK,EAAE;CACzB,KAAK,QAAQ;CACb,KAAK,QAAQ;CACb,OAAO,QAAQ;CACf,UAAU,QAAQ;CAClB,CAAC;AAEH,MAAa,6BAA6B,WAA6C;AACtF,KAAI,OAAO,SAAS,KAAM,QAAO,aAAa,OAAO;AACrD,KAAI,OAAO,WAAW,KAAM,QAAO,UAAU,OAAO;AACpD,QAAO;;AAGR,MAAa,mBAAmB,UAC/B,IAAI,SAAS,gBAAgB;AAC5B,OAAM,KAAK,SAAS,MAAM,WAAW,YAAY;EAAE;EAAM;EAAQ,CAAC,CAAC;EAClE;AAEH,MAAa,wBACZ,UACqC;AACrC,KAAI,MAAM,aAAa,KAAA,KAAa,MAAM,aAAa,KACtD,QAAO;EAAE,MAAM,MAAM;EAAU,QAAQ;EAAM;AAE9C,KAAI,MAAM,eAAe,KAAA,KAAa,MAAM,eAAe,KAC1D,QAAO;EAAE,MAAM;EAAM,QAAQ,MAAM;EAAY;AAEhD,QAAO;;AAGR,MAAa,oBAAoB,UAChC,QAAQ,QAAQ,qBAAqB,MAAM,IAAI,gBAAgB,MAAM,CAAC;AAEvE,MAAa,oBAAoB,UAChC,IAAI,SAAS,iBAAiB;AAC7B,OAAM,KAAK,UAAU,UAAU,aAAa,MAAM,CAAC;EAClD;AAEH,MAAa,+BACZ,OACA,cAEA,QAAQ,KAAK,CACZ,gBAAgB,MAAM,EACtB,IAAI,SAAe,mBAAmB,iBAAiB,eAAe,KAAK,EAAE,UAAU,CAAC,CACxF,CAAC;AASH,MAAM,wBACL,OACA,QACA,iBACU;AACV,KAAI,gBAAgB,QAAQ,aAAa,WAAW,MAAM,QAAQ,KAAA,EACjE,KAAI;AACH,UAAQ,KAAK,CAAC,MAAM,KAAK,OAAO;AAChC;SACO;AAKT,OAAM,KAAK,OAAO;;AAGnB,MAAa,2BACZ,OACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,SAAS,4BAA4B,OAAO,QAAQ,QAAQ;AAClE,QAAO,OAAO,WAAW;AACxB,uBAAqB,OAAO,WAAW,QAAQ,iBAAiB,KAAK;GACpE;AAEF,MAAI,OADiB,OAAO,cAAc,OAAO,MACnC,KAAM;AACpB,KAAI,QAAQ,eAAe,KAAA,EAC1B,QAAO,QAAQ,YAAY,CAAC,KAAK,OAAO,OAAO;CAEhD,MAAM,SAAS,4BAA4B,OAAO,QAAQ,iBAAiB,IAAM;AACjF,QAAO,OAAO,WAAW;AACxB,uBAAqB,OAAO,WAAW,QAAQ,iBAAiB,KAAK;GACpE;AACF,QAAO,OAAO,cAAc,OAAO;EAClC;AAUH,MAAa,4BACZ,YAEA,OAAO,UACN,QAAQ,OACR,OAAO,UACN,OAAO,cAAc,QAAQ,KAAK,CAAC,KAClC,OAAO,SAAS,WAAW,OAAO,KAAK,QAAQ,kBAAkB,OAAO,CAAC,CAAC,CAC1E,EACD,OAAO,cAAc,QAAQ,aAAa,CAAC,KAC1C,OAAO,SAAS,UAAU,OAAO,KAAK,QAAQ,0BAA0B,MAAM,CAAC,CAAC,CAChF,CACD,CACD"}
+{"version":3,"file":"process-supervisor.mjs","names":[],"sources":["../../../src/substrate/runtime/process-supervisor.ts"],"sourcesContent":["import { spawn } from 'node:child_process';\nimport type { Readable } from 'node:stream';\n\nimport { Effect } from 'effect';\n\nexport interface ManagedProcessExitStatus {\n\treadonly code: number | null;\n\treadonly signal: NodeJS.Signals | null;\n}\n\nexport interface ManagedProcessChild {\n\treadonly pid?: number;\n\treadonly stdout?: Readable | null;\n\treadonly stderr?: Readable | null;\n\treadonly exitCode?: number | null;\n\treadonly signalCode?: NodeJS.Signals | null;\n\tkill(signal?: NodeJS.Signals): boolean;\n\ton(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;\n\ton(event: 'error', listener: (cause: Error) => void): this;\n\tonce(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;\n\tonce(event: 'error', listener: (cause: Error) => void): this;\n\toff(event: 'exit', listener: (code: number | null, signal: NodeJS.Signals | null) => void): this;\n\toff(event: 'error', listener: (cause: Error) => void): this;\n}\n\nexport interface ManagedProcessSpawnOptions {\n\treadonly cwd: string;\n\treadonly env: NodeJS.ProcessEnv;\n\treadonly stdio: 'pipe';\n\treadonly detached?: boolean;\n}\n\nexport type ManagedProcessSpawner = (\n\tcommand: string,\n\targs: ReadonlyArray<string>,\n\toptions: ManagedProcessSpawnOptions,\n) => ManagedProcessChild;\n\nexport const nodeProcessSpawner: ManagedProcessSpawner = (command, args, options) =>\n\tspawn(command, [...args], {\n\t\tcwd: options.cwd,\n\t\tenv: options.env,\n\t\tstdio: options.stdio,\n\t\tdetached: options.detached,\n\t}) as ManagedProcessChild;\n\nexport const describeProcessExitStatus = (status: ManagedProcessExitStatus): string => {\n\tif (status.code !== null) return `exit code ${status.code}`;\n\tif (status.signal !== null) return `signal ${status.signal}`;\n\treturn 'unknown exit status';\n};\n\nexport const onceProcessExit = (child: ManagedProcessChild): Promise<ManagedProcessExitStatus> =>\n\tnew Promise((resolveExit) => {\n\t\tchild.once('exit', (code, signal) => resolveExit({ code, signal }));\n\t});\n\nexport const getProcessExitStatus = (\n\tchild: ManagedProcessChild,\n): ManagedProcessExitStatus | null => {\n\tif (child.exitCode !== undefined && child.exitCode !== null) {\n\t\treturn { code: child.exitCode, signal: null };\n\t}\n\tif (child.signalCode !== undefined && child.signalCode !== null) {\n\t\treturn { code: null, signal: child.signalCode };\n\t}\n\treturn null;\n};\n\nexport const awaitProcessExit = (child: ManagedProcessChild): Promise<ManagedProcessExitStatus> =>\n\tPromise.resolve(getProcessExitStatus(child) ?? onceProcessExit(child));\n\nexport const onceProcessError = (child: ManagedProcessChild): Promise<unknown> =>\n\tnew Promise((resolveError) => {\n\t\tchild.once('error', (cause) => resolveError(cause));\n\t});\n\nexport const waitForProcessExitOrTimeout = (\n\tchild: ManagedProcessChild,\n\ttimeoutMs: number,\n): Promise<ManagedProcessExitStatus | null> =>\n\tPromise.race([\n\t\tonceProcessExit(child),\n\t\tnew Promise<null>((resolveTimeout) => setTimeout(() => resolveTimeout(null), timeoutMs)),\n\t]);\n\nexport interface TerminateManagedProcessOptions {\n\treadonly graceMs: number;\n\treadonly killTimeoutMs?: number;\n\treadonly processGroup?: boolean;\n\treadonly onEscalate?: () => Effect.Effect<void>;\n}\n\nconst signalManagedProcess = (\n\tchild: ManagedProcessChild,\n\tsignal: NodeJS.Signals,\n\tprocessGroup: boolean,\n): void => {\n\tif (processGroup && process.platform !== 'win32' && child.pid !== undefined) {\n\t\ttry {\n\t\t\tprocess.kill(-child.pid, signal);\n\t\t\treturn;\n\t\t} catch {\n\t\t\t// Fall back to the direct child signal below. This covers races\n\t\t\t// where the group has already exited and tests with fake pids.\n\t\t}\n\t}\n\tchild.kill(signal);\n};\n\nexport const terminateManagedProcess = (\n\tchild: ManagedProcessChild,\n\toptions: TerminateManagedProcessOptions,\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tconst exited = waitForProcessExitOrTimeout(child, options.graceMs);\n\t\tyield* Effect.sync(() => {\n\t\t\tsignalManagedProcess(child, 'SIGTERM', options.processGroup === true);\n\t\t});\n\t\tconst first = yield* Effect.promise(() => exited);\n\t\tif (first !== null) return;\n\t\tif (options.onEscalate !== undefined) {\n\t\t\tyield* options.onEscalate().pipe(Effect.ignore);\n\t\t}\n\t\tconst killed = waitForProcessExitOrTimeout(child, options.killTimeoutMs ?? 1_000);\n\t\tyield* Effect.sync(() => {\n\t\t\tsignalManagedProcess(child, 'SIGKILL', options.processGroup === true);\n\t\t});\n\t\tyield* Effect.promise(() => killed);\n\t});\n\nexport interface AwaitManagedProcessReadyOptions<E, R = never> {\n\treadonly ready: Effect.Effect<void, E, R>;\n\treadonly exit: Promise<ManagedProcessExitStatus>;\n\treadonly processError: Promise<unknown>;\n\treadonly onExitBeforeReady: (status: ManagedProcessExitStatus) => E;\n\treadonly onProcessErrorBeforeReady: (cause: unknown) => E;\n}\n\nexport const awaitManagedProcessReady = <E, R = never>(\n\toptions: AwaitManagedProcessReadyOptions<E, R>,\n): Effect.Effect<void, E, R> =>\n\tEffect.raceFirst(\n\t\toptions.ready,\n\t\tEffect.raceFirst(\n\t\t\tEffect.promise(() => options.exit).pipe(\n\t\t\t\tEffect.flatMap((status) => Effect.fail(options.onExitBeforeReady(status))),\n\t\t\t),\n\t\t\tEffect.promise(() => options.processError).pipe(\n\t\t\t\tEffect.flatMap((cause) => Effect.fail(options.onProcessErrorBeforeReady(cause))),\n\t\t\t),\n\t\t),\n\t);\n"],"mappings":";;;;;;;;;;;;;;;AAsCA,MAAa,sBAA6C,SAAS,MAAM,YACxE,MAAM,SAAS,CAAC,GAAG,IAAI,GAAG;CACzB,KAAK,QAAQ;CACb,KAAK,QAAQ;CACb,OAAO,QAAQ;CACf,UAAU,QAAQ;AACnB,CAAC;AAEF,MAAa,6BAA6B,WAA6C;CACtF,IAAI,OAAO,SAAS,MAAM,OAAO,aAAa,OAAO;CACrD,IAAI,OAAO,WAAW,MAAM,OAAO,UAAU,OAAO;CACpD,OAAO;AACR;AAEA,MAAa,mBAAmB,UAC/B,IAAI,SAAS,gBAAgB;CAC5B,MAAM,KAAK,SAAS,MAAM,WAAW,YAAY;EAAE;EAAM;CAAO,CAAC,CAAC;AACnE,CAAC;AAEF,MAAa,wBACZ,UACqC;CACrC,IAAI,MAAM,aAAa,KAAA,KAAa,MAAM,aAAa,MACtD,OAAO;EAAE,MAAM,MAAM;EAAU,QAAQ;CAAK;CAE7C,IAAI,MAAM,eAAe,KAAA,KAAa,MAAM,eAAe,MAC1D,OAAO;EAAE,MAAM;EAAM,QAAQ,MAAM;CAAW;CAE/C,OAAO;AACR;AAEA,MAAa,oBAAoB,UAChC,QAAQ,QAAQ,qBAAqB,KAAK,KAAK,gBAAgB,KAAK,CAAC;AAEtE,MAAa,oBAAoB,UAChC,IAAI,SAAS,iBAAiB;CAC7B,MAAM,KAAK,UAAU,UAAU,aAAa,KAAK,CAAC;AACnD,CAAC;AAEF,MAAa,+BACZ,OACA,cAEA,QAAQ,KAAK,CACZ,gBAAgB,KAAK,GACrB,IAAI,SAAe,mBAAmB,iBAAiB,eAAe,IAAI,GAAG,SAAS,CAAC,CACxF,CAAC;AASF,MAAM,wBACL,OACA,QACA,iBACU;CACV,IAAI,gBAAgB,QAAQ,aAAa,WAAW,MAAM,QAAQ,KAAA,GACjE,IAAI;EACH,QAAQ,KAAK,CAAC,MAAM,KAAK,MAAM;EAC/B;CACD,QAAQ,CAGR;CAED,MAAM,KAAK,MAAM;AAClB;AAEA,MAAa,2BACZ,OACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,SAAS,4BAA4B,OAAO,QAAQ,OAAO;CACjE,OAAO,OAAO,WAAW;EACxB,qBAAqB,OAAO,WAAW,QAAQ,iBAAiB,IAAI;CACrE,CAAC;CAED,KAAI,OADiB,OAAO,cAAc,MAAM,OAClC,MAAM;CACpB,IAAI,QAAQ,eAAe,KAAA,GAC1B,OAAO,QAAQ,WAAW,CAAC,CAAC,KAAK,OAAO,MAAM;CAE/C,MAAM,SAAS,4BAA4B,OAAO,QAAQ,iBAAiB,GAAK;CAChF,OAAO,OAAO,WAAW;EACxB,qBAAqB,OAAO,WAAW,QAAQ,iBAAiB,IAAI;CACrE,CAAC;CACD,OAAO,OAAO,cAAc,MAAM;AACnC,CAAC;AAUF,MAAa,4BACZ,YAEA,OAAO,UACN,QAAQ,OACR,OAAO,UACN,OAAO,cAAc,QAAQ,IAAI,CAAC,CAAC,KAClC,OAAO,SAAS,WAAW,OAAO,KAAK,QAAQ,kBAAkB,MAAM,CAAC,CAAC,CAC1E,GACA,OAAO,cAAc,QAAQ,YAAY,CAAC,CAAC,KAC1C,OAAO,SAAS,UAAU,OAAO,KAAK,QAAQ,0BAA0B,KAAK,CAAC,CAAC,CAChF,CACD,CACD"}

package/dist/substrate/runtime/projection/operational-endpoints.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"operational-endpoints.mjs","names":[],"sources":["../../../../src/substrate/runtime/projection/operational-endpoints.ts"],"sourcesContent":["import { endpointKey, type PluginKey } from '../../brand.ts';\nimport type { EngineEvent } from '../../events.ts';\n\ntype EndpointRegisteredEvent = Extract<EngineEvent, { readonly tag: 'endpoint.registered' }>;\n\n// Endpoint-projection policy is closed-allowlist:\n// only the fields enumerated below are projected as operational\n// endpoints. Anything else — including legitimate sensitive URLs\n// (`pairUrl`, `walletPairingToken`, OAuth `tokenUrl`, etc.) and any\n// future field a plugin adds — is ignored by default. A plugin that\n// wants a new field projected must extend this list AND ship a\n// projection test pinning its display name. The previous loose\n// \"skip-if-matches-sensitive-regex\" check dropped legitimate OAuth\n// fields like `tokenUrl` and missed novel sensitive names; the\n// allowlist removes that whole class of false-negative/false-positive\n// pair.\nconst SAFE_URL_FIELDS = {\n\turl: 'http',\n\trpcUrl: 'rpc',\n\tfaucetUrl: 'faucet',\n\tgraphqlUrl: 'graphql',\n} as const;\n\nexport interface OperationalEndpointProjectionOptions {\n\t/** Routable capabilities are the authoritative public endpoint\n\t * source. Resolved-value URL scraping is only a fallback for\n\t * plugins with no router contribution, such as live/local-rpc\n\t * network modes. */\n\treadonly routablesPresent?: boolean;\n}\n\nexport const operationalEndpointEventsFromResolvedValue = (\n\tpluginKey: PluginKey,\n\tvalue: unknown,\n\tregisteredAt: number,\n\toptions: OperationalEndpointProjectionOptions = {},\n): ReadonlyArray<EndpointRegisteredEvent> => {\n\tif (options.routablesPresent === true) return [];\n\tif (value === null || typeof value !== 'object') return [];\n\tconst record = value as Readonly<Record<string, unknown>>;\n\tconst events: Array<EndpointRegisteredEvent> = [];\n\tfor (const [field, name] of Object.entries(SAFE_URL_FIELDS)) {\n\t\tconst raw = record[field];\n\t\tif (typeof raw !== 'string' || !isHttpUrl(raw)) continue;\n\t\tevents.push({\n\t\t\ttag: 'endpoint.registered',\n\t\t\tendpoint: {\n\t\t\t\tendpointKey: endpointKey(`${pluginKey}:${field}`),\n\t\t\t\tpluginKey,\n\t\t\t\tname,\n\t\t\t\turl: raw,\n\t\t\t\tdisplayUrl: null,\n\t\t\t\twireProtocol: 'http',\n\t\t\t\tregisteredAt,\n\t\t\t},\n\t\t});\n\t}\n\treturn events;\n};\n\nconst isHttpUrl = (value: string): boolean => {\n\ttry {\n\t\tconst parsed = new URL(value);\n\t\treturn parsed.protocol === 'http:' || parsed.protocol === 'https:';\n\t} catch {\n\t\treturn false;\n\t}\n};\n"],"mappings":";;AAgBA,MAAM,kBAAkB;CACvB,KAAK;CACL,QAAQ;CACR,WAAW;CACX,YAAY;CACZ;AAUD,MAAa,8CACZ,WACA,OACA,cACA,UAAgD,EAAE,KACN;AAC5C,KAAI,QAAQ,qBAAqB,KAAM,QAAO,EAAE;AAChD,KAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO,EAAE;CAC1D,MAAM,SAAS;CACf,MAAM,SAAyC,EAAE;AACjD,MAAK,MAAM,CAAC,OAAO,SAAS,OAAO,QAAQ,gBAAgB,EAAE;EAC5D,MAAM,MAAM,OAAO;AACnB,MAAI,OAAO,QAAQ,YAAY,CAAC,UAAU,IAAI,CAAE;AAChD,SAAO,KAAK;GACX,KAAK;GACL,UAAU;IACT,aAAa,YAAY,GAAG,UAAU,GAAG,QAAQ;IACjD;IACA;IACA,KAAK;IACL,YAAY;IACZ,cAAc;IACd;IACA;GACD,CAAC;;AAEH,QAAO;;AAGR,MAAM,aAAa,UAA2B;AAC7C,KAAI;EACH,MAAM,SAAS,IAAI,IAAI,MAAM;AAC7B,SAAO,OAAO,aAAa,WAAW,OAAO,aAAa;SACnD;AACP,SAAO"}
+{"version":3,"file":"operational-endpoints.mjs","names":[],"sources":["../../../../src/substrate/runtime/projection/operational-endpoints.ts"],"sourcesContent":["import { endpointKey, type PluginKey } from '../../brand.ts';\nimport type { EngineEvent } from '../../events.ts';\n\ntype EndpointRegisteredEvent = Extract<EngineEvent, { readonly tag: 'endpoint.registered' }>;\n\n// Endpoint-projection policy is closed-allowlist:\n// only the fields enumerated below are projected as operational\n// endpoints. Anything else — including legitimate sensitive URLs\n// (`pairUrl`, `walletPairingToken`, OAuth `tokenUrl`, etc.) and any\n// future field a plugin adds — is ignored by default. A plugin that\n// wants a new field projected must extend this list AND ship a\n// projection test pinning its display name. The previous loose\n// \"skip-if-matches-sensitive-regex\" check dropped legitimate OAuth\n// fields like `tokenUrl` and missed novel sensitive names; the\n// allowlist removes that whole class of false-negative/false-positive\n// pair.\nconst SAFE_URL_FIELDS = {\n\turl: 'http',\n\trpcUrl: 'rpc',\n\tfaucetUrl: 'faucet',\n\tgraphqlUrl: 'graphql',\n} as const;\n\nexport interface OperationalEndpointProjectionOptions {\n\t/** Routable capabilities are the authoritative public endpoint\n\t * source. Resolved-value URL scraping is only a fallback for\n\t * plugins with no router contribution, such as live/local-rpc\n\t * network modes. */\n\treadonly routablesPresent?: boolean;\n}\n\nexport const operationalEndpointEventsFromResolvedValue = (\n\tpluginKey: PluginKey,\n\tvalue: unknown,\n\tregisteredAt: number,\n\toptions: OperationalEndpointProjectionOptions = {},\n): ReadonlyArray<EndpointRegisteredEvent> => {\n\tif (options.routablesPresent === true) return [];\n\tif (value === null || typeof value !== 'object') return [];\n\tconst record = value as Readonly<Record<string, unknown>>;\n\tconst events: Array<EndpointRegisteredEvent> = [];\n\tfor (const [field, name] of Object.entries(SAFE_URL_FIELDS)) {\n\t\tconst raw = record[field];\n\t\tif (typeof raw !== 'string' || !isHttpUrl(raw)) continue;\n\t\tevents.push({\n\t\t\ttag: 'endpoint.registered',\n\t\t\tendpoint: {\n\t\t\t\tendpointKey: endpointKey(`${pluginKey}:${field}`),\n\t\t\t\tpluginKey,\n\t\t\t\tname,\n\t\t\t\turl: raw,\n\t\t\t\tdisplayUrl: null,\n\t\t\t\twireProtocol: 'http',\n\t\t\t\tregisteredAt,\n\t\t\t},\n\t\t});\n\t}\n\treturn events;\n};\n\nconst isHttpUrl = (value: string): boolean => {\n\ttry {\n\t\tconst parsed = new URL(value);\n\t\treturn parsed.protocol === 'http:' || parsed.protocol === 'https:';\n\t} catch {\n\t\treturn false;\n\t}\n};\n"],"mappings":";;AAgBA,MAAM,kBAAkB;CACvB,KAAK;CACL,QAAQ;CACR,WAAW;CACX,YAAY;AACb;AAUA,MAAa,8CACZ,WACA,OACA,cACA,UAAgD,CAAC,MACL;CAC5C,IAAI,QAAQ,qBAAqB,MAAM,OAAO,CAAC;CAC/C,IAAI,UAAU,QAAQ,OAAO,UAAU,UAAU,OAAO,CAAC;CACzD,MAAM,SAAS;CACf,MAAM,SAAyC,CAAC;CAChD,KAAK,MAAM,CAAC,OAAO,SAAS,OAAO,QAAQ,eAAe,GAAG;EAC5D,MAAM,MAAM,OAAO;EACnB,IAAI,OAAO,QAAQ,YAAY,CAAC,UAAU,GAAG,GAAG;EAChD,OAAO,KAAK;GACX,KAAK;GACL,UAAU;IACT,aAAa,YAAY,GAAG,UAAU,GAAG,OAAO;IAChD;IACA;IACA,KAAK;IACL,YAAY;IACZ,cAAc;IACd;GACD;EACD,CAAC;CACF;CACA,OAAO;AACR;AAEA,MAAM,aAAa,UAA2B;CAC7C,IAAI;EACH,MAAM,SAAS,IAAI,IAAI,KAAK;EAC5B,OAAO,OAAO,aAAa,WAAW,OAAO,aAAa;CAC3D,QAAQ;EACP,OAAO;CACR;AACD"}

package/dist/substrate/runtime/projection/state-ref.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"state-ref.mjs","names":[],"sources":["../../../../src/substrate/runtime/projection/state-ref.ts"],"sourcesContent":["// Subscribable projection state-ref.\n//\n// Architecture § Renderer § \"Subscribable projection — exact field\n// enumeration\" (G2) + § \"Renderer mount lifetime vs engine cycle\n// lifetime\" (decision #8). The state-ref is process-scoped (mounted\n// once); the engine cycle re-runs many times and never re-creates the\n// ref. The renderer subscribes once at mount; the engine updates\n// in-place across cycles.\n//\n// The projection's TypeScript shape is enforced closed by\n// `__ProjectionFieldsClosed` in `../../projection.ts`. Adding a\n// display-vocabulary field (`title`, `primary`, `extras`) at this\n// layer would fail to assign into `SubscribableState` — renderers\n// derive those from `rows[*].kind` + display rules.\n\nimport { Effect, SubscriptionRef } from 'effect';\n\nimport type {\n\tBuildEntry,\n\tAccountProjection,\n\tEndpoint,\n\tPackageProjection,\n\tRow,\n\tStructuredError,\n\tSubscribableState,\n} from '../../projection.ts';\n\n/**\n * Empty initial projection. Cycle starts at `id: 0`, `phase:\n * 'booting'`. Identity fields are placeholder; the engine MUST\n * replace via `update.ts::setIdentity` before any renderer is\n * notified of anything user-visible.\n *\n * The shape here is the entire contract the renderer sees — no\n * service names, no display vocabulary. If a future field needs\n * adding, the architecture-revision discipline kicks in via\n * `__ProjectionFieldsClosed`.\n */\nexport const emptyProjection = (): SubscribableState => ({\n\tidentity: { app: '', stack: '', network: '' },\n\tcycle: { id: 0, startedAt: 0, phase: 'booting' },\n\trows: [],\n\tendpoints: [],\n\taccounts: [],\n\tpackages: [],\n\terrors: [],\n\tlastEvent: { seq: 0, at: 0 },\n\tstackBuild: [],\n});\n\n/**\n * Create the subscribable projection ref. One per process.\n *\n * Engine cycle: the ref outlives the engine cycle. Stop-and-restart\n * keeps the same ref; only `cycle.id` increments. Renderers see a\n * continuous stream — that's the whole point of decoupling renderer\n * lifetime from engine cycle.\n */\nexport const makeProjectionRef = (): Effect.Effect<\n\tSubscriptionRef.SubscriptionRef<SubscribableState>\n> => SubscriptionRef.make(emptyProjection());\n\n/**\n * Sync-only constructor for the subscribable projection ref. The\n * `runStack(...)` API allocates the ref BEFORE the supervised\n * Effect runs so callers can subscribe to `state.changes` ahead of\n * boot — that allocation path has no Effect runtime to run under and\n * must complete synchronously.\n *\n * Callers that already live inside an Effect should use the\n * Effect-wrapped `makeProjectionRef()` so future changes to the\n * constructor stay Effect-correct without breaking those call\n * sites. This sync variant is pinned at the substrate boundary: any\n * future refactor of `makeProjectionRef` (e.g. layering a `withSpan`\n * or annotation) MUST keep `makeProjectionRefSync` synchronous — if\n * that ever becomes impossible the boot-time call site needs a\n * different signaling strategy (Deferred-handoff), not a silent\n * `Effect.runSync` crash on an async effect.\n *\n * `SubscriptionRef.make` is sync-effect today (no async, no\n * side-effects beyond an `unbounded` `PubSub.unbounded({ replay:\n * 1 })`), so `Effect.runSync` is safe right now; the indirection\n * exists so the constraint is documented at the constructor, not\n * inferred from the caller.\n */\nexport const makeProjectionRefSync = (): SubscriptionRef.SubscriptionRef<SubscribableState> =>\n\tEffect.runSync(makeProjectionRef());\n\n/**\n * Compile-time guard: the projection shape MUST NOT contain display\n * vocabulary. These conditional types resolve to `never` (and would\n * fail to assign anywhere they're used) if `title`/`primary`/\n * `extras` were ever added to `SubscribableState` or `Row`.\n *\n * The architecture's invariant becomes a TS error at the boundary\n * — the projection layer can't be wired up if a renderer-display\n * concept leaks into the engine's data model.\n */\ntype _NoDisplayVocabAtTop = 'title' extends keyof SubscribableState\n\t? never\n\t: 'primary' extends keyof SubscribableState\n\t\t? never\n\t\t: 'extras' extends keyof SubscribableState\n\t\t\t? never\n\t\t\t: true;\ntype _NoDisplayVocabInRow = 'title' extends keyof Row\n\t? never\n\t: 'primary' extends keyof Row\n\t\t? never\n\t\t: 'extras' extends keyof Row\n\t\t\t? never\n\t\t\t: true;\nexport type __NoDisplayVocab = _NoDisplayVocabAtTop & _NoDisplayVocabInRow extends true\n\t? true\n\t: never;\n\n// Re-export the sub-types renderers reach for so they don't import\n// across the substrate boundary directly — `state-ref.ts` is the\n// renderer-facing entry point.\nexport type {\n\tAccountProjection,\n\tBuildEntry,\n\tEndpoint,\n\tPackageProjection,\n\tRow,\n\tStructuredError,\n\tSubscribableState,\n};\n"],"mappings":";;;;;;;;;;;;;AAsCA,MAAa,yBAA4C;CACxD,UAAU;EAAE,KAAK;EAAI,OAAO;EAAI,SAAS;EAAI;CAC7C,OAAO;EAAE,IAAI;EAAG,WAAW;EAAG,OAAO;EAAW;CAChD,MAAM,EAAE;CACR,WAAW,EAAE;CACb,UAAU,EAAE;CACZ,UAAU,EAAE;CACZ,QAAQ,EAAE;CACV,WAAW;EAAE,KAAK;EAAG,IAAI;EAAG;CAC5B,YAAY,EAAE;CACd;;;;;;;;;AAUD,MAAa,0BAER,gBAAgB,KAAK,iBAAiB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyB5C,MAAa,8BACZ,OAAO,QAAQ,mBAAmB,CAAC"}
+{"version":3,"file":"state-ref.mjs","names":[],"sources":["../../../../src/substrate/runtime/projection/state-ref.ts"],"sourcesContent":["// Subscribable projection state-ref.\n//\n// Architecture § Renderer § \"Subscribable projection — exact field\n// enumeration\" (G2) + § \"Renderer mount lifetime vs engine cycle\n// lifetime\" (decision #8). The state-ref is process-scoped (mounted\n// once); the engine cycle re-runs many times and never re-creates the\n// ref. The renderer subscribes once at mount; the engine updates\n// in-place across cycles.\n//\n// The projection's TypeScript shape is enforced closed by\n// `__ProjectionFieldsClosed` in `../../projection.ts`. Adding a\n// display-vocabulary field (`title`, `primary`, `extras`) at this\n// layer would fail to assign into `SubscribableState` — renderers\n// derive those from `rows[*].kind` + display rules.\n\nimport { Effect, SubscriptionRef } from 'effect';\n\nimport type {\n\tBuildEntry,\n\tAccountProjection,\n\tEndpoint,\n\tPackageProjection,\n\tRow,\n\tStructuredError,\n\tSubscribableState,\n} from '../../projection.ts';\n\n/**\n * Empty initial projection. Cycle starts at `id: 0`, `phase:\n * 'booting'`. Identity fields are placeholder; the engine MUST\n * replace via `update.ts::setIdentity` before any renderer is\n * notified of anything user-visible.\n *\n * The shape here is the entire contract the renderer sees — no\n * service names, no display vocabulary. If a future field needs\n * adding, the architecture-revision discipline kicks in via\n * `__ProjectionFieldsClosed`.\n */\nexport const emptyProjection = (): SubscribableState => ({\n\tidentity: { app: '', stack: '', network: '' },\n\tcycle: { id: 0, startedAt: 0, phase: 'booting' },\n\trows: [],\n\tendpoints: [],\n\taccounts: [],\n\tpackages: [],\n\terrors: [],\n\tlastEvent: { seq: 0, at: 0 },\n\tstackBuild: [],\n});\n\n/**\n * Create the subscribable projection ref. One per process.\n *\n * Engine cycle: the ref outlives the engine cycle. Stop-and-restart\n * keeps the same ref; only `cycle.id` increments. Renderers see a\n * continuous stream — that's the whole point of decoupling renderer\n * lifetime from engine cycle.\n */\nexport const makeProjectionRef = (): Effect.Effect<\n\tSubscriptionRef.SubscriptionRef<SubscribableState>\n> => SubscriptionRef.make(emptyProjection());\n\n/**\n * Sync-only constructor for the subscribable projection ref. The\n * `runStack(...)` API allocates the ref BEFORE the supervised\n * Effect runs so callers can subscribe to `state.changes` ahead of\n * boot — that allocation path has no Effect runtime to run under and\n * must complete synchronously.\n *\n * Callers that already live inside an Effect should use the\n * Effect-wrapped `makeProjectionRef()` so future changes to the\n * constructor stay Effect-correct without breaking those call\n * sites. This sync variant is pinned at the substrate boundary: any\n * future refactor of `makeProjectionRef` (e.g. layering a `withSpan`\n * or annotation) MUST keep `makeProjectionRefSync` synchronous — if\n * that ever becomes impossible the boot-time call site needs a\n * different signaling strategy (Deferred-handoff), not a silent\n * `Effect.runSync` crash on an async effect.\n *\n * `SubscriptionRef.make` is sync-effect today (no async, no\n * side-effects beyond an `unbounded` `PubSub.unbounded({ replay:\n * 1 })`), so `Effect.runSync` is safe right now; the indirection\n * exists so the constraint is documented at the constructor, not\n * inferred from the caller.\n */\nexport const makeProjectionRefSync = (): SubscriptionRef.SubscriptionRef<SubscribableState> =>\n\tEffect.runSync(makeProjectionRef());\n\n// Re-export the sub-types renderers reach for so they don't import\n// across the substrate boundary directly — `state-ref.ts` is the\n// renderer-facing entry point.\nexport type {\n\tAccountProjection,\n\tBuildEntry,\n\tEndpoint,\n\tPackageProjection,\n\tRow,\n\tStructuredError,\n\tSubscribableState,\n};\n"],"mappings":";;;;;;;;;;;;;AAsCA,MAAa,yBAA4C;CACxD,UAAU;EAAE,KAAK;EAAI,OAAO;EAAI,SAAS;CAAG;CAC5C,OAAO;EAAE,IAAI;EAAG,WAAW;EAAG,OAAO;CAAU;CAC/C,MAAM,CAAC;CACP,WAAW,CAAC;CACZ,UAAU,CAAC;CACX,UAAU,CAAC;CACX,QAAQ,CAAC;CACT,WAAW;EAAE,KAAK;EAAG,IAAI;CAAE;CAC3B,YAAY,CAAC;AACd;;;;;;;;;AAUA,MAAa,0BAER,gBAAgB,KAAK,gBAAgB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyB3C,MAAa,8BACZ,OAAO,QAAQ,kBAAkB,CAAC"}

package/dist/substrate/runtime/projection/update.mjs

@@ -1,15 +1,87 @@
-import { SpanAttr } from "../observability/spans.mjs";
-import { AccountProjectionSchema, PackageProjectionSchema } from "./persisted.mjs";
+import { LogAttr } from "../observability/log-attrs.mjs";
 import { eventAtOrNull } from "../../event-time.mjs";
-import { applyLifecycleFact, factFromEvent } from "../lifecycle/lifecycle-fact.mjs";
 import { Effect, Schema, SubscriptionRef } from "effect";
 //#region src/substrate/runtime/projection/update.ts
+/** Structural schema for a `projection.updated[account]` payload. */
+const AccountProjectionSchema = Schema.Struct({
+	key: Schema.String,
+	rowKey: Schema.NullOr(Schema.String),
+	name: Schema.String,
+	address: Schema.NullOr(Schema.String),
+	scheme: Schema.NullOr(Schema.Literals([
+		"ed25519",
+		"secp256k1",
+		"secp256r1"
+	])),
+	source: Schema.NullOr(Schema.Literals(["real", "impersonate"])),
+	funding: Schema.Struct({
+		status: Schema.Literals([
+			"pending",
+			"funded",
+			"skipped",
+			"failed",
+			"unknown"
+		]),
+		balanceMist: Schema.NullOr(Schema.String),
+		requestedMist: Schema.NullOr(Schema.String),
+		entries: Schema.optional(Schema.Array(Schema.Struct({
+			coin: Schema.String,
+			fullCoinType: Schema.String,
+			amount: Schema.String,
+			status: Schema.Literals([
+				"funded",
+				"already-satisfied",
+				"skipped"
+			])
+		})))
+	}),
+	walletVisible: Schema.Boolean,
+	updatedAt: Schema.Number
+});
+/** Structural schema for a `projection.updated[package]` payload. */
+const PackageProjectionSchema = Schema.Struct({
+	key: Schema.String,
+	rowKey: Schema.NullOr(Schema.String),
+	name: Schema.String,
+	kind: Schema.Literals(["local", "known"]),
+	packageId: Schema.String,
+	upgradeCapId: Schema.NullOr(Schema.String),
+	mvrPlaceholder: Schema.String,
+	sourcePath: Schema.NullOr(Schema.String),
+	updatedAt: Schema.Number
+});
 /** Bounded buffer for the top-level errors list. */
 const MAX_ERRORS_KEPT = 100;
 /** Bounded buffer for the top-level build-entries list. */
 const MAX_BUILD_ENTRIES_KEPT = 200;
 /** Per-row bounded log-tail length. Architecture: default 100 lines. */
 const MAX_ROW_LOG_LINES = 100;
+/** Project a lifecycle-shaped `EngineEvent` into a per-plugin delta.
+*  Returns `null` for events that don't carry lifecycle information so
+*  the reducer can short-circuit. The substrate stays event-name-blind
+*  by routing through this single mapping table. */
+const factFromEvent = (event) => {
+	switch (event.tag) {
+		case "lifecycle.statusChanged": return {
+			pluginKey: event.pluginKey,
+			delta: { status: event.to }
+		};
+		case "lifecycle.phaseSet": return {
+			pluginKey: event.pluginKey,
+			delta: { phase: event.phase }
+		};
+		default: return null;
+	}
+};
+/** Apply a fact delta to a row. Pure. Fields not in the delta are
+*  preserved verbatim — the merge-not-replace shape `LifecycleFact`
+*  promises. */
+const applyLifecycleFact = (row, delta) => ({
+	...row,
+	...delta.status !== void 0 ? { status: delta.status } : {},
+	...delta.phase !== void 0 ? { phase: delta.phase } : {},
+	...delta.selectiveRestartHighlight !== void 0 ? { selectiveRestartHighlight: delta.selectiveRestartHighlight } : {}
+});
 /**
 * Pure projection reducer. One event in, one new state out. All field
 * writes preserve `readonly` invariants by constructing fresh
@@ -56,13 +128,17 @@ const applyEvent = (state, event, prevalidated) => {
 		case "strategy.registered":
 		case "strategy.unregistered":
 		case "manifest.flushed":
-		case "codegen.emitted":
-		case "snapshot.captureStarted":
-		case "snapshot.captureProgress":
+		case "codegen.emitted": return withTouched({});
 		case "snapshot.captureSkipped":
 		case "snapshot.captureFailed":
-		case "snapshot.captured":
-		case "snapshot.restored": return withTouched({});
+		case "snapshot.captured": return withTouched({ cycle: state.cycle.phase === "snapshotting" ? {
+			...state.cycle,
+			phase: "running"
+		} : state.cycle });
+		case "snapshot.restored": return withTouched({ cycle: {
+			...state.cycle,
+			phase: "restoring"
+		} });
 		case "shutdown.escalated": return withTouched({ cycle: {
 			...state.cycle,
 			phase: "shutting-down"
@@ -133,7 +209,7 @@ const updateRef = (ref, event) => Effect.gen(function* () {
 	if (event.tag === "projection.updated") {
 		if (event.kind === "account" || event.kind === "package") {
 			prevalidated = tryDecodeProjectionPayload(event.kind === "account" ? AccountProjectionSchema : PackageProjectionSchema, event.payload);
-			if (!prevalidated.ok) yield* Effect.logWarning(`projection.updated: dropping malformed ${event.kind} payload for key=${event.key}`).pipe(Effect.annotateLogs({ [SpanAttr.errorMessage]: formatDecodeIssue(prevalidated.cause) }));
+			if (!prevalidated.ok) yield* Effect.logWarning(`projection.updated: dropping malformed ${event.kind} payload for key=${event.key}`).pipe(Effect.annotateLogs({ [LogAttr.errorMessage]: formatDecodeIssue(prevalidated.cause) }));
 		}
 	}
 	yield* SubscriptionRef.update(ref, (state) => {
@@ -199,7 +275,7 @@ const upsertRow = (rows, key, update) => {
 const appendLogLine = (row, line, level) => {
 	const nextLines = [...row.logTail.lines, line];
 	const truncated = nextLines.length > MAX_ROW_LOG_LINES;
-	const trimmed = truncated ? nextLines.slice(-MAX_ROW_LOG_LINES) : nextLines;
+	const trimmed = truncated ? nextLines.slice(-100) : nextLines;
 	return {
 		...row,
 		logTail: {
@@ -259,6 +335,6 @@ const pushBounded = (xs, value, max) => {
 	return next.length > max ? next.slice(-max) : next;
 };
 //#endregion
-export { applyEvent, declareAccount, setIdentity, updateRef };
+export { AccountProjectionSchema, PackageProjectionSchema, declareAccount, setIdentity, updateRef };
 
 //# sourceMappingURL=update.mjs.map