@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/api/load-config.mjs

@@ -0,0 +1,88 @@
+import { readStackEngine } from "./define-devstack.mjs";
+import { Data, Effect } from "effect";
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region src/api/load-config.ts
+const DEFAULT_CONFIG_PATH = "./devstack.config.ts";
+/** Resolve a `--config <path>` argument to an absolute path, falling
+*  through to a parent-directory search when the default value is
+*  used. Returns `null` when no candidate exists. */
+const resolveConfigPath = (configPath) => {
+	const target = configPath ?? "./devstack.config.ts";
+	const explicit = isAbsolute(target) ? target : resolve(process.cwd(), target);
+	if (existsSync(explicit)) return explicit;
+	if (configPath !== void 0 && configPath !== "./devstack.config.ts") return null;
+	let dir = process.cwd();
+	for (;;) {
+		const candidate = resolve(dir, "devstack.config.ts");
+		if (existsSync(candidate)) return candidate;
+		const parent = resolve(dir, "..");
+		if (parent === dir) return null;
+		dir = parent;
+	}
+};
+/** Typed failure of {@link loadDevstackConfig}. `kind` distinguishes a
+*  missing config from an invalid one so CLI wrappers can map it to the
+*  right exit code. */
+var DevstackConfigError = class extends Data.TaggedError("DevstackConfigError") {};
+const validate = (resolvedConfigPath, mod) => {
+	const def = mod.default;
+	if (def === null || typeof def !== "object" || def._tag !== "Stack") throw new DevstackConfigError({
+		kind: "invalid",
+		message: `config at ${resolvedConfigPath} does not default-export a Stack value (got _tag=${String(def?._tag)})`
+	});
+	const publicStack = def;
+	let engine;
+	try {
+		engine = readStackEngine(publicStack);
+	} catch (cause) {
+		throw new DevstackConfigError({
+			kind: "invalid",
+			message: `config at ${resolvedConfigPath} default-exported an invalid Stack handle: ${cause instanceof Error ? cause.message : String(cause)}`,
+			cause
+		});
+	}
+	return {
+		stack: publicStack,
+		engine,
+		resolvedConfigPath
+	};
+};
+/**
+* Resolve, import, and validate a `devstack.config.ts`. Returns the
+* public stack handle (for `runStack`) plus the engine stack and the
+* resolved config path. Fails with a {@link DevstackConfigError}.
+*/
+const loadDevstackConfig = (configPath) => Effect.gen(function* () {
+	const abs = resolveConfigPath(configPath);
+	if (abs === null) {
+		const attempted = configPath !== void 0 ? resolve(process.cwd(), configPath) : resolve(process.cwd(), DEFAULT_CONFIG_PATH);
+		return yield* Effect.fail(new DevstackConfigError({
+			kind: "not-found",
+			message: `devstack config not found at ${attempted}`,
+			searchedPaths: [attempted]
+		}));
+	}
+	const url = pathToFileURL(abs).href;
+	const mod = yield* Effect.tryPromise({
+		try: () => import(url),
+		catch: (cause) => new DevstackConfigError({
+			kind: "invalid",
+			message: `failed to import ${abs}: ${cause instanceof Error ? cause.message : String(cause)}`,
+			cause
+		})
+	});
+	return yield* Effect.try({
+		try: () => validate(abs, mod),
+		catch: (cause) => cause instanceof DevstackConfigError ? cause : new DevstackConfigError({
+			kind: "invalid",
+			message: `invalid config at ${abs}`,
+			cause
+		})
+	});
+});
+//#endregion
+export { DEFAULT_CONFIG_PATH, loadDevstackConfig, resolveConfigPath };
+
+//# sourceMappingURL=load-config.mjs.map

package/dist/api/load-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-config.mjs","names":["resolvePath"],"sources":["../../src/api/load-config.ts"],"sourcesContent":["// CLI-free config loader. Resolves and imports a `devstack.config.ts`,\n// validates its default-exported `Stack`, and returns the public stack\n// handle plus the erased engine stack.\n//\n// This is the single source of truth for config path resolution +\n// loading. The CLI wrapper (`cli/wirings/config-loader.ts`) re-exports\n// `resolveConfigPath`/`DEFAULT_CONFIG_PATH` and translates this module's\n// `DevstackConfigError` into the CLI-flavored `CliConfig*` errors.\n//\n// Why it lives under `api/` and avoids `cli/`/`surfaces/`: build\n// integrations (the vitest `globalSetup`) need to load a config to boot\n// a stack, but must NOT pull the CLI/TUI graph into their bundle. This\n// module depends only on node built-ins, `effect`, and the api/substrate\n// types.\n\nimport { existsSync } from 'node:fs';\nimport { isAbsolute, resolve as resolvePath } from 'node:path';\nimport { pathToFileURL } from 'node:url';\n\nimport { Data, Effect } from 'effect';\n\nimport { readStackEngine, type Stack } from './define-devstack.ts';\nimport type { SupervisedStack } from '../substrate/runtime/index.ts';\n\nexport const DEFAULT_CONFIG_PATH = './devstack.config.ts';\n\n/** Resolve a `--config <path>` argument to an absolute path, falling\n *  through to a parent-directory search when the default value is\n *  used. Returns `null` when no candidate exists. */\nexport const resolveConfigPath = (configPath: string | undefined): string | null => {\n\tconst target = configPath ?? DEFAULT_CONFIG_PATH;\n\tconst explicit = isAbsolute(target) ? target : resolvePath(process.cwd(), target);\n\tif (existsSync(explicit)) return explicit;\n\tif (configPath !== undefined && configPath !== DEFAULT_CONFIG_PATH) return null;\n\tlet dir = process.cwd();\n\tfor (;;) {\n\t\tconst candidate = resolvePath(dir, 'devstack.config.ts');\n\t\tif (existsSync(candidate)) return candidate;\n\t\tconst parent = resolvePath(dir, '..');\n\t\tif (parent === dir) return null;\n\t\tdir = parent;\n\t}\n};\n\n/** Typed failure of {@link loadDevstackConfig}. `kind` distinguishes a\n *  missing config from an invalid one so CLI wrappers can map it to the\n *  right exit code. */\nexport class DevstackConfigError extends Data.TaggedError('DevstackConfigError')<{\n\treadonly kind: 'not-found' | 'invalid';\n\treadonly message: string;\n\treadonly searchedPaths?: ReadonlyArray<string>;\n\treadonly cause?: unknown;\n}> {}\n\nexport interface LoadedDevstackConfig {\n\t/** The public stack handle exactly as the config default-exported it\n\t *  — the value to feed `runStack`. */\n\treadonly stack: Stack<SupervisedStack['members']>;\n\t/** The validated internal engine stack (erased runtime boundary\n\t *  shape) — exposes `options.codegen`/`options.stateDir`. */\n\treadonly engine: SupervisedStack;\n\t/** Absolute path of the config file that was loaded. */\n\treadonly resolvedConfigPath: string;\n}\n\nconst validate = (\n\tresolvedConfigPath: string,\n\tmod: { readonly default?: unknown },\n): LoadedDevstackConfig => {\n\tconst def = mod.default;\n\tif (def === null || typeof def !== 'object' || (def as { _tag?: unknown })._tag !== 'Stack') {\n\t\tthrow new DevstackConfigError({\n\t\t\tkind: 'invalid',\n\t\t\tmessage: `config at ${resolvedConfigPath} does not default-export a Stack value (got _tag=${String((def as { _tag?: unknown })?._tag)})`,\n\t\t});\n\t}\n\tconst publicStack = def as Stack<SupervisedStack['members']>;\n\tlet engine: SupervisedStack;\n\ttry {\n\t\tengine = readStackEngine(publicStack);\n\t} catch (cause) {\n\t\tthrow new DevstackConfigError({\n\t\t\tkind: 'invalid',\n\t\t\tmessage: `config at ${resolvedConfigPath} default-exported an invalid Stack handle: ${cause instanceof Error ? cause.message : String(cause)}`,\n\t\t\tcause,\n\t\t});\n\t}\n\treturn { stack: publicStack, engine, resolvedConfigPath };\n};\n\n/**\n * Resolve, import, and validate a `devstack.config.ts`. Returns the\n * public stack handle (for `runStack`) plus the engine stack and the\n * resolved config path. Fails with a {@link DevstackConfigError}.\n */\nexport const loadDevstackConfig = (\n\tconfigPath?: string,\n): Effect.Effect<LoadedDevstackConfig, DevstackConfigError> =>\n\tEffect.gen(function* () {\n\t\tconst abs = resolveConfigPath(configPath);\n\t\tif (abs === null) {\n\t\t\tconst attempted =\n\t\t\t\tconfigPath !== undefined\n\t\t\t\t\t? resolvePath(process.cwd(), configPath)\n\t\t\t\t\t: resolvePath(process.cwd(), DEFAULT_CONFIG_PATH);\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew DevstackConfigError({\n\t\t\t\t\tkind: 'not-found',\n\t\t\t\t\tmessage: `devstack config not found at ${attempted}`,\n\t\t\t\t\tsearchedPaths: [attempted],\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst url = pathToFileURL(abs).href;\n\t\tconst mod = yield* Effect.tryPromise({\n\t\t\ttry: () => import(url) as Promise<{ readonly default?: unknown }>,\n\t\t\tcatch: (cause) =>\n\t\t\t\tnew DevstackConfigError({\n\t\t\t\t\tkind: 'invalid',\n\t\t\t\t\tmessage: `failed to import ${abs}: ${cause instanceof Error ? cause.message : String(cause)}`,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t});\n\t\treturn yield* Effect.try({\n\t\t\ttry: () => validate(abs, mod),\n\t\t\tcatch: (cause) =>\n\t\t\t\tcause instanceof DevstackConfigError\n\t\t\t\t\t? cause\n\t\t\t\t\t: new DevstackConfigError({\n\t\t\t\t\t\t\tkind: 'invalid',\n\t\t\t\t\t\t\tmessage: `invalid config at ${abs}`,\n\t\t\t\t\t\t\tcause,\n\t\t\t\t\t\t}),\n\t\t});\n\t});\n"],"mappings":";;;;;;AAwBA,MAAa,sBAAsB;;;;AAKnC,MAAa,qBAAqB,eAAkD;CACnF,MAAM,SAAS,cAAA;CACf,MAAM,WAAW,WAAW,MAAM,IAAI,SAASA,QAAY,QAAQ,IAAI,GAAG,MAAM;CAChF,IAAI,WAAW,QAAQ,GAAG,OAAO;CACjC,IAAI,eAAe,KAAA,KAAa,eAAA,wBAAoC,OAAO;CAC3E,IAAI,MAAM,QAAQ,IAAI;CACtB,SAAS;EACR,MAAM,YAAYA,QAAY,KAAK,oBAAoB;EACvD,IAAI,WAAW,SAAS,GAAG,OAAO;EAClC,MAAM,SAASA,QAAY,KAAK,IAAI;EACpC,IAAI,WAAW,KAAK,OAAO;EAC3B,MAAM;CACP;AACD;;;;AAKA,IAAa,sBAAb,cAAyC,KAAK,YAAY,qBAAqB,CAAC,CAK7E,CAAC;AAaJ,MAAM,YACL,oBACA,QAC0B;CAC1B,MAAM,MAAM,IAAI;CAChB,IAAI,QAAQ,QAAQ,OAAO,QAAQ,YAAa,IAA2B,SAAS,SACnF,MAAM,IAAI,oBAAoB;EAC7B,MAAM;EACN,SAAS,aAAa,mBAAmB,mDAAmD,OAAQ,KAA4B,IAAI,EAAE;CACvI,CAAC;CAEF,MAAM,cAAc;CACpB,IAAI;CACJ,IAAI;EACH,SAAS,gBAAgB,WAAW;CACrC,SAAS,OAAO;EACf,MAAM,IAAI,oBAAoB;GAC7B,MAAM;GACN,SAAS,aAAa,mBAAmB,6CAA6C,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GAC3I;EACD,CAAC;CACF;CACA,OAAO;EAAE,OAAO;EAAa;EAAQ;CAAmB;AACzD;;;;;;AAOA,MAAa,sBACZ,eAEA,OAAO,IAAI,aAAa;CACvB,MAAM,MAAM,kBAAkB,UAAU;CACxC,IAAI,QAAQ,MAAM;EACjB,MAAM,YACL,eAAe,KAAA,IACZA,QAAY,QAAQ,IAAI,GAAG,UAAU,IACrCA,QAAY,QAAQ,IAAI,GAAG,mBAAmB;EAClD,OAAO,OAAO,OAAO,KACpB,IAAI,oBAAoB;GACvB,MAAM;GACN,SAAS,gCAAgC;GACzC,eAAe,CAAC,SAAS;EAC1B,CAAC,CACF;CACD;CACA,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC;CAC/B,MAAM,MAAM,OAAO,OAAO,WAAW;EACpC,WAAW,OAAO;EAClB,QAAQ,UACP,IAAI,oBAAoB;GACvB,MAAM;GACN,SAAS,oBAAoB,IAAI,IAAI,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GAC1F;EACD,CAAC;CACH,CAAC;CACD,OAAO,OAAO,OAAO,IAAI;EACxB,WAAW,SAAS,KAAK,GAAG;EAC5B,QAAQ,UACP,iBAAiB,sBACd,QACA,IAAI,oBAAoB;GACxB,MAAM;GACN,SAAS,qBAAqB;GAC9B;EACD,CAAC;CACL,CAAC;AACF,CAAC"}

package/dist/api/mode-narrowed-factory.d.mts

@@ -1,4 +1,4 @@
-import { NetworkConfig, NetworkMode } from "../substrate/network.mjs";
+import { NetworkConfig, NetworkMode } from "../plugins/sui/network-config.mjs";
 
 //#region src/api/mode-narrowed-factory.d.ts
 /** A factories record keyed by network mode. Each branch is an

package/dist/api/mode-narrowed-factory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mode-narrowed-factory.mjs","names":[],"sources":["../../src/api/mode-narrowed-factory.ts"],"sourcesContent":["// Mode-narrowed factory helper.\n//\n// Architecture Tension 11 + type-prototype finding #4: a plugin's\n// factories are exposed as an object indexed by `NetworkMode`. When a\n// stack passes a typed-narrow network through `defineDevstackWith`, the\n// callback receives a namespace whose accessible properties are exactly\n// those present in the network's mode branch. Asking for the wrong\n// branch is a compile error at the call site.\n//\n// Two surfaces:\n//\n//   - `defineModeNamespace({ local, live, fork })` — plugin authors\n//     declare their per-mode factories once; the helper hands back a\n//     callable namespace that does the narrowing.\n\nimport type { NetworkConfig, NetworkMode } from '../substrate/network.ts';\n\n/** A factories record keyed by network mode. Each branch is an\n *  arbitrary record of factory functions. */\nexport type FactoriesByMode<F extends Partial<Record<NetworkMode, unknown>>> = F;\n\n/** Project the factories record to the branch that matches a network's\n *  mode. Branches that aren't present collapse to `never`, which makes\n *  the property access fail at compile time. */\nexport type FactoriesFor<\n\tF extends Partial<Record<NetworkMode, unknown>>,\n\tMode extends NetworkMode,\n> = Mode extends keyof F ? F[Mode] : never;\n\n/**\n * Plugin-author entry point. Pass a per-mode factories record; receive\n * a callable namespace. The returned value type is\n * narrowed to the matching mode branch — illegal-mode property access\n * is a compile error.\n *\n * Two casts here are the boundary between runtime breadth and type-level\n * narrowness (type-prototype results §\"Where I had to use any/casts\"):\n *  - The runtime returns the full factories record.\n *  - The type system projects it down to the matching branch.\n */\nexport type ModeNamespace<F extends Partial<Record<NetworkMode, unknown>>> = <\n\tN extends NetworkConfig,\n>(\n\tnetwork: N,\n) => FactoriesFor<F, N['mode']>;\n\nexport function defineModeNamespace<F extends Partial<Record<NetworkMode, unknown>>>(\n\tfactoriesPerMode: F,\n): ModeNamespace<F> {\n\treturn (<N extends NetworkConfig>(network: N) =>\n\t\tfactoriesPerMode[network.mode as keyof F] as FactoriesFor<F, N['mode']>) as ModeNamespace<F>;\n}\n"],"mappings":";AA8CA,SAAgB,oBACf,kBACmB;AACnB,UAAkC,YACjC,iBAAiB,QAAQ"}
+{"version":3,"file":"mode-narrowed-factory.mjs","names":[],"sources":["../../src/api/mode-narrowed-factory.ts"],"sourcesContent":["// Mode-narrowed factory helper.\n//\n// Architecture Tension 11 + type-prototype finding #4: a plugin's\n// factories are exposed as an object indexed by `NetworkMode`. When a\n// stack passes a typed-narrow network through `defineDevstackWith`, the\n// callback receives a namespace whose accessible properties are exactly\n// those present in the network's mode branch. Asking for the wrong\n// branch is a compile error at the call site.\n//\n// Two surfaces:\n//\n//   - `defineModeNamespace({ local, live, fork })` — plugin authors\n//     declare their per-mode factories once; the helper hands back a\n//     callable namespace that does the narrowing.\n\nimport type { NetworkConfig, NetworkMode } from '../plugins/sui/network-config.ts';\n\n/** A factories record keyed by network mode. Each branch is an\n *  arbitrary record of factory functions. */\nexport type FactoriesByMode<F extends Partial<Record<NetworkMode, unknown>>> = F;\n\n/** Project the factories record to the branch that matches a network's\n *  mode. Branches that aren't present collapse to `never`, which makes\n *  the property access fail at compile time. */\nexport type FactoriesFor<\n\tF extends Partial<Record<NetworkMode, unknown>>,\n\tMode extends NetworkMode,\n> = Mode extends keyof F ? F[Mode] : never;\n\n/**\n * Plugin-author entry point. Pass a per-mode factories record; receive\n * a callable namespace. The returned value type is\n * narrowed to the matching mode branch — illegal-mode property access\n * is a compile error.\n *\n * Two casts here are the boundary between runtime breadth and type-level\n * narrowness (type-prototype results §\"Where I had to use any/casts\"):\n *  - The runtime returns the full factories record.\n *  - The type system projects it down to the matching branch.\n */\nexport type ModeNamespace<F extends Partial<Record<NetworkMode, unknown>>> = <\n\tN extends NetworkConfig,\n>(\n\tnetwork: N,\n) => FactoriesFor<F, N['mode']>;\n\nexport function defineModeNamespace<F extends Partial<Record<NetworkMode, unknown>>>(\n\tfactoriesPerMode: F,\n): ModeNamespace<F> {\n\treturn (<N extends NetworkConfig>(network: N) =>\n\t\tfactoriesPerMode[network.mode as keyof F] as FactoriesFor<F, N['mode']>) as ModeNamespace<F>;\n}\n"],"mappings":";AA8CA,SAAgB,oBACf,kBACmB;CACnB,SAAkC,YACjC,iBAAiB,QAAQ;AAC3B"}

package/dist/api/run-stack-internal.mjs

@@ -0,0 +1,202 @@
+import { readStackEngine } from "./define-devstack.mjs";
+import { appName, stackName } from "../substrate/brand.mjs";
+import { makeProjectionRefSync } from "../substrate/runtime/projection/state-ref.mjs";
+import "../substrate/runtime/index.mjs";
+import { buildSubstrateLayers, layerProductionOrchestrators, resolveProductionCodegenOptions, superviseStackWithProductionBoot } from "../orchestrators/boot.mjs";
+import { resolveAppName, resolveNetworkSync, resolveStackName, resolveStateDir } from "./inference-network.mjs";
+import { Cause, Deferred, Effect, Exit, Fiber, Layer, Logger, Queue, Ref, Stream } from "effect";
+//#region src/api/run-stack-internal.ts
+const resolveIdentity = (stack, opts, cwd) => {
+	const app = resolveAppName({
+		explicit: opts?.app,
+		cwd
+	});
+	const stackNameStr = resolveStackName({
+		explicit: opts?.stack ?? stack.options.stackName,
+		cwd
+	});
+	const resolved = resolveNetworkSync({
+		explicit: opts?.network,
+		env: process.env.DEVSTACK_NETWORK,
+		explicitSource: "runStack({ identity.network })"
+	});
+	return {
+		app: appName(app),
+		stack: stackName(stackNameStr),
+		network: resolved.parsed.name
+	};
+};
+const toBootError = (cause) => ({
+	_tag: "BootError",
+	cause
+});
+/**
+* Allocate every boot-time handle slot in ONE place.
+*
+* SYNC-SAFETY CONTRACT (the reason this is a sync constructor, not an
+* `Effect`): the handle must expose a real `state` / `commands` queue and
+* be subscribable BEFORE `start` forks the supervisor. `Deferred.make`,
+* `Queue.unbounded`, and `Ref.make` are pure sync effects (no side effects,
+* no async), so `Effect.runSync` is safe for all of them. The projection ref
+* goes through the explicit `makeProjectionRefSync` so the sync contract is
+* pinned at the substrate constructor — if `makeProjectionRef` ever picks up
+* an async/Layer wrapper (`withSpan`, annotation), `makeProjectionRefSync`
+* must stay sync-only or this whole allocation must move behind a
+* Deferred-handoff seam.
+*/
+const makeRunHandleSlots = () => ({
+	state: makeProjectionRefSync(),
+	bootDeferred: Effect.runSync(Deferred.make()),
+	stopRequested: Effect.runSync(Deferred.make()),
+	eventQueueRef: Effect.runSync(Deferred.make()),
+	commandQueue: Effect.runSync(Queue.unbounded()),
+	runCommandRef: Effect.runSync(Deferred.make()),
+	fiberRef: Effect.runSync(Deferred.make()),
+	startClaim: Effect.runSync(Ref.make(false)),
+	midRunCauseRef: Effect.runSync(Ref.make(null))
+});
+/** Compose the public handle + the live `SupervisorHandle` into the
+*  `InternalRunHandle` the caller boot hooks receive. The two composed hooks
+*  build it identically; factored here so the closure-soundness note (the
+*  hooks only deref `publicHandle` at boot, after the body assigns it) lives
+*  in one place. */
+const buildInternalHandle = (publicHandle, supervisor) => ({
+	...publicHandle,
+	supervisor
+});
+/**
+* The implementation behind `runStack`. Boots a `Stack` for programmatic
+* embedding and returns a `RunHandle` synchronously; the supervisor fiber
+* is forked on `start`.
+*
+* Lifecycle (identical to `runStack`'s documented contract):
+*
+*   1. `runStackWithBoot(stack, opts)` — synchronous; no fiber forked yet.
+*   2. `await Effect.runPromise(handle.start)` — forks the supervisor,
+*      blocks until every plugin reaches `ready` (or fails with
+*      `BootError`).
+*   3. Use `handle.events` / `handle.state` to observe.
+*   4. `await Effect.runPromise(handle.stop)` — graceful shutdown.
+*   5. `handle.awaitShutdown` resolves once finalizers complete.
+*
+* Internal architecture: the handle stores a `Deferred` for boot
+* completion. The supervised body resolves it from the SUPERVISOR-OWNED
+* readiness signal — `superviseStackEffect`'s `withinScope` hook fires
+* only after `runInitialAcquire` wins its `raceFirst` against
+* `awaitShutdown` (i.e. once `allReadyOrTerminal` — `ready || done` — is
+* true). This is the same `done`-tolerant gate the long-running CLI path
+* uses; it does NOT watch per-node ready-gates (a non-failed terminal
+* `done` node need never resolve its `awaitReady` gate). Initial-acquire
+* failures surface through the supervised body's `catchCause` tee, which
+* fails the deferred with a `BootError`. `start` awaits it.
+*
+* `opts.commandHandler` threads straight into `superviseStackEffect`'s
+* `commandHandler` slot. `opts.boot` injects caller hooks that run AFTER
+* their built-in counterpart (the PR#21 ordering); their failures fold
+* into `BootError` via the same `catchCause` tee, so `start` keeps its
+* `Effect<void, BootError, never>` type.
+*/
+const runStackWithBoot = (stack, opts = {}) => {
+	const engineStack = readStackEngine(stack);
+	const runtimeRoot = resolveStateDir({
+		runtimeRoot: opts.runtimeRoot,
+		stateDir: opts.stateDir ?? engineStack.options.stateDir,
+		env: process.env.DEVSTACK_STATE_DIR,
+		cwd: process.cwd()
+	});
+	const appRoot = opts.appRoot ?? process.cwd();
+	const identity = resolveIdentity(stack, opts.identity, appRoot);
+	const codegen = opts.codegen ?? engineStack.options.codegen;
+	const supervisedStack = {
+		_tag: "Stack",
+		members: engineStack.members,
+		options: engineStack.options
+	};
+	const { state, bootDeferred, stopRequested, eventQueueRef, commandQueue, runCommandRef, fiberRef, startClaim, midRunCauseRef } = makeRunHandleSlots();
+	const substrate = layerProductionOrchestrators({ codegen: resolveProductionCodegenOptions({
+		appRoot,
+		effectiveStack: String(identity.stack),
+		codegen
+	}) }).pipe(Layer.provideMerge(buildSubstrateLayers(identity, runtimeRoot)));
+	const runCommand = (command) => Effect.flatMap(Deferred.await(runCommandRef), (dispatch) => dispatch(command));
+	const events = Stream.unwrap(Effect.gen(function* () {
+		const queue = yield* Deferred.await(eventQueueRef);
+		return Stream.fromQueue(queue);
+	}));
+	let publicHandle;
+	const supervised = Effect.gen(function* () {
+		const commandHandler = opts.commandHandler === void 0 ? void 0 : yield* opts.commandHandler;
+		yield* superviseStackWithProductionBoot(supervisedStack, identity, state, {
+			extras: stack.options.extras,
+			networkOptions: stack.options.networkOptions,
+			...opts.boot?.devstackVersion === void 0 ? {} : { devstackVersion: opts.boot.devstackVersion },
+			...commandHandler === void 0 ? {} : { commandHandler },
+			...opts.extendContext === void 0 ? {} : { extendContextAfterBuiltIn: opts.extendContext },
+			beforeInitialAcquire: (handle) => Effect.gen(function* () {
+				yield* Deferred.succeed(eventQueueRef, handle.events).pipe(Effect.catch(() => Effect.void));
+				yield* Deferred.succeed(runCommandRef, handle.runCommand).pipe(Effect.catch(() => Effect.void));
+				yield* Effect.forkScoped(Effect.gen(function* () {
+					while (true) {
+						const command = yield* Queue.take(commandQueue);
+						yield* Queue.offer(handle.commands, command);
+					}
+				}));
+				yield* Effect.forkScoped(Effect.gen(function* () {
+					yield* Deferred.await(stopRequested);
+					yield* Queue.offer(handle.commands, { tag: "shutdown.requested" });
+				}));
+				if (opts.boot?.beforeInitialAcquire !== void 0) yield* opts.boot.beforeInitialAcquire(buildInternalHandle(publicHandle, handle));
+			}),
+			withinScope: (handle) => Effect.gen(function* () {
+				let firstFailure = null;
+				for (const [key] of handle.graph.nodes) if ((yield* handle.registry.getStatus(key).pipe(Effect.catch(() => Effect.succeed("failed")))) === "failed") {
+					const failureExit = yield* Effect.exit(handle.registry.awaitReady(key));
+					firstFailure = toBootError(Exit.isFailure(failureExit) ? failureExit.cause : Cause.empty);
+					break;
+				}
+				if (firstFailure === null) yield* Deferred.succeed(bootDeferred, void 0).pipe(Effect.asVoid);
+				else yield* Deferred.fail(bootDeferred, firstFailure).pipe(Effect.asVoid);
+				if (opts.boot?.withinScope !== void 0) yield* opts.boot.withinScope(buildInternalHandle(publicHandle, handle));
+			})
+		});
+	});
+	const loggerLayer = Logger.layer([]);
+	const supervisedProgram = supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer)).pipe(Effect.catchCause((cause) => Effect.gen(function* () {
+		const bootAlreadyCompleted = yield* Deferred.isDone(bootDeferred);
+		yield* Deferred.fail(bootDeferred, toBootError(cause)).pipe(Effect.asVoid, Effect.catch(() => Effect.void));
+		if (bootAlreadyCompleted) yield* Ref.set(midRunCauseRef, cause);
+		yield* Effect.logError(`devstack runStack: supervisor died\n${Cause.pretty(cause)}`);
+	})));
+	publicHandle = {
+		start: Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+			if (yield* Ref.modify(startClaim, (started) => started ? [false, true] : [true, true])) {
+				const fiber = yield* Effect.forkDetach(supervisedProgram);
+				yield* Deferred.succeed(fiberRef, fiber);
+			}
+			yield* restore(Deferred.await(bootDeferred));
+		})),
+		stop: Effect.gen(function* () {
+			yield* Deferred.succeed(stopRequested, void 0).pipe(Effect.catch(() => Effect.void));
+			if (!(yield* Deferred.isDone(fiberRef))) return;
+			const fiber = yield* Deferred.await(fiberRef);
+			yield* Fiber.await(fiber);
+		}),
+		awaitShutdown: Effect.gen(function* () {
+			if (!(yield* Deferred.isDone(fiberRef))) return;
+			const fiber = yield* Deferred.await(fiberRef);
+			yield* Fiber.await(fiber);
+			const midRunCause = yield* Ref.get(midRunCauseRef);
+			if (midRunCause !== null) return yield* Effect.failCause(midRunCause);
+		}),
+		events,
+		state,
+		commands: commandQueue,
+		runCommand,
+		identity
+	};
+	return publicHandle;
+};
+//#endregion
+export { runStackWithBoot };
+
+//# sourceMappingURL=run-stack-internal.mjs.map

package/dist/api/run-stack-internal.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-stack-internal.mjs","names":[],"sources":["../../src/api/run-stack-internal.ts"],"sourcesContent":["// `runStackWithBoot(stack, optsWithBoot)` — the NON-PUBLIC seam under\n// `runStack`.\n//\n// `api/run-stack.ts` is the thin PUBLIC facade: `runStack` delegates here\n// with a zero-`boot` bag, so the public surface (`RunHandle`,\n// `RunStackOptions`, `BootError`) and the zero-`boot` path stay\n// byte-identical. This module owns the supervised-body construction and\n// the caller-injectable boot hook seam the CLI `up` verb routes through.\n//\n// Why a seam at all: the CLI `up` verb needs the SAME substrate Layer\n// composition + supervised body `runStack` builds, but wrapped with extra\n// `beforeInitialAcquire`/`withinScope` work (interrupted-restore recovery,\n// the roster lock, the command-channel IPC bridge, and the TUI surface).\n// `runStackWithBoot` threads those as CALLER-INJECTED hooks so\n// the CLI consumes ONE boot core instead of forking it. Because the bag is\n// non-public, its hooks receive an `InternalRunHandle` that additionally\n// carries the live `SupervisorHandle` (the seam the CLI hooks drain) —\n// substrate detail that NEVER reaches the public `RunHandle`.\n//\n// PR#21 boot-ordering invariant (do not reorder): the composed hooks run\n// the BUILT-IN work FIRST, then the caller's. For `beforeInitialAcquire`\n// this means the event-queue handoff + stop-bridge + command-pump are armed\n// before any caller hook runs (so a `stop()` during a caller hook always\n// has a bridge) AND before the first acquire (`superviseStackEffect` runs\n// the whole composed `beforeInitialAcquire` ahead of `runInitialAcquire`).\n// For `withinScope` the built-in readiness-gate resolution (the status\n// scan that resolves `bootDeferred`) runs first, so a caller `withinScope`\n// can never delay `handle.start`.\n\nimport {\n\tCause,\n\tDeferred,\n\tEffect,\n\tExit,\n\tFiber,\n\ttype FileSystem,\n\tLayer,\n\tLogger,\n\tQueue,\n\tRef,\n\ttype Scope,\n\tStream,\n\ttype SubscriptionRef,\n} from 'effect';\n\nimport { appName, stackName } from '../substrate/brand.ts';\nimport type { Identity } from '../substrate/identity.ts';\nimport type { EngineCommand, EngineEvent } from '../substrate/events.ts';\nimport { makeProjectionRefSync } from '../substrate/runtime/index.ts';\nimport type { StackPathsService } from '../substrate/runtime/paths.ts';\nimport type { SnapshotOrchestratorService } from '../orchestrators/snapshot/index.ts';\nimport type {\n\tSupervisorCommandHandler,\n\tSupervisorHandle,\n} from '../substrate/runtime/supervisor/index.ts';\nimport {\n\tbuildSubstrateLayers,\n\tlayerProductionOrchestrators,\n\tresolveProductionCodegenOptions,\n\tsuperviseStackWithProductionBoot,\n} from '../orchestrators/boot.ts';\nimport { readStackEngine, type Stack } from './define-devstack.ts';\nimport type { AnyPlugin } from '../substrate/plugin.ts';\nimport {\n\tresolveAppName,\n\tresolveNetworkSync,\n\tresolveStackName,\n\tresolveStateDir,\n} from './inference-network.ts';\nimport type {\n\tBootError,\n\tRunHandle,\n\tRunStackIdentityOptions,\n\tRunStackOptions,\n} from './run-stack.ts';\n\n// -----------------------------------------------------------------------------\n// Internal handle + boot bag\n// -----------------------------------------------------------------------------\n\n/** The handle the caller-injected `boot` hooks receive. It is the public\n *  `RunHandle` PLUS the live `SupervisorHandle` — the substrate seam the\n *  CLI `up` hooks drain (roster lock keys off it, the IPC bridge tails\n *  `supervisor.events` / pumps `supervisor.commands`, the TUI mounts\n *  `supervisor.state`). NON-PUBLIC: `index.ts` never re-exports it, so the\n *  `SupervisorHandle` substrate type stays off the public surface. */\nexport interface InternalRunHandle extends RunHandle {\n\t/** The live supervisor handle for this boot. Available inside both\n\t *  composed hooks; carries `events`/`commands`/`runCommand`/`state`/\n\t *  `graph`/`registry` the CLI hooks consume directly. */\n\treadonly supervisor: SupervisorHandle;\n}\n\n/** The substrate services the seam already has in scope when it runs the\n *  caller hooks (the composed `beforeInitialAcquire`/`withinScope` run\n *  inside `superviseStackEffect`, which is `Effect.provide(substrate)`).\n *  The bag hooks may yield these directly — the CLI `up` hooks drive the\n *  ONE `SnapshotOrchestratorService` instance the supervisor's contribution\n *  dispatcher registers participants on (so an operator `snapshot save`\n *  captures the LIVE participant set, not an empty one off a sibling\n *  orchestrator), plus `FileSystem`/`StackPathsService` for the\n *  interrupted-restore + roster paths. `Scope.Scope` lets a hook fork\n *  scoped fibers (the IPC pump, the TUI mount) onto the supervised scope.\n *  NON-PUBLIC: like `InternalRunHandle`, this never reaches the public\n *  `runStack` facade. */\nexport type BootHookServices =\n\t| Scope.Scope\n\t| SnapshotOrchestratorService\n\t| FileSystem.FileSystem\n\t| StackPathsService;\n\n/** Caller-injected boot hooks. Both run AFTER their built-in counterpart\n *  (see the PR#21 ordering note at the top of this file). Their failures\n *  fold into `BootError.cause` via the same `catchCause` tee the built-in\n *  work uses, so `handle.start` stays `Effect<void, BootError, never>` —\n *  the bag does NOT widen the public error channel. The R-channel is\n *  `BootHookServices` (substrate services the seam already provides), NOT\n *  `never`: the hooks run inside the supervised scope and may drive the\n *  seam's live substrate (notably the supervisor's snapshot orchestrator). */\nexport interface RunStackBootBag {\n\treadonly devstackVersion?: string;\n\treadonly beforeInitialAcquire?: (\n\t\thandle: InternalRunHandle,\n\t) => Effect.Effect<void, unknown, BootHookServices>;\n\treadonly withinScope?: (\n\t\thandle: InternalRunHandle,\n\t) => Effect.Effect<void, unknown, BootHookServices>;\n}\n\n/** The substrate services a {@link CommandHandlerFactory} may yield — the\n *  same singletons the contribution dispatcher + boot hooks see, minus\n *  `Scope.Scope` (the factory runs before the supervised scope opens, so it\n *  forks nothing). A handler closes over `SnapshotOrchestratorService` to\n *  capture the LIVE participant set and `FileSystem` to thread it into the\n *  snapshot I/O. */\ntype CommandHandlerServices =\n\t| SnapshotOrchestratorService\n\t| FileSystem.FileSystem\n\t| StackPathsService;\n\n/** A FACTORY for the supervisor command handler. The seam runs it ONCE,\n *  inside the supervised body (so `CommandHandlerServices` — notably the live\n *  `SnapshotOrchestratorService` + `FileSystem` — are in scope), BEFORE it\n *  hands `startSupervisor` the resolved handler. So the resulting handler\n *  (whose own R-channel is `never`, as the supervisor command loop requires)\n *  closes over the seam's REAL substrate instances directly — no Deferred\n *  hand-off. Resolving the snapshot orchestrator here yields the SAME\n *  instance the contribution dispatcher registers live participants on, so an\n *  operator `snapshot save` captures the LIVE chain/blob/db state, not an\n *  empty set off a sibling orchestrator. */\nexport type CommandHandlerFactory = Effect.Effect<\n\tSupervisorCommandHandler,\n\tnever,\n\tCommandHandlerServices\n>;\n\n/** `RunStackOptions` plus the non-public injection points. `commandHandler`\n *  is a FACTORY the seam resolves against its live substrate (see\n *  {@link CommandHandlerFactory}); `boot` carries the caller-injected hooks. */\nexport interface RunStackOptionsWithBoot extends RunStackOptions {\n\treadonly commandHandler?: CommandHandlerFactory;\n\treadonly boot?: RunStackBootBag;\n}\n\n// -----------------------------------------------------------------------------\n// Identity resolution\n// -----------------------------------------------------------------------------\n\nconst resolveIdentity = (\n\tstack: Stack<ReadonlyArray<AnyPlugin>>,\n\topts: RunStackIdentityOptions | undefined,\n\tcwd: string,\n): Identity => {\n\tconst app = resolveAppName({\n\t\texplicit: opts?.app,\n\t\tcwd,\n\t});\n\tconst stackNameStr = resolveStackName({\n\t\texplicit: opts?.stack ?? stack.options.stackName,\n\t\tcwd,\n\t});\n\t// Parse + validate up-front so a malformed value fails here rather\n\t// than downstream when a plugin probes the network. The identity's\n\t// network is the canonical name (`localnet`, `testnet`, …) — never the\n\t// `sui:`-prefixed wallet-standard form, which devstack does not use\n\t// internally — so plugin checks and on-disk cache namespaces key on one\n\t// stable name regardless of how it was spelled on the CLI.\n\tconst resolved = resolveNetworkSync({\n\t\texplicit: opts?.network,\n\t\tenv: process.env.DEVSTACK_NETWORK,\n\t\texplicitSource: 'runStack({ identity.network })',\n\t});\n\treturn {\n\t\tapp: appName(app),\n\t\tstack: stackName(stackNameStr),\n\t\tnetwork: resolved.parsed.name,\n\t};\n};\n\nconst toBootError = (cause: Cause.Cause<unknown>): BootError => ({\n\t_tag: 'BootError',\n\tcause,\n});\n\n// -----------------------------------------------------------------------------\n// Boot-time handle slots\n// -----------------------------------------------------------------------------\n\n/** The mutable cells + ref the handle's lifecycle effects close over. Every\n *  field is allocated SYNCHRONOUSLY in `makeRunHandleSlots` (see its\n *  sync-safety contract) so the public handle can expose a live `state` /\n *  `commands` queue and let callers subscribe to `state.changes` BEFORE\n *  `start` ever forks the supervisor fiber. */\ninterface RunHandleSlots {\n\t/** The supervisor's live projection. Seeded sync; populated by the\n\t *  supervised body once it boots. */\n\treadonly state: SubscriptionRef.SubscriptionRef<\n\t\timport('../substrate/projection.ts').SubscribableState\n\t>;\n\t/** Resolved (or failed with `BootError`) by the readiness gate; `start`\n\t *  awaits it. */\n\treadonly bootDeferred: Deferred.Deferred<void, BootError>;\n\t/** Set by `stop`; the built-in stop-bridge awaits it and offers\n\t *  `shutdown.requested` onto the supervisor's command channel. */\n\treadonly stopRequested: Deferred.Deferred<void>;\n\t/** Handed the supervisor's event dequeue by `beforeInitialAcquire`; the\n\t *  public `events` stream unwraps it. */\n\treadonly eventQueueRef: Deferred.Deferred<Queue.Dequeue<EngineEvent>>;\n\t/** Public command channel, pumped onto the supervisor's own queue once it\n\t *  boots — the TUI/IPC publish target. */\n\treadonly commandQueue: Queue.Queue<EngineCommand>;\n\t/** Handed the supervisor's submit-and-await dispatch by\n\t *  `beforeInitialAcquire`; the public `runCommand` awaits it. */\n\treadonly runCommandRef: Deferred.Deferred<\n\t\t(command: EngineCommand) => Effect.Effect<void, unknown, never>\n\t>;\n\t/** Holds the forked supervisor fiber; `stop`/`awaitShutdown` await it. */\n\treadonly fiberRef: Deferred.Deferred<Fiber.Fiber<void, never>>;\n\t/** Single-fire guard so a second `start` is a no-op. */\n\treadonly startClaim: Ref.Ref<boolean>;\n\t/** Tee for a mid-run defect/failure raised AFTER boot completed, so\n\t *  `awaitShutdown` can re-surface it (a post-boot `Deferred.fail` is a\n\t *  no-op). */\n\treadonly midRunCauseRef: Ref.Ref<Cause.Cause<unknown> | null>;\n}\n\n/**\n * Allocate every boot-time handle slot in ONE place.\n *\n * SYNC-SAFETY CONTRACT (the reason this is a sync constructor, not an\n * `Effect`): the handle must expose a real `state` / `commands` queue and\n * be subscribable BEFORE `start` forks the supervisor. `Deferred.make`,\n * `Queue.unbounded`, and `Ref.make` are pure sync effects (no side effects,\n * no async), so `Effect.runSync` is safe for all of them. The projection ref\n * goes through the explicit `makeProjectionRefSync` so the sync contract is\n * pinned at the substrate constructor — if `makeProjectionRef` ever picks up\n * an async/Layer wrapper (`withSpan`, annotation), `makeProjectionRefSync`\n * must stay sync-only or this whole allocation must move behind a\n * Deferred-handoff seam.\n */\nconst makeRunHandleSlots = (): RunHandleSlots => ({\n\tstate: makeProjectionRefSync(),\n\tbootDeferred: Effect.runSync(Deferred.make<void, BootError>()),\n\tstopRequested: Effect.runSync(Deferred.make<void>()),\n\teventQueueRef: Effect.runSync(Deferred.make<Queue.Dequeue<EngineEvent>>()),\n\tcommandQueue: Effect.runSync(Queue.unbounded<EngineCommand>()),\n\trunCommandRef: Effect.runSync(\n\t\tDeferred.make<(command: EngineCommand) => Effect.Effect<void, unknown, never>>(),\n\t),\n\tfiberRef: Effect.runSync(Deferred.make<Fiber.Fiber<void, never>>()),\n\tstartClaim: Effect.runSync(Ref.make(false)),\n\tmidRunCauseRef: Effect.runSync(Ref.make<Cause.Cause<unknown> | null>(null)),\n});\n\n/** Compose the public handle + the live `SupervisorHandle` into the\n *  `InternalRunHandle` the caller boot hooks receive. The two composed hooks\n *  build it identically; factored here so the closure-soundness note (the\n *  hooks only deref `publicHandle` at boot, after the body assigns it) lives\n *  in one place. */\nconst buildInternalHandle = (\n\tpublicHandle: RunHandle,\n\tsupervisor: SupervisorHandle,\n): InternalRunHandle => ({ ...publicHandle, supervisor });\n\n// -----------------------------------------------------------------------------\n// runStackWithBoot\n// -----------------------------------------------------------------------------\n\n/**\n * The implementation behind `runStack`. Boots a `Stack` for programmatic\n * embedding and returns a `RunHandle` synchronously; the supervisor fiber\n * is forked on `start`.\n *\n * Lifecycle (identical to `runStack`'s documented contract):\n *\n *   1. `runStackWithBoot(stack, opts)` — synchronous; no fiber forked yet.\n *   2. `await Effect.runPromise(handle.start)` — forks the supervisor,\n *      blocks until every plugin reaches `ready` (or fails with\n *      `BootError`).\n *   3. Use `handle.events` / `handle.state` to observe.\n *   4. `await Effect.runPromise(handle.stop)` — graceful shutdown.\n *   5. `handle.awaitShutdown` resolves once finalizers complete.\n *\n * Internal architecture: the handle stores a `Deferred` for boot\n * completion. The supervised body resolves it from the SUPERVISOR-OWNED\n * readiness signal — `superviseStackEffect`'s `withinScope` hook fires\n * only after `runInitialAcquire` wins its `raceFirst` against\n * `awaitShutdown` (i.e. once `allReadyOrTerminal` — `ready || done` — is\n * true). This is the same `done`-tolerant gate the long-running CLI path\n * uses; it does NOT watch per-node ready-gates (a non-failed terminal\n * `done` node need never resolve its `awaitReady` gate). Initial-acquire\n * failures surface through the supervised body's `catchCause` tee, which\n * fails the deferred with a `BootError`. `start` awaits it.\n *\n * `opts.commandHandler` threads straight into `superviseStackEffect`'s\n * `commandHandler` slot. `opts.boot` injects caller hooks that run AFTER\n * their built-in counterpart (the PR#21 ordering); their failures fold\n * into `BootError` via the same `catchCause` tee, so `start` keeps its\n * `Effect<void, BootError, never>` type.\n */\nexport const runStackWithBoot = (\n\tstack: Stack<ReadonlyArray<AnyPlugin>>,\n\topts: RunStackOptionsWithBoot = {},\n): RunHandle => {\n\tconst engineStack = readStackEngine(stack);\n\tconst runtimeRoot = resolveStateDir({\n\t\truntimeRoot: opts.runtimeRoot,\n\t\tstateDir: opts.stateDir ?? engineStack.options.stateDir,\n\t\tenv: process.env.DEVSTACK_STATE_DIR,\n\t\tcwd: process.cwd(),\n\t});\n\tconst appRoot = opts.appRoot ?? process.cwd();\n\tconst identity = resolveIdentity(stack, opts.identity, appRoot);\n\tconst codegen = opts.codegen ?? engineStack.options.codegen;\n\n\tconst supervisedStack = {\n\t\t_tag: 'Stack' as const,\n\t\tmembers: engineStack.members,\n\t\toptions: engineStack.options,\n\t};\n\n\t// Every boot-time handle slot is allocated in ONE place (the sync-safety\n\t// contract lives on `makeRunHandleSlots`): the handle must expose a live\n\t// `state` / `commands` queue and be subscribable BEFORE `start` forks the\n\t// supervisor fiber.\n\tconst {\n\t\tstate,\n\t\tbootDeferred,\n\t\tstopRequested,\n\t\teventQueueRef,\n\t\tcommandQueue,\n\t\trunCommandRef,\n\t\tfiberRef,\n\t\tstartClaim,\n\t\tmidRunCauseRef,\n\t} = makeRunHandleSlots();\n\n\t// Resolve the per-stack LIVE codegen output location through the ONE\n\t// shared boot seam: EVERY live run emits into\n\t// `.devstack/stacks/<stack>/generated/` (gitignored), so the id-bearing\n\t// tree never lands in committed source. The committed `src/generated`\n\t// tree is owned solely by the stack-free `codegen` verb. An explicit\n\t// `opts.codegen` (or the stack's own `codegen`) is honored verbatim by\n\t// the resolver. The effective stack (the resolved `identity.stack`) is\n\t// in scope here, exactly as in the CLI's `buildVerbLayers` seam — both\n\t// route through `resolveProductionCodegenOptions`.\n\tconst substrate = layerProductionOrchestrators({\n\t\tcodegen: resolveProductionCodegenOptions({\n\t\t\tappRoot,\n\t\t\teffectiveStack: String(identity.stack),\n\t\t\tcodegen,\n\t\t}),\n\t}).pipe(Layer.provideMerge(buildSubstrateLayers(identity, runtimeRoot)));\n\n\t// The submit-and-await dispatch surfaced on the public handle. Awaits\n\t// the supervisor's `runCommand` (wired in the built-in\n\t// `beforeInitialAcquire`), then delegates.\n\tconst runCommand = (command: EngineCommand): Effect.Effect<void, unknown, never> =>\n\t\tEffect.flatMap(Deferred.await(runCommandRef), (dispatch) => dispatch(command));\n\n\tconst events: Stream.Stream<EngineEvent, never, never> = Stream.unwrap(\n\t\tEffect.gen(function* () {\n\t\t\tconst queue = yield* Deferred.await(eventQueueRef);\n\t\t\treturn Stream.fromQueue(queue);\n\t\t}),\n\t);\n\n\t// The PUBLIC handle is assigned exactly once at the end of this body\n\t// (after the lifecycle effects exist) and returned. The composed boot\n\t// hooks below close over `publicHandle` to build an `InternalRunHandle`\n\t// (the public handle + the live `SupervisorHandle`), but they only\n\t// deref it at BOOT time — long after this synchronous body finishes and\n\t// assigns it — so the closure is sound. Declared with a forward `let`\n\t// rather than mutated readonly fields so `RunHandle` stays immutable.\n\tlet publicHandle: RunHandle;\n\n\tconst supervised = Effect.gen(function* () {\n\t\t// Resolve the command-handler FACTORY against the seam's live\n\t\t// substrate (in scope here via `Effect.provide(substrate)` below)\n\t\t// BEFORE `startSupervisor` consumes the handler. The factory closes\n\t\t// over the same `SnapshotOrchestratorService` the contribution\n\t\t// dispatcher registers participants on, so the resulting handler\n\t\t// (R = `never`, as the command loop requires) drives the LIVE state.\n\t\tconst commandHandler =\n\t\t\topts.commandHandler === undefined ? undefined : yield* opts.commandHandler;\n\t\t// The shared production-boot assembly (contribution dispatcher +\n\t\t// post-acquire hook + built-in plugin-context extension, then\n\t\t// `layerBuiltInPluginRuntime`) lives in ONE place\n\t\t// (`orchestrators/boot.ts superviseStackWithProductionBoot`). This\n\t\t// seam supplies only the LONG-RUNNING-specific wrapping: the\n\t\t// resolved command handler, the public `runStack({ extendContext })`\n\t\t// chained after the built-in, and the composed boot hooks below.\n\t\tyield* superviseStackWithProductionBoot(supervisedStack, identity, state, {\n\t\t\textras: stack.options.extras,\n\t\t\tnetworkOptions: stack.options.networkOptions,\n\t\t\t...(opts.boot?.devstackVersion === undefined\n\t\t\t\t? {}\n\t\t\t\t: { devstackVersion: opts.boot.devstackVersion }),\n\t\t\t...(commandHandler === undefined ? {} : { commandHandler }),\n\t\t\t...(opts.extendContext === undefined\n\t\t\t\t? {}\n\t\t\t\t: { extendContextAfterBuiltIn: opts.extendContext }),\n\t\t\t// ── COMPOSED `beforeInitialAcquire` (ONE ordered gen) ──────────\n\t\t\t// ORDER (PR#21-load-bearing): BUILT-IN work first, THEN caller.\n\t\t\t//   1. built-in: event-queue handoff + runCommand surface +\n\t\t\t//      command-pump fork + stop-bridge fork.\n\t\t\t//   2. caller: `opts.boot?.beforeInitialAcquire(...)`.\n\t\t\t// `superviseStackEffect` runs this whole composed effect BEFORE\n\t\t\t// `runInitialAcquire`, so the caller hook (the CLI's recover/\n\t\t\t// roster/IPC/TUI bundle) runs before first acquire too; and because\n\t\t\t// the built-in stop-bridge is armed first, a `stop()` raised during\n\t\t\t// a caller hook always has a command bridge.\n\t\t\tbeforeInitialAcquire: (handle) =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tyield* Deferred.succeed(eventQueueRef, handle.events).pipe(\n\t\t\t\t\t\tEffect.catch(() => Effect.void),\n\t\t\t\t\t);\n\t\t\t\t\t// Surface the supervisor's submit-and-await dispatch onto the\n\t\t\t\t\t// public handle BEFORE acquire so a boot failure can't leave\n\t\t\t\t\t// the handle without a command bridge.\n\t\t\t\t\tyield* Deferred.succeed(runCommandRef, handle.runCommand).pipe(\n\t\t\t\t\t\tEffect.catch(() => Effect.void),\n\t\t\t\t\t);\n\t\t\t\t\t// Pump the eager public command queue onto the supervisor's\n\t\t\t\t\t// own command queue (`handle.commands` — the seam the signal\n\t\t\t\t\t// handler + command loop drain). A publish on the public\n\t\t\t\t\t// queue therefore always reaches the supervisor's drain.\n\t\t\t\t\tyield* Effect.forkScoped(\n\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\twhile (true) {\n\t\t\t\t\t\t\t\tconst command = yield* Queue.take(commandQueue);\n\t\t\t\t\t\t\t\tyield* Queue.offer(handle.commands, command);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\n\t\t\t\t\t// Bridge `stop` requests onto the supervisor's command\n\t\t\t\t\t// channel before acquire starts so a boot failure cannot\n\t\t\t\t\t// leave the public handle without an event/command bridge.\n\t\t\t\t\tyield* Effect.forkScoped(\n\t\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\t\tyield* Deferred.await(stopRequested);\n\t\t\t\t\t\t\tyield* Queue.offer(handle.commands, {\n\t\t\t\t\t\t\t\ttag: 'shutdown.requested',\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\n\t\t\t\t\t// Caller-injected work runs AFTER the built-in bridges are\n\t\t\t\t\t// armed. Its failures fold into the supervised body's\n\t\t\t\t\t// `catchCause` below (and thence into `BootError`).\n\t\t\t\t\tif (opts.boot?.beforeInitialAcquire !== undefined) {\n\t\t\t\t\t\tyield* opts.boot.beforeInitialAcquire(buildInternalHandle(publicHandle, handle));\n\t\t\t\t\t}\n\t\t\t\t}),\n\t\t\t// ── COMPOSED `withinScope` (ONE ordered gen) ───────────────────\n\t\t\t// ORDER: BUILT-IN readiness-gate resolution first, THEN caller.\n\t\t\t//   1. built-in: the status scan that resolves `bootDeferred`.\n\t\t\t//   2. caller: `opts.boot?.withinScope(...)`.\n\t\t\t// Resolving the gate first means a caller `withinScope` can never\n\t\t\t// delay `handle.start`.\n\t\t\twithinScope: (handle) =>\n\t\t\t\t// Resolve the boot gate from the SUPERVISOR-OWNED readiness\n\t\t\t\t// signal. `superviseStackEffect` only calls `withinScope`\n\t\t\t\t// after `runInitialAcquire` wins its `raceFirst` against\n\t\t\t\t// `awaitShutdown` and yields `'booted'` (boot.ts) — i.e. once\n\t\t\t\t// `allReadyOrTerminal` is true (`ready || done`). This is the\n\t\t\t\t// SAME `done`-tolerant gate the long-running CLI path uses,\n\t\t\t\t// not a per-node `awaitReady` watcher (whose ready-gate a\n\t\t\t\t// non-failed terminal `done` node need never resolve, so it\n\t\t\t\t// would hang here).\n\t\t\t\t//\n\t\t\t\t// `runInitialAcquire` does NOT itself fail on a per-PLUGIN\n\t\t\t\t// acquire failure: `acquireFullGraph` swallows node failures\n\t\t\t\t// into the registry's `failed` status (the CLI surfaces them as\n\t\t\t\t// red TUI rows and keeps the stack up). runStack's contract is\n\t\t\t\t// stricter — `start` FAILS with `BootError` if any node failed\n\t\t\t\t// initial acquire. So gate on the STATUS contract here: succeed\n\t\t\t\t// iff every node is `ready`/`done`, else fail with the first\n\t\t\t\t// `failed` node's `PluginAcquireFailed` cause. A failed node's\n\t\t\t\t// ready-gate IS resolved (markFailed failed it), so reading it\n\t\t\t\t// is hang-free — the `done`-tolerant equivalent of the old\n\t\t\t\t// watcher's failure detection. (Post-acquire HOOK failures —\n\t\t\t\t// codegen / manifest — fail `runInitialAcquire` directly and\n\t\t\t\t// tee through the supervised body's `catchCause` below; we\n\t\t\t\t// never reach here on that path.)\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tlet firstFailure: BootError | null = null;\n\t\t\t\t\tfor (const [key] of handle.graph.nodes) {\n\t\t\t\t\t\tconst status = yield* handle.registry\n\t\t\t\t\t\t\t.getStatus(key)\n\t\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed('failed' as const)));\n\t\t\t\t\t\tif (status === 'failed') {\n\t\t\t\t\t\t\tconst failureExit = yield* Effect.exit(handle.registry.awaitReady(key));\n\t\t\t\t\t\t\tfirstFailure = toBootError(\n\t\t\t\t\t\t\t\tExit.isFailure(failureExit) ? failureExit.cause : Cause.empty,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tbreak;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\tif (firstFailure === null) {\n\t\t\t\t\t\tyield* Deferred.succeed(bootDeferred, undefined).pipe(Effect.asVoid);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tyield* Deferred.fail(bootDeferred, firstFailure).pipe(Effect.asVoid);\n\t\t\t\t\t}\n\n\t\t\t\t\t// Caller-injected work runs AFTER the boot gate is resolved,\n\t\t\t\t\t// so it can never delay `handle.start`. Its failures fold\n\t\t\t\t\t// into the supervised body's `catchCause` below; since the\n\t\t\t\t\t// boot gate already succeeded by this point, such a failure\n\t\t\t\t\t// surfaces on `awaitShutdown` (mid-run), not `start` — the\n\t\t\t\t\t// same place a built-in `withinScope` failure would land.\n\t\t\t\t\tif (opts.boot?.withinScope !== undefined) {\n\t\t\t\t\t\tyield* opts.boot.withinScope(buildInternalHandle(publicHandle, handle));\n\t\t\t\t\t}\n\t\t\t\t}),\n\t\t});\n\t});\n\n\tconst loggerLayer = Logger.layer([]);\n\tconst layered = supervised.pipe(Effect.provide(substrate), Effect.provide(loggerLayer));\n\n\t// Convert any uncaught cause into a boot failure if the deferred\n\t// hasn't completed. If `bootDeferred` HAS already succeeded then\n\t// `Deferred.fail` is a no-op — the cause is a mid-run failure\n\t// (e.g. a plugin scope finalizer defect) and would otherwise be\n\t// silently dropped: the fiber exits `Success(void)` and\n\t// `awaitShutdown` resolves clean. Tee the cause into\n\t// `midRunCauseRef` so `awaitShutdown` can re-surface it, AND emit\n\t// `Effect.logError(Cause.pretty(cause))` so observability stays\n\t// loud regardless of whether anyone awaits. Boot failures (still in\n\t// the bootDeferred-pending window) only surface via `start`, not\n\t// here — we'd otherwise re-raise them on `awaitShutdown` after\n\t// `start` already rejected. NOTE: a CALLER `boot` hook failure folds\n\t// through this SAME tee, so its failure surfaces as `BootError` on\n\t// `start` (when raised before the gate resolves) or re-raises on\n\t// `awaitShutdown` (after) — never widening `start`'s error channel.\n\tconst supervisedProgram: Effect.Effect<void, never, never> = layered.pipe(\n\t\tEffect.catchCause((cause) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst bootAlreadyCompleted = yield* Deferred.isDone(bootDeferred);\n\t\t\t\tyield* Deferred.fail(bootDeferred, toBootError(cause)).pipe(\n\t\t\t\t\tEffect.asVoid,\n\t\t\t\t\tEffect.catch(() => Effect.void),\n\t\t\t\t);\n\t\t\t\tif (bootAlreadyCompleted) {\n\t\t\t\t\tyield* Ref.set(midRunCauseRef, cause);\n\t\t\t\t}\n\t\t\t\tyield* Effect.logError(`devstack runStack: supervisor died\\n${Cause.pretty(cause)}`);\n\t\t\t}),\n\t\t),\n\t);\n\n\tconst start: Effect.Effect<void, BootError, never> = Effect.uninterruptibleMask((restore) =>\n\t\tEffect.gen(function* () {\n\t\t\tconst shouldStart = yield* Ref.modify(startClaim, (started) =>\n\t\t\t\tstarted ? [false, true] : [true, true],\n\t\t\t);\n\t\t\tif (shouldStart) {\n\t\t\t\t// `forkDetach` decouples the supervisor fiber from the `start`\n\t\t\t\t// fiber's scope. `forkChild`\n\t\t\t\t// would tie the supervisor to whatever fiber runs `start`, and\n\t\t\t\t// once `start` resolves (after `bootDeferred` succeeds) the\n\t\t\t\t// runtime would interrupt the supervisor — transitioning every\n\t\t\t\t// plugin `ready → stopping → stopped` before the caller can\n\t\t\t\t// read post-ready state or call `handle.stop`. The handle's\n\t\t\t\t// explicit `stop` + `awaitShutdown` paths are the only\n\t\t\t\t// shutdown signals; the captured `Fiber` reference is how the\n\t\t\t\t// daemon stays releasable.\n\t\t\t\tconst fiber = yield* Effect.forkDetach(supervisedProgram);\n\t\t\t\tyield* Deferred.succeed(fiberRef, fiber);\n\t\t\t}\n\t\t\tyield* restore(Deferred.await(bootDeferred));\n\t\t}),\n\t);\n\n\tconst stop: Effect.Effect<void, never, never> = Effect.gen(function* () {\n\t\tyield* Deferred.succeed(stopRequested, undefined).pipe(Effect.catch(() => Effect.void));\n\t\tconst alreadyStarted = yield* Deferred.isDone(fiberRef);\n\t\tif (!alreadyStarted) {\n\t\t\treturn;\n\t\t}\n\t\tconst fiber = yield* Deferred.await(fiberRef);\n\t\t// `Fiber.await` returns an `Exit` without raising — handles both\n\t\t// success and interrupt-cause cases (the supervisor's\n\t\t// graceful-shutdown path closes the scope, which surfaces as an\n\t\t// interrupt cause if the fiber was mid-await on the latch poll).\n\t\tyield* Fiber.await(fiber);\n\t});\n\n\tconst awaitShutdown: Effect.Effect<void, unknown, never> = Effect.gen(function* () {\n\t\tconst alreadyStarted = yield* Deferred.isDone(fiberRef);\n\t\tif (!alreadyStarted) {\n\t\t\treturn;\n\t\t}\n\t\tconst fiber = yield* Deferred.await(fiberRef);\n\t\tyield* Fiber.await(fiber);\n\t\t// Re-surface any mid-run defect/failure captured by the\n\t\t// supervised body's `catchCause` (boot failures are already\n\t\t// surfaced via `start`). Without this re-raise a plugin scope\n\t\t// finalizer defect would silently drop and operators get no\n\t\t// signal — see the comment on `midRunCauseRef` above.\n\t\tconst midRunCause = yield* Ref.get(midRunCauseRef);\n\t\tif (midRunCause !== null) {\n\t\t\treturn yield* Effect.failCause(midRunCause);\n\t\t}\n\t});\n\n\t// Assign the handle the composed boot hooks close over (they only deref\n\t// it at boot, after this assignment) and return it.\n\tpublicHandle = {\n\t\tstart,\n\t\tstop,\n\t\tawaitShutdown,\n\t\tevents,\n\t\tstate,\n\t\tcommands: commandQueue,\n\t\trunCommand,\n\t\tidentity,\n\t};\n\n\treturn publicHandle;\n};\n"],"mappings":"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"}

package/dist/api/run-stack.d.mts

@@ -1,10 +1,10 @@
 import { SubscribableState } from "../substrate/projection.mjs";
-import { EngineEvent } from "../substrate/events.mjs";
 import { AnyPlugin } from "../substrate/plugin.mjs";
 import { Stack } from "./define-devstack.mjs";
-import { CapabilitySinksService } from "../substrate/runtime/capability-sinks/service.mjs";
-import { ProductionCodegenOptions } from "../orchestrators/runtime-composition.mjs";
-import { Cause, Context, Effect, Scope, Stream, SubscriptionRef } from "effect";
+import { Identity } from "../substrate/identity.mjs";
+import { EngineCommand, EngineEvent } from "../substrate/events.mjs";
+import { ProductionCodegenOptions } from "../orchestrators/boot.mjs";
+import { Cause, Context, Effect, Queue, Scope, Stream, SubscriptionRef } from "effect";
 
 //#region src/api/run-stack.d.ts
 /** Identity overrides for `runStack`. App and stack fall back through
@@ -36,8 +36,8 @@ interface RunStackOptions {
   readonly stateDir?: string;
   /** Extend the plugin execution context after built-in plugin
    *  services are installed. Use this for custom plugin-author
-   *  services, capability sinks, or logger overrides. */
-  readonly extendContext?: (ctx: Context.Context<never>) => Effect.Effect<Context.Context<never>, never, Scope.Scope | CapabilitySinksService>;
+   *  services or logger overrides. */
+  readonly extendContext?: (ctx: Context.Context<never>) => Effect.Effect<Context.Context<never>, never, Scope.Scope>;
 }
 /** Boot error surfaced by `RunHandle.start`. Wraps the supervisor's
  *  startup failure tree for cascade-formatter rendering. */
@@ -45,47 +45,98 @@ interface BootError {
   readonly _tag: 'BootError';
   readonly cause: Cause.Cause<unknown>;
 }
-/** Programmatic handle. Symmetric with the attached CLI surface:
- *  `events`, `state`, and `awaitShutdown` are the same primitives the
- *  TUI consumes in-process. */
+/**
+ * The programmatic handle `runStack` returns. It is a small bag of Effect
+ * values + readable refs — a functional surface, not an object with methods:
+ * each lifecycle action (`start` / `stop` / `awaitShutdown`) is an
+ * `Effect` you run, and each observation channel (`events` / `state`) is a
+ * value you read. Returned synchronously, BEFORE any fiber is forked, so a
+ * caller can subscribe to `state` / `events` ahead of `start`.
+ *
+ * Symmetric with the attached CLI surface: `events`, `state`, and
+ * `awaitShutdown` are the SAME in-process primitives the TUI consumes.
+ *
+ * Typical use:
+ *
+ *   const handle = runStack(stack, opts);
+ *   await Effect.runPromise(handle.start);          // boot → all ready
+ *   const snapshot = await Effect.runPromise(SubscriptionRef.get(handle.state));
+ *   await Effect.runPromise(handle.stop);           // graceful shutdown
+ *   await Effect.runPromise(handle.awaitShutdown);  // finalizers done
+ */
 interface RunHandle {
-  /** Boot the supervisor and resolve when every plugin reaches
-   *  `ready`. Fails with `BootError` if any plugin's acquire path
-   *  fails. */
+  /** Fork the supervisor fiber and resolve once EVERY plugin reaches
+   *  `ready` (or a terminal `done`). Fails with `BootError` if any
+   *  plugin's initial-acquire path fails. Idempotent: a second `start`
+   *  is a no-op that just awaits the same boot gate. */
   readonly start: Effect.Effect<void, BootError, never>;
-  /** Trigger graceful shutdown: enqueues `shutdown.requested` onto
-   *  the supervisor's command channel, then awaits the fiber. */
+  /** Request graceful shutdown: publishes `shutdown.requested` onto the
+   *  supervisor's command channel (driving scope finalizers), then awaits
+   *  the fiber. Safe to call before `start` (returns immediately) and
+   *  more than once. */
   readonly stop: Effect.Effect<void, never, never>;
   /** Resolve when the supervisor fiber exits. Succeeds on a clean
    *  shutdown; fails with the captured `Cause` if the supervisor died
-   *  mid-run after boot completed (e.g. a plugin scope finalizer
-   *  defect). Boot-time failures still surface via `start`. */
+   *  mid-run AFTER boot completed (e.g. a plugin scope-finalizer defect).
+   *  Boot-time failures surface via `start`, not here — so a host that
+   *  blocks the process on this Effect stays up for the supervisor's
+   *  whole lifetime and learns of a post-boot death. */
   readonly awaitShutdown: Effect.Effect<void, unknown, never>;
-  /** Tail of typed engine events from the supervisor's hub. The
-   *  upstream is a `Queue.Dequeue`; consume via `Stream.run...`. */
+  /** Tail of typed engine events off the supervisor's hub. SINGLE
+   *  CONSUMER: the upstream is a `Queue.Dequeue`, so taking an event
+   *  removes it — running this stream from two places SPLITS the events
+   *  between them rather than fanning out. Consume it once (e.g. via
+   *  `Stream.runForEach`) and tee downstream if you need multiple sinks.
+   *  Empty until `start` wires the hub. */
   readonly events: Stream.Stream<EngineEvent, never, never>;
-  /** The supervisor's live projection. Renderers + tests read this
-   *  directly; changes flow through `SubscriptionRef.changes`. */
+  /** The supervisor's live projection — the single read-model of stack
+   *  state (identity, per-plugin lifecycle, cycle phase, log tail). Live
+   *  for the supervisor's whole process lifetime: snapshot it with
+   *  `SubscriptionRef.get`, or observe updates via `SubscriptionRef.changes`.
+   *  Renderers + tests read it directly; nothing writes through it. */
   readonly state: SubscriptionRef.SubscriptionRef<SubscribableState>;
+  /** Fire-and-forget publish side of the supervisor's command channel —
+   *  enqueue an `EngineCommand` (`shutdown.requested`,
+   *  `selective-restart.requested`, snapshot/wipe/prune verbs, …) and
+   *  return immediately. The same queue the supervisor drains; the signal
+   *  handler and the `stop` bridge publish here too. Use `runCommand` when
+   *  you need to await the command's outcome. */
+  readonly commands: Queue.Enqueue<EngineCommand>;
+  /** Submit-and-AWAIT dispatch: publishes `command` in-band on the
+   *  supervisor's command loop and resolves when the loop finishes
+   *  handling it, re-failing with the handler's cause. Use this (over
+   *  `commands`) when the caller must know the command succeeded —
+   *  e.g. a destructive `snapshot.restore`. (The cross-process IPC bridge
+   *  layers ack-correlation on top of this.) */
+  readonly runCommand: (command: EngineCommand) => Effect.Effect<void, unknown, never>;
+  /** The resolved `Identity` — app / stack / network — this handle booted
+   *  with, after all option > env > inference resolution. Available
+   *  synchronously, BEFORE `start`. */
+  readonly identity: Identity;
 }
 /**
  * Boot a `Stack` for programmatic embedding. Returns a `RunHandle`
  * synchronously; the supervisor fiber is forked on `start`.
  *
- * Lifecycle:
+ * Programmatic contract — call, then drive the returned handle's Effects:
  *
- *   1. `runStack(stack, opts)` — synchronous; no fiber forked yet.
- *   2. `await Effect.runPromise(handle.start)` — forks the supervisor,
- *      blocks until every plugin reaches `ready` (or fails with
- *      `BootError`).
- *   3. Use `handle.events` / `handle.state` to observe.
+ *   1. `runStack(stack, opts)` — synchronous; NO fiber forked yet. Safe to
+ *      read `handle.identity` and subscribe to `handle.state` /
+ *      `handle.events` right away.
+ *   2. `await Effect.runPromise(handle.start)` — forks the supervisor and
+ *      blocks until every plugin reaches `ready` (or fails with `BootError`).
+ *   3. Observe via `handle.state` (snapshot / changes) and `handle.events`
+ *      (single-consumer tail); drive via `handle.commands` /
+ *      `handle.runCommand`.
  *   4. `await Effect.runPromise(handle.stop)` — graceful shutdown.
- *   5. `handle.awaitShutdown` resolves once finalizers complete.
+ *   5. `await Effect.runPromise(handle.awaitShutdown)` — resolves once scope
+ *      finalizers complete (or re-raises a post-boot supervisor death).
  *
- * Internal architecture: the handle stores a `Deferred` for boot
- * completion. The supervised body forks a watcher fiber over the
- * registry's `awaitReady` per node; once every node is `ready` (or one
- * fails) the deferred completes. `start` awaits it.
+ * Thin facade: delegates to `runStackWithBoot` (in `run-stack-internal.ts`)
+ * with a zero-`boot` bag and no `commandHandler`, so this public path is
+ * byte-identical to the pre-seam `runStack` body. The boot-injection seam
+ * the CLI `up` verb consumes is non-public — it is NOT re-exported from
+ * `index.ts`, and its substrate types never appear on `RunHandle`.
  */
 declare const runStack: (stack: Stack<ReadonlyArray<AnyPlugin>>, opts?: RunStackOptions) => RunHandle;
 //#endregion