@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/substrate/runtime/supervisor/start-supervisor.mjs

@@ -0,0 +1,250 @@
+import { RuntimeRoot } from "../paths.mjs";
+import { withStackSpan } from "../observability/spans.mjs";
+import { CapabilitySinksService } from "../capability-sinks/service.mjs";
+import { layerCapabilitySinksDefault } from "../capability-sinks/layer.mjs";
+import "../capability-sinks/index.mjs";
+import { SupervisorBootError } from "./errors.mjs";
+import { Logger as Logger$1 } from "../observability/logger.mjs";
+import { LogStore, makeLogStore } from "../observability/log-store.mjs";
+import { SpanStore, makeSpanStore } from "../observability/span-store.mjs";
+import "../observability/index.mjs";
+import { ControlPlaneService } from "../control-plane/service.mjs";
+import { controlPlaneDomainFromContext } from "../control-plane/domain.mjs";
+import { declareAccount, setIdentity } from "../projection/update.mjs";
+import { resolveGraph } from "../lifecycle/dep-graph.mjs";
+import { buildWatchIndex, exactPrefixMatch } from "../lifecycle/watch-attribution.mjs";
+import { planFullDrain } from "../lifecycle/selective-restart.mjs";
+import { installSignalHandler } from "../lifecycle/signals.mjs";
+import "../lifecycle/index.mjs";
+import { OptionalService, buildTransitionEmitter, noopLogger, setCyclePhase, withEventPublishingLogger } from "./wiring.mjs";
+import { acquireFullGraph, buildRegistry } from "./acquire-node.mjs";
+import { runPostAcquireHook } from "./background-tasks.mjs";
+import { teardownKeys } from "./teardown.mjs";
+import { allReadyOrTerminal } from "./state.mjs";
+import { commandLoop } from "./command-loop.mjs";
+import { Context, Deferred, Effect, Exit, Layer, Queue, Ref, SubscriptionRef, Tracer } from "effect";
+//#region src/substrate/runtime/supervisor/start-supervisor.ts
+const loggerAccess = OptionalService(Logger$1);
+const runtimeRootAccess = OptionalService(RuntimeRoot);
+const sinksAccess = OptionalService(CapabilitySinksService);
+const pendingAccountProjection = (rowKey, resourceId, updatedAt) => {
+	if (!resourceId.startsWith("account/")) return null;
+	const name = resourceId.slice(8);
+	if (name.length === 0) return null;
+	return {
+		key: resourceId,
+		rowKey,
+		name,
+		address: null,
+		scheme: null,
+		source: null,
+		funding: {
+			status: "pending",
+			balanceMist: null,
+			requestedMist: null,
+			entries: []
+		},
+		walletVisible: false,
+		updatedAt
+	};
+};
+/**
+* Prepare a supervisor for `stack` without running the initial acquire.
+* The returned `SupervisorHandle` is Scope-managed; the supervisor's
+* lifecycle is the surrounding Scope's lifecycle. Signal handlers,
+* the command loop, and every plugin's scope are children of the
+* supervisor scope. Callers that mount renderers can subscribe to the
+* returned state before invoking `runInitialAcquire`.
+*
+* `pluginContext` carries the substrate-context services available to
+* each plugin's `acquire` body (`IdentityContext`,
+* `ContainerRuntimeService`, `RuntimeRoot`, `StackPathsService`, etc.).
+* Plugins declare what they need by yielding the corresponding
+* `Context.Service` tag from within `Effect.gen`; the supervisor
+* provides this context before running the acquire effect so the
+* plugin's R-channel narrows to `Scope.Scope` (then to `never` after
+* the per-plugin Scope is provided).
+*
+* `CapabilitySinksService` extension (ARCHITECTURE.md § Plugin-author
+* extension via Layer composition): if the caller layers a
+* `CapabilitySinksService` into `pluginContext`, the supervisor
+* harvests through THAT instance instead of building its own.
+*/
+const startSupervisor = (stack, identity, state, pluginContext = Context.empty(), sinks = [], commandHandler, postAcquireHook, options = {}) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({ "devstack.stack.memberCount": stack.members.length });
+	const baseLogger = loggerAccess.read(pluginContext, noopLogger);
+	yield* baseLogger.log("supervisor", null, {
+		level: "debug",
+		message: "supervisor boot start",
+		fields: {
+			app: identity.app,
+			stack: identity.stack,
+			network: identity.chain,
+			memberCount: stack.members.length
+		}
+	});
+	yield* SubscriptionRef.update(state, (s) => ({
+		...setIdentity(s, {
+			app: identity.app,
+			stack: identity.stack,
+			network: identity.chain
+		}),
+		cycle: {
+			...s.cycle,
+			startedAt: s.cycle.startedAt === 0 ? Date.now() : s.cycle.startedAt,
+			phase: "booting"
+		}
+	}));
+	const graph = yield* resolveGraph(stack.members).pipe(Effect.mapError((cause) => new SupervisorBootError({ cause })));
+	const hub = yield* Queue.unbounded();
+	const commands = yield* Queue.unbounded();
+	const queuedCommands = yield* Queue.unbounded();
+	const stackRestartTask = yield* Ref.make({ tag: "idle" });
+	const stackRestartSeq = yield* Ref.make(0);
+	const snapshotCaptureTask = yield* Ref.make({ tag: "idle" });
+	const snapshotCaptureSeq = yield* Ref.make(0);
+	const shutdownLatch = yield* Ref.make(false);
+	const shutdownComplete = yield* Deferred.make();
+	const initialAcquireStarted = yield* Ref.make(false);
+	const logStore = yield* makeLogStore(options.logStore ?? {});
+	const spanStore = yield* makeSpanStore();
+	const logger = withEventPublishingLogger(baseLogger, state, hub, logStore);
+	const traced = (eff) => Effect.provideService(eff, Tracer.Tracer, spanStore.tracer);
+	const registry = yield* buildRegistry(graph, yield* Effect.scope, buildTransitionEmitter(state, hub));
+	const controlPlaneDomain = controlPlaneDomainFromContext({
+		pluginContext,
+		graph,
+		registry,
+		logStore,
+		spanStore
+	});
+	const pluginRuntimeContext = pluginContext.pipe(Context.add(Logger$1, Logger$1.of(logger)), Context.add(LogStore, LogStore.of(logStore)), Context.add(SpanStore, SpanStore.of(spanStore)), Context.add(Tracer.Tracer, spanStore.tracer), Context.add(ControlPlaneService, ControlPlaneService.of({
+		state,
+		publishCommand: (command) => Effect.asVoid(Queue.offer(commands, command)),
+		domain: controlPlaneDomain
+	})));
+	for (const [key, node] of graph.nodes) {
+		const declaredAccount = pendingAccountProjection(key, node.member.id, Date.now());
+		yield* SubscriptionRef.update(state, (s) => ({
+			...declaredAccount === null ? s : declareAccount(s, declaredAccount),
+			rows: s.rows.some((r) => r.key === key) ? s.rows : [...s.rows, {
+				key,
+				role: node.member.role,
+				status: "pending",
+				phase: null,
+				lastError: null,
+				logTail: {
+					lines: [],
+					level: "info",
+					truncated: false
+				},
+				endpoints: [],
+				selectiveRestartHighlight: false,
+				section: node.member.section,
+				endpointSection: node.member.endpointSection ?? node.member.section
+			}]
+		}));
+	}
+	const runtimeRootResolved = runtimeRootAccess.read(pluginContext, { root: "" });
+	if (runtimeRootResolved.root === "") yield* Effect.logWarning("supervisor: RuntimeRoot missing from pluginContext; falling back to empty root. Production wiring must layer `layerRuntimeRoot(...)` into pluginContext.");
+	const runtimeRoot = runtimeRootResolved.root;
+	const sinksService = yield* sinksAccess.readEffect(pluginRuntimeContext, Effect.gen(function* () {
+		return Context.get(yield* Layer.build(layerCapabilitySinksDefault(sinks)), CapabilitySinksService);
+	}));
+	const enableCommandLoop = options.commandLoop !== false;
+	if (enableCommandLoop) {
+		yield* Effect.forkScoped(traced(installSignalHandler(commands)));
+		yield* Effect.forkScoped(traced(Effect.gen(function* () {
+			while (true) {
+				const command = yield* Queue.take(commands);
+				yield* Queue.offer(queuedCommands, {
+					kind: "fire-and-forget",
+					command
+				});
+			}
+		})));
+	}
+	const supervisorState = {
+		graph,
+		registry,
+		ref: state,
+		hub,
+		queuedCommands,
+		stackRestartTask,
+		stackRestartSeq,
+		snapshotCaptureTask,
+		snapshotCaptureSeq,
+		shutdownLatch,
+		shutdownComplete,
+		pluginContext: pluginRuntimeContext,
+		sinks: sinksService,
+		logger,
+		identity,
+		runtimeRoot,
+		commandHandler,
+		postAcquireHook
+	};
+	const runInitialAcquire = Effect.gen(function* () {
+		if (yield* Ref.modify(initialAcquireStarted, (started) => [started, true])) return;
+		if (yield* Ref.get(shutdownLatch)) return;
+		yield* acquireFullGraph(graph, registry, state, hub, pluginRuntimeContext, sinksService, logger, identity, runtimeRoot);
+		if (yield* Ref.get(shutdownLatch)) return;
+		if (yield* allReadyOrTerminal(graph, registry)) {
+			yield* runPostAcquireHook(supervisorState);
+			if (!(yield* Ref.get(shutdownLatch))) yield* setCyclePhase(state, "running");
+		} else if (!(yield* Ref.get(shutdownLatch))) yield* setCyclePhase(state, "running");
+	}).pipe(Effect.withSpan("lifecycle.supervisor.initialAcquire"), traced);
+	const watchIndex = buildWatchIndex(graph.nodes);
+	const notifyWatchFire = (path) => Effect.gen(function* () {
+		const matched = /* @__PURE__ */ new Set();
+		for (const entry of watchIndex) for (const pat of entry.paths) if (exactPrefixMatch(pat, path)) {
+			matched.add(entry.pluginKey);
+			break;
+		}
+		if (matched.size === 0) return;
+		for (const key of matched) yield* Queue.offer(commands, {
+			tag: "selective-restart.requested",
+			pluginKey: key
+		});
+	}).pipe(Effect.withSpan("lifecycle.supervisor.notifyWatchFire"));
+	if (enableCommandLoop) yield* Effect.forkScoped(traced(commandLoop(supervisorState)));
+	yield* Effect.addFinalizer(() => traced(Effect.gen(function* () {
+		yield* teardownKeys(graph, registry, planFullDrain(graph).teardownOrder).pipe(Effect.catch(() => Effect.void));
+	})));
+	const awaitShutdown = Deferred.await(shutdownComplete).pipe(Effect.withSpan("lifecycle.supervisor.awaitShutdown"), traced);
+	const runCommand = (command) => Effect.gen(function* () {
+		const completion = yield* Deferred.make();
+		yield* Queue.offer(queuedCommands, {
+			kind: "submitted",
+			submission: {
+				command,
+				completion
+			}
+		});
+		const exit = yield* Deferred.await(completion);
+		if (Exit.isFailure(exit)) return yield* Effect.failCause(exit.cause);
+	}).pipe(Effect.withSpan("lifecycle.supervisor.runCommand"), traced);
+	return {
+		handle: {
+			identity,
+			graph,
+			registry,
+			events: hub,
+			commands,
+			runCommand,
+			state,
+			watchIndex,
+			notifyWatchFire,
+			awaitShutdown
+		},
+		runInitialAcquire
+	};
+}).pipe(withStackSpan("lifecycle.supervisor.startSupervisor", {
+	app: identity.app,
+	stack: identity.stack,
+	network: identity.chain
+}));
+//#endregion
+export { startSupervisor };
+
+//# sourceMappingURL=start-supervisor.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"start-supervisor.mjs","names":["Logger"],"sources":["../../../../src/substrate/runtime/supervisor/start-supervisor.ts"],"sourcesContent":["// Top-level supervisor entry — composes every per-concern module.\n//\n// Responsibilities (in order):\n//   1. Seed projection identity + booting slice so early-mounted\n//      renderers see a complete baseline.\n//   2. Resolve the dep graph + boot the registry.\n//   3. Build the substrate-wiring bag: logger overlay, runtime root,\n//      CapabilitySinks service (caller-pre-built or substrate-default).\n//   4. Compose the `SupervisorState` record (one bag passed to every\n//      module).\n//   5. Build `runInitialAcquire` — the deferred initial-acquire body.\n//   6. Build the watch index + `notifyWatchFire`.\n//   7. Fork the command loop + signal handler.\n//   8. Install the scope-close finalizer (reverse-dep teardown).\n//   9. Return the handle.\n\nimport {\n\tContext,\n\tDeferred,\n\tEffect,\n\tExit,\n\tLayer,\n\tQueue,\n\tRef,\n\tScope,\n\tSubscriptionRef,\n\tTracer,\n} from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport type { EngineCommand, EngineEvent } from '../../events.ts';\nimport type { Identity } from '../../identity.ts';\nimport type { LifecycleStatus } from '../../lifecycle.ts';\nimport type { AccountProjection, SubscribableState } from '../../projection.ts';\nimport {\n\tCapabilitySinksService,\n\tlayerCapabilitySinksDefault,\n\ttype OrchestratorSinks,\n} from '../capability-sinks/index.ts';\nimport {\n\tLogger,\n\tLogStore,\n\tSpanStore,\n\tmakeLogStore,\n\tmakeSpanStore,\n\twithStackSpan,\n\ttype LoggerShape,\n\ttype LogStoreConfig,\n} from '../observability/index.ts';\nimport { ControlPlaneService } from '../control-plane/service.ts';\nimport { controlPlaneDomainFromContext } from '../control-plane/domain.ts';\nimport { RuntimeRoot } from '../paths.ts';\nimport { declareAccount, setIdentity } from '../projection/update.ts';\nimport {\n\tbuildWatchIndex,\n\texactPrefixMatch,\n\tinstallSignalHandler,\n\tplanFullDrain,\n\tresolveGraph,\n\ttype PluginRegistry,\n\ttype ResolvedGraph,\n\ttype UnknownDependency,\n\ttype WatchEntry,\n} from '../lifecycle/index.ts';\nimport { acquireFullGraph, buildRegistry } from './acquire-node.ts';\nimport { commandLoop } from './command-loop.ts';\nimport { runPostAcquireHook } from './background-tasks.ts';\nimport {\n\tSupervisorBootError,\n\ttype SupervisorError,\n\ttype SupervisorPostAcquireFailed,\n} from './errors.ts';\nimport {\n\tallReadyOrTerminal,\n\ttype QueuedCommand,\n\ttype SnapshotCaptureTaskState,\n\ttype StackRestartTaskState,\n\ttype SupervisorCommandHandler,\n\ttype SupervisorPostAcquireHook,\n\ttype SupervisorState,\n} from './state.ts';\nimport type { SupervisedStack } from './types.ts';\nimport { teardownKeys } from './teardown.ts';\nimport {\n\tbuildTransitionEmitter,\n\tnoopLogger,\n\tOptionalService,\n\tsetCyclePhase,\n\twithEventPublishingLogger,\n} from './wiring.ts';\n\nconst loggerAccess = OptionalService(Logger);\nconst runtimeRootAccess = OptionalService(RuntimeRoot);\nconst sinksAccess = OptionalService(CapabilitySinksService);\n\nexport interface SupervisorHandle {\n\treadonly identity: Identity;\n\treadonly graph: ResolvedGraph;\n\treadonly registry: PluginRegistry;\n\treadonly events: Queue.Dequeue<EngineEvent>;\n\treadonly commands: Queue.Enqueue<EngineCommand>;\n\treadonly runCommand: (command: EngineCommand) => Effect.Effect<void, unknown>;\n\treadonly state: SubscriptionRef.SubscriptionRef<SubscribableState>;\n\treadonly watchIndex: ReadonlyArray<WatchEntry>;\n\t/** Fire a watch event for the given path. Substrate-level glue:\n\t *  the thick L0 watcher calls this; tests call it directly. */\n\treadonly notifyWatchFire: (path: string) => Effect.Effect<void>;\n\t/** Block until the supervisor's command loop sets the shutdown\n\t *  latch. The outer runtime then closes the supervisor scope, which\n\t *  tears down every plugin in reverse-dep order. */\n\treadonly awaitShutdown: Effect.Effect<void>;\n}\n\nexport interface SupervisorStartup {\n\treadonly handle: SupervisorHandle;\n\treadonly runInitialAcquire: Effect.Effect<void, SupervisorPostAcquireFailed, never>;\n}\n\nexport interface SupervisorStartupOptions {\n\treadonly commandLoop?: boolean;\n\t/** Per-service log-store tuning. Absent fields fall back to the\n\t *  `DEVSTACK_DASHBOARD_LOG_*` env vars, then the module defaults\n\t *  (2000 records/service, 256 services). Threaded into the\n\t *  process-scoped `makeLogStore` below. */\n\treadonly logStore?: LogStoreConfig;\n}\n\nconst pendingAccountProjection = (\n\trowKey: PluginKey,\n\tresourceId: string,\n\tupdatedAt: number,\n): AccountProjection | null => {\n\tif (!resourceId.startsWith('account/')) return null;\n\tconst name = resourceId.slice('account/'.length);\n\tif (name.length === 0) return null;\n\treturn {\n\t\tkey: resourceId as `account/${string}`,\n\t\trowKey,\n\t\tname,\n\t\taddress: null,\n\t\tscheme: null,\n\t\tsource: null,\n\t\tfunding: { status: 'pending', balanceMist: null, requestedMist: null, entries: [] },\n\t\twalletVisible: false,\n\t\tupdatedAt,\n\t};\n};\n\n/**\n * Prepare a supervisor for `stack` without running the initial acquire.\n * The returned `SupervisorHandle` is Scope-managed; the supervisor's\n * lifecycle is the surrounding Scope's lifecycle. Signal handlers,\n * the command loop, and every plugin's scope are children of the\n * supervisor scope. Callers that mount renderers can subscribe to the\n * returned state before invoking `runInitialAcquire`.\n *\n * `pluginContext` carries the substrate-context services available to\n * each plugin's `acquire` body (`IdentityContext`,\n * `ContainerRuntimeService`, `RuntimeRoot`, `StackPathsService`, etc.).\n * Plugins declare what they need by yielding the corresponding\n * `Context.Service` tag from within `Effect.gen`; the supervisor\n * provides this context before running the acquire effect so the\n * plugin's R-channel narrows to `Scope.Scope` (then to `never` after\n * the per-plugin Scope is provided).\n *\n * `CapabilitySinksService` extension (ARCHITECTURE.md § Plugin-author\n * extension via Layer composition): if the caller layers a\n * `CapabilitySinksService` into `pluginContext`, the supervisor\n * harvests through THAT instance instead of building its own.\n */\nexport const startSupervisor = (\n\tstack: SupervisedStack,\n\tidentity: Identity,\n\tstate: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\tpluginContext: Context.Context<never> = Context.empty(),\n\tsinks: OrchestratorSinks = [],\n\tcommandHandler?: SupervisorCommandHandler,\n\tpostAcquireHook?: SupervisorPostAcquireHook,\n\toptions: SupervisorStartupOptions = {},\n): Effect.Effect<SupervisorStartup, SupervisorBootError | UnknownDependency, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.stack.memberCount': stack.members.length,\n\t\t});\n\n\t\t// Optional Logger service — pull from the plugin context if the\n\t\t// caller layered it in (CLI / e2e do). Bare smoke tests get the\n\t\t// no-op fallback so they remain log-free.\n\t\tconst baseLogger: LoggerShape = loggerAccess.read(pluginContext, noopLogger);\n\n\t\tyield* baseLogger.log('supervisor', null, {\n\t\t\tlevel: 'debug',\n\t\t\tmessage: 'supervisor boot start',\n\t\t\tfields: {\n\t\t\t\tapp: identity.app,\n\t\t\t\tstack: identity.stack,\n\t\t\t\tnetwork: identity.chain,\n\t\t\t\tmemberCount: stack.members.length,\n\t\t\t},\n\t\t});\n\n\t\t// Seed the projection's identity and booting slices before\n\t\t// acquire starts so renderers mounting early have a complete\n\t\t// baseline.\n\t\tyield* SubscriptionRef.update(\n\t\t\tstate,\n\t\t\t(s) =>\n\t\t\t\t({\n\t\t\t\t\t...setIdentity(s, {\n\t\t\t\t\t\tapp: identity.app,\n\t\t\t\t\t\tstack: identity.stack,\n\t\t\t\t\t\tnetwork: identity.chain,\n\t\t\t\t\t}),\n\t\t\t\t\tcycle: {\n\t\t\t\t\t\t...s.cycle,\n\t\t\t\t\t\tstartedAt: s.cycle.startedAt === 0 ? Date.now() : s.cycle.startedAt,\n\t\t\t\t\t\tphase: 'booting',\n\t\t\t\t\t},\n\t\t\t\t}) satisfies SubscribableState,\n\t\t);\n\n\t\t// Resolve the dep graph.\n\t\tconst graph = yield* resolveGraph(stack.members).pipe(\n\t\t\tEffect.mapError((cause) => new SupervisorBootError({ cause })),\n\t\t);\n\n\t\t// Event hub + command channel.\n\t\tconst hub = yield* Queue.unbounded<EngineEvent>();\n\t\tconst commands = yield* Queue.unbounded<EngineCommand>();\n\t\tconst queuedCommands = yield* Queue.unbounded<QueuedCommand>();\n\t\tconst stackRestartTask = yield* Ref.make<StackRestartTaskState>({ tag: 'idle' });\n\t\tconst stackRestartSeq = yield* Ref.make(0);\n\t\tconst snapshotCaptureTask = yield* Ref.make<SnapshotCaptureTaskState>({ tag: 'idle' });\n\t\tconst snapshotCaptureSeq = yield* Ref.make(0);\n\t\tconst shutdownLatch = yield* Ref.make(false);\n\t\tconst shutdownComplete = yield* Deferred.make<void>();\n\t\tconst initialAcquireStarted = yield* Ref.make(false);\n\n\t\t// Observability stores (process-scoped, like `state`/`hub`): a\n\t\t// cross-service queryable log ring fed off the SAME logger path that\n\t\t// feeds the projection's per-row tail, and a completed-span ring fed\n\t\t// by a recording Tracer. Both survive `stack.restart` because they\n\t\t// live in this closure (only `cycle.id` bumps on restart). The\n\t\t// dashboard reads them via the control-plane `domain`.\n\t\tconst logStore = yield* makeLogStore(options.logStore ?? {});\n\t\tconst spanStore = yield* makeSpanStore();\n\t\tconst logger = withEventPublishingLogger(baseLogger, state, hub, logStore);\n\n\t\t// Provide the recording Tracer to the supervisor's OWN effects too.\n\t\t// `pluginRuntimeContext` below carries the tracer into plugin\n\t\t// acquire/boot, but the supervisor's forked fibers (command loop,\n\t\t// background snapshot/restart tasks), the teardown finalizer, and the\n\t\t// `lifecycle.supervisor.*` spans run under THIS fiber's ambient context\n\t\t// — which has no tracer unless we add one. Without this, exactly the\n\t\t// dashboard-triggered ops (restart/snapshot/prune) the Traces tab wants\n\t\t// would emit spans into the default no-op tracer and evaporate.\n\t\t// `forkScoped`/finalizers inherit the context at fork/install time, so\n\t\t// stamping the tracer onto each supervisor-owned effect captures them\n\t\t// without double-provisioning the plugin path or disturbing any\n\t\t// caller-provided OTel composition.\n\t\tconst traced = <A, E, R>(eff: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n\t\t\tEffect.provideService(eff, Tracer.Tracer, spanStore.tracer);\n\n\t\t// Per-plugin scopes parent off the supervisor scope.\n\t\tconst supervisorScope = yield* Effect.scope;\n\n\t\tconst emit = buildTransitionEmitter(state, hub);\n\t\tconst registry = yield* buildRegistry(graph, supervisorScope, emit);\n\n\t\t// Build the control-plane `domain` accessor surface from the data\n\t\t// the supervisor holds at wiring time: the resolved registry +\n\t\t// graph, plus the (optional) snapshot orchestrator / container\n\t\t// runtime / filesystem the caller may have layered into\n\t\t// `pluginContext`. The projection stays CLOSED — `domain` reads\n\t\t// resolved plugin VALUES via the name-blind registry seam, never\n\t\t// the projection. The registry is process-scoped, so the closure\n\t\t// stays valid across `stack.restart` (only `cycle.id` bumps).\n\t\tconst controlPlaneDomain = controlPlaneDomainFromContext({\n\t\t\tpluginContext,\n\t\t\tgraph,\n\t\t\tregistry,\n\t\t\tlogStore,\n\t\t\tspanStore,\n\t\t});\n\n\t\tconst pluginRuntimeContext = pluginContext.pipe(\n\t\t\tContext.add(Logger, Logger.of(logger)),\n\t\t\t// Observability stores + the recording Tracer. The Tracer is an\n\t\t\t// Effect `Context.Reference`, so adding it here makes every span\n\t\t\t// run with this context (all plugin acquire/boot/op spans —\n\t\t\t// `withSpan`/`spanWithLabels`) record into `spanStore` instead of\n\t\t\t// hitting the default no-op native tracer. The stores themselves\n\t\t\t// are exposed so the control-plane `domain` can query them.\n\t\t\tContext.add(LogStore, LogStore.of(logStore)),\n\t\t\tContext.add(SpanStore, SpanStore.of(spanStore)),\n\t\t\tContext.add(Tracer.Tracer, spanStore.tracer),\n\t\t\t// Expose the control plane (live projection + fire-and-forget\n\t\t\t// command dispatch + the plugin-domain accessor surface) to\n\t\t\t// in-process surfaces like the dashboard plugin. Reads the same\n\t\t\t// `state` ref and `commands` queue the supervisor itself drives.\n\t\t\tContext.add(\n\t\t\t\tControlPlaneService,\n\t\t\t\tControlPlaneService.of({\n\t\t\t\t\tstate,\n\t\t\t\t\tpublishCommand: (command) => Effect.asVoid(Queue.offer(commands, command)),\n\t\t\t\t\tdomain: controlPlaneDomain,\n\t\t\t\t}),\n\t\t\t),\n\t\t) as Context.Context<never>;\n\n\t\t// Declare a row for every plugin so the projection's\n\t\t// `lifecycle.statusChanged` events have a row to attach to.\n\t\t// `section` is plugin-declared at `definePlugin({ section })`\n\t\t// time; we stamp it onto the row here so the TUI groups rows\n\t\t// without pattern-matching on plugin-name substrings.\n\t\tfor (const [key, node] of graph.nodes) {\n\t\t\tconst declaredAccount = pendingAccountProjection(key, node.member.id, Date.now());\n\t\t\tyield* SubscriptionRef.update(state, (s) => ({\n\t\t\t\t...(declaredAccount === null ? s : declareAccount(s, declaredAccount)),\n\t\t\t\trows: s.rows.some((r) => r.key === key)\n\t\t\t\t\t? s.rows\n\t\t\t\t\t: [\n\t\t\t\t\t\t\t...s.rows,\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\tkey,\n\t\t\t\t\t\t\t\trole: node.member.role,\n\t\t\t\t\t\t\t\tstatus: 'pending' as LifecycleStatus,\n\t\t\t\t\t\t\t\tphase: null,\n\t\t\t\t\t\t\t\tlastError: null,\n\t\t\t\t\t\t\t\tlogTail: { lines: [], level: 'info' as const, truncated: false },\n\t\t\t\t\t\t\t\tendpoints: [],\n\t\t\t\t\t\t\t\tselectiveRestartHighlight: false,\n\t\t\t\t\t\t\t\tsection: node.member.section,\n\t\t\t\t\t\t\t\tendpointSection: node.member.endpointSection ?? node.member.section,\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t],\n\t\t\t}));\n\t\t}\n\n\t\t// Extract `RuntimeRoot` from the plugin context — needed to\n\t\t// build the `AcquireContext` handed to dynamic capability\n\t\t// factories. Fallback to '' for bare smoke tests that don't\n\t\t// wire RuntimeRoot; emit a logWarning when that path fires so\n\t\t// production-style misconfigurations are visible (plugins\n\t\t// computing `${runtimeRoot}/foo` would otherwise silently\n\t\t// resolve to host-filesystem root).\n\t\tconst runtimeRootResolved = runtimeRootAccess.read(pluginContext, { root: '' });\n\t\tif (runtimeRootResolved.root === '') {\n\t\t\tyield* Effect.logWarning(\n\t\t\t\t'supervisor: RuntimeRoot missing from pluginContext; falling back to empty root. ' +\n\t\t\t\t\t'Production wiring must layer `layerRuntimeRoot(...)` into pluginContext.',\n\t\t\t);\n\t\t}\n\t\tconst runtimeRoot = runtimeRootResolved.root;\n\n\t\t// Resolve the CapabilitySinks registry for this stack. Two paths:\n\t\t//\n\t\t//   (a) Plugin-author / orchestrator pre-built path: the caller\n\t\t//       layered a `CapabilitySinksService` into `pluginContext`\n\t\t//       (typically by composing `layerCapabilitySinksDefault(...)`\n\t\t//       PLUS one or more custom-sink Layers). The supervisor\n\t\t//       harvests through THAT instance, so custom sinks\n\t\t//       registered by plugin authors actually fire.\n\t\t//\n\t\t//   (b) Bare path: no service in context — the supervisor builds\n\t\t//       the substrate default with the orchestrator sinks passed\n\t\t//       in. `Layer.build` opens the layer's resources on the\n\t\t//       SURROUNDING scope (the supervisor's), so the sinks +\n\t\t//       formatter registry live for the supervisor's lifetime\n\t\t//       and reap on its scope close.\n\t\tconst sinksService = yield* sinksAccess.readEffect(\n\t\t\tpluginRuntimeContext,\n\t\t\tEffect.gen(function* () {\n\t\t\t\treturn Context.get(\n\t\t\t\t\tyield* Layer.build(layerCapabilitySinksDefault(sinks)),\n\t\t\t\t\tCapabilitySinksService,\n\t\t\t\t);\n\t\t\t}),\n\t\t);\n\n\t\tconst enableCommandLoop = options.commandLoop !== false;\n\t\tif (enableCommandLoop) {\n\t\t\tyield* Effect.forkScoped(traced(installSignalHandler(commands)));\n\t\t\tyield* Effect.forkScoped(\n\t\t\t\ttraced(\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\twhile (true) {\n\t\t\t\t\t\t\tconst command = yield* Queue.take(commands);\n\t\t\t\t\t\t\tyield* Queue.offer(queuedCommands, { kind: 'fire-and-forget', command });\n\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\tconst supervisorState: SupervisorState = {\n\t\t\tgraph,\n\t\t\tregistry,\n\t\t\tref: state,\n\t\t\thub,\n\t\t\tqueuedCommands,\n\t\t\tstackRestartTask,\n\t\t\tstackRestartSeq,\n\t\t\tsnapshotCaptureTask,\n\t\t\tsnapshotCaptureSeq,\n\t\t\tshutdownLatch,\n\t\t\tshutdownComplete,\n\t\t\tpluginContext: pluginRuntimeContext,\n\t\t\tsinks: sinksService,\n\t\t\tlogger,\n\t\t\tidentity,\n\t\t\truntimeRoot,\n\t\t\tcommandHandler,\n\t\t\tpostAcquireHook,\n\t\t};\n\n\t\tconst runInitialAcquire = Effect.gen(function* () {\n\t\t\tconst alreadyStarted = yield* Ref.modify(initialAcquireStarted, (started) => [started, true]);\n\t\t\tif (alreadyStarted) return;\n\t\t\tif (yield* Ref.get(shutdownLatch)) return;\n\t\t\tyield* acquireFullGraph(\n\t\t\t\tgraph,\n\t\t\t\tregistry,\n\t\t\t\tstate,\n\t\t\t\thub,\n\t\t\t\tpluginRuntimeContext,\n\t\t\t\tsinksService,\n\t\t\t\tlogger,\n\t\t\t\tidentity,\n\t\t\t\truntimeRoot,\n\t\t\t);\n\t\t\tif (yield* Ref.get(shutdownLatch)) return;\n\t\t\tconst initialReady = yield* allReadyOrTerminal(graph, registry);\n\t\t\tif (initialReady) {\n\t\t\t\tyield* runPostAcquireHook(supervisorState);\n\t\t\t\tif (!(yield* Ref.get(shutdownLatch))) {\n\t\t\t\t\tyield* setCyclePhase(state, 'running');\n\t\t\t\t}\n\t\t\t} else if (!(yield* Ref.get(shutdownLatch))) {\n\t\t\t\tyield* setCyclePhase(state, 'running');\n\t\t\t}\n\t\t}).pipe(Effect.withSpan('lifecycle.supervisor.initialAcquire'), traced);\n\n\t\t// Build the watch index up front; the supervisor exposes\n\t\t// `notifyWatchFire` so the L0 thick watcher can call into it.\n\t\tconst watchIndex = buildWatchIndex(graph.nodes);\n\n\t\tconst notifyWatchFire = (path: string): Effect.Effect<void> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst matched = new Set<PluginKey>();\n\t\t\t\tfor (const entry of watchIndex) {\n\t\t\t\t\tfor (const pat of entry.paths) {\n\t\t\t\t\t\tif (exactPrefixMatch(pat, path)) {\n\t\t\t\t\t\t\tmatched.add(entry.pluginKey);\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}\n\t\t\t\tif (matched.size === 0) return;\n\t\t\t\t// One `selective-restart.requested` per matched plugin, in\n\t\t\t\t// match order. (Previously the head was offered separately\n\t\t\t\t// from the tail — identical behaviour, one fewer branch.)\n\t\t\t\tfor (const key of matched) {\n\t\t\t\t\tyield* Queue.offer(commands, {\n\t\t\t\t\t\ttag: 'selective-restart.requested',\n\t\t\t\t\t\tpluginKey: key,\n\t\t\t\t\t} satisfies EngineCommand);\n\t\t\t\t}\n\t\t\t}).pipe(Effect.withSpan('lifecycle.supervisor.notifyWatchFire'));\n\n\t\t// Fork the command loop.\n\t\tif (enableCommandLoop) {\n\t\t\tyield* Effect.forkScoped(traced(commandLoop(supervisorState)));\n\t\t}\n\n\t\t// Tear-down finalizer: closes every plugin scope in reverse-dep\n\t\t// order. The supervisor scope itself closes when the surrounding\n\t\t// caller closes — `Scope.close` cascades to plugin scopes.\n\t\tyield* Effect.addFinalizer(() =>\n\t\t\ttraced(\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst plan = planFullDrain(graph);\n\t\t\t\t\tyield* teardownKeys(graph, registry, plan.teardownOrder).pipe(\n\t\t\t\t\t\tEffect.catch(() => Effect.void),\n\t\t\t\t\t);\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\n\t\tconst awaitShutdown: Effect.Effect<void> = Deferred.await(shutdownComplete).pipe(\n\t\t\tEffect.withSpan('lifecycle.supervisor.awaitShutdown'),\n\t\t\ttraced,\n\t\t);\n\n\t\tconst runCommand = (command: EngineCommand): Effect.Effect<void, unknown> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst completion = yield* Deferred.make<Exit.Exit<void, unknown>>();\n\t\t\t\tyield* Queue.offer(queuedCommands, {\n\t\t\t\t\tkind: 'submitted',\n\t\t\t\t\tsubmission: { command, completion },\n\t\t\t\t});\n\t\t\t\tconst exit = yield* Deferred.await(completion);\n\t\t\t\tif (Exit.isFailure(exit)) {\n\t\t\t\t\treturn yield* Effect.failCause(exit.cause);\n\t\t\t\t}\n\t\t\t}).pipe(Effect.withSpan('lifecycle.supervisor.runCommand'), traced);\n\n\t\tconst handle = {\n\t\t\tidentity,\n\t\t\tgraph,\n\t\t\tregistry,\n\t\t\tevents: hub,\n\t\t\tcommands,\n\t\t\trunCommand,\n\t\t\tstate,\n\t\t\twatchIndex,\n\t\t\tnotifyWatchFire,\n\t\t\tawaitShutdown,\n\t\t} satisfies SupervisorHandle;\n\t\treturn { handle, runInitialAcquire } satisfies SupervisorStartup;\n\t}).pipe(\n\t\twithStackSpan('lifecycle.supervisor.startSupervisor', {\n\t\t\tapp: identity.app,\n\t\t\tstack: identity.stack,\n\t\t\tnetwork: identity.chain,\n\t\t}),\n\t);\n\n/**\n * Boot a supervisor for `stack` and wait for the initial acquire to\n * finish before returning the handle. Existing callers that only need\n * a ready-or-failed handle keep this simpler entry point; live surfaces\n * that need startup display use `startSupervisor`.\n */\nexport const supervise = (\n\tstack: SupervisedStack,\n\tidentity: Identity,\n\tstate: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\tpluginContext: Context.Context<never> = Context.empty(),\n\tsinks: OrchestratorSinks = [],\n\tcommandHandler?: SupervisorCommandHandler,\n\tpostAcquireHook?: SupervisorPostAcquireHook,\n): Effect.Effect<SupervisorHandle, SupervisorError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst startup = yield* startSupervisor(\n\t\t\tstack,\n\t\t\tidentity,\n\t\t\tstate,\n\t\t\tpluginContext,\n\t\t\tsinks,\n\t\t\tcommandHandler,\n\t\t\tpostAcquireHook,\n\t\t\t{ commandLoop: true },\n\t\t);\n\t\tyield* startup.runInitialAcquire;\n\t\treturn startup.handle;\n\t}).pipe(\n\t\twithStackSpan('lifecycle.supervisor.supervise', {\n\t\t\tapp: identity.app,\n\t\t\tstack: identity.stack,\n\t\t\tnetwork: identity.chain,\n\t\t}),\n\t);\n\n/**\n * Block until the supervisor's shutdown latch fires OR the surrounding\n * scope is interrupted (signal-driven exit). Wraps `awaitShutdown` for\n * the common \"boot then wait\" shape.\n *\n * Returns the final supervisor state so callers (CLI, programmable\n * API) can inspect the projection after shutdown.\n */\nexport const runToShutdown = (\n\thandle: SupervisorHandle,\n): Effect.Effect<SubscribableState, never, never> =>\n\tEffect.gen(function* () {\n\t\tyield* handle.awaitShutdown;\n\t\treturn yield* SubscriptionRef.get(handle.state);\n\t}).pipe(Effect.withSpan('lifecycle.supervisor.runToShutdown'));\n"],"mappings":"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"}

package/dist/substrate/runtime/supervisor/state.d.mts

@@ -0,0 +1 @@
+import { Context, Deferred, Effect, Exit, Fiber, Queue, Ref, SubscriptionRef } from "effect";

package/dist/substrate/runtime/supervisor/state.mjs

@@ -0,0 +1,22 @@
+import "../capability-sinks/index.mjs";
+import { isReadyOrTerminal } from "../lifecycle/state-machine.mjs";
+import "../lifecycle/index.mjs";
+import { Effect } from "effect";
+//#region src/substrate/runtime/supervisor/state.ts
+/**
+* True when every node in `graph` has reached a `ready`-or-terminal
+* lifecycle status. Used by the command-loop to gate the post-acquire
+* hook after a (selective) restart and by the initial-acquire path to
+* decide whether to transition the cycle phase to `running`.
+*
+* Failed status reads collapse to `'failed'` so a transient registry
+* error doesn't block the readiness gate forever.
+*/
+const allReadyOrTerminal = (graph, registry) => Effect.gen(function* () {
+	for (const key of graph.nodes.keys()) if (!isReadyOrTerminal(yield* registry.getStatus(key).pipe(Effect.catch(() => Effect.succeed("failed"))))) return false;
+	return true;
+});
+//#endregion
+export { allReadyOrTerminal };
+
+//# sourceMappingURL=state.mjs.map

package/dist/substrate/runtime/supervisor/state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.mjs","names":[],"sources":["../../../../src/substrate/runtime/supervisor/state.ts"],"sourcesContent":["// Supervisor shared-state record.\n//\n// `startSupervisor`'s `Effect.gen` body closes over ~20 locals. Rather\n// than thread each one through every helper individually, we group\n// them into a typed bag here so the per-concern modules (command-loop,\n// background-tasks, shutdown) take ONE argument.\n//\n// The shape originated as `CommandLoopDeps`; the split renames it and\n// extends with the post-acquire context (graph, registry, identity,\n// runtimeRoot) so the same record satisfies every module's needs.\n\nimport {\n\tEffect,\n\ttype Context,\n\ttype Deferred,\n\ttype Exit,\n\ttype Fiber,\n\ttype Queue,\n\ttype Ref,\n\ttype SubscriptionRef,\n} from 'effect';\n\nimport type { EngineCommand, EngineEvent } from '../../events.ts';\nimport type { Identity } from '../../identity.ts';\nimport type { LifecycleStatus } from '../../lifecycle.ts';\nimport type { SubscribableState } from '../../projection.ts';\nimport { type CapabilitySinksShape } from '../capability-sinks/index.ts';\nimport { isReadyOrTerminal } from '../lifecycle/index.ts';\nimport type { LoggerShape } from '../observability/index.ts';\nimport type { PluginRegistry, ResolvedGraph } from '../lifecycle/index.ts';\n\nexport type StackRestartTaskState =\n\t| { readonly tag: 'idle' }\n\t| { readonly tag: 'starting'; readonly token: number }\n\t| {\n\t\t\treadonly tag: 'running';\n\t\t\treadonly token: number;\n\t\t\treadonly fiber: Fiber.Fiber<void, never>;\n\t  };\n\nexport type SnapshotCaptureTaskState =\n\t| { readonly tag: 'idle' }\n\t| { readonly tag: 'starting'; readonly token: number; readonly snapshotId: string | null }\n\t| {\n\t\t\treadonly tag: 'running';\n\t\t\treadonly token: number;\n\t\t\treadonly snapshotId: string | null;\n\t\t\treadonly fiber: Fiber.Fiber<void, never>;\n\t  };\n\nexport interface SupervisorCommandHandlerContext {\n\treadonly publish: (event: EngineEvent) => Effect.Effect<void, never, never>;\n}\n\nexport type SupervisorCommandHandler = (\n\tcmd: EngineCommand,\n\tctx: SupervisorCommandHandlerContext,\n) => Effect.Effect<ReadonlyArray<EngineEvent>, unknown, never>;\n\nexport interface SupervisorPostAcquireContext {\n\treadonly graph: ResolvedGraph;\n\treadonly registry: PluginRegistry;\n\treadonly identity: Identity;\n\treadonly runtimeRoot: string;\n}\n\nexport type SupervisorPostAcquireHook = (\n\tctx: SupervisorPostAcquireContext,\n) => Effect.Effect<ReadonlyArray<EngineEvent>, unknown, never>;\n\nexport interface CommandSubmission {\n\treadonly command: EngineCommand;\n\treadonly completion: Deferred.Deferred<Exit.Exit<void, unknown>>;\n}\n\nexport type QueuedCommand =\n\t| { readonly kind: 'fire-and-forget'; readonly command: EngineCommand }\n\t| { readonly kind: 'submitted'; readonly submission: CommandSubmission };\n\n/**\n * True when every node in `graph` has reached a `ready`-or-terminal\n * lifecycle status. Used by the command-loop to gate the post-acquire\n * hook after a (selective) restart and by the initial-acquire path to\n * decide whether to transition the cycle phase to `running`.\n *\n * Failed status reads collapse to `'failed'` so a transient registry\n * error doesn't block the readiness gate forever.\n */\nexport const allReadyOrTerminal = (\n\tgraph: ResolvedGraph,\n\tregistry: PluginRegistry,\n): Effect.Effect<boolean, never, never> =>\n\tEffect.gen(function* () {\n\t\tfor (const key of graph.nodes.keys()) {\n\t\t\tconst status = yield* registry\n\t\t\t\t.getStatus(key)\n\t\t\t\t.pipe(Effect.catch(() => Effect.succeed<LifecycleStatus>('failed')));\n\t\t\tif (!isReadyOrTerminal(status)) return false;\n\t\t}\n\t\treturn true;\n\t});\n\n/**\n * The shared-state record threaded through command-loop, background\n * tasks, and shutdown. Built once at the top of `startSupervisor`.\n */\nexport interface SupervisorState {\n\treadonly graph: ResolvedGraph;\n\treadonly registry: PluginRegistry;\n\treadonly ref: SubscriptionRef.SubscriptionRef<SubscribableState>;\n\treadonly hub: Queue.Enqueue<EngineEvent>;\n\treadonly queuedCommands: Queue.Dequeue<QueuedCommand>;\n\treadonly stackRestartTask: Ref.Ref<StackRestartTaskState>;\n\treadonly stackRestartSeq: Ref.Ref<number>;\n\treadonly snapshotCaptureTask: Ref.Ref<SnapshotCaptureTaskState>;\n\treadonly snapshotCaptureSeq: Ref.Ref<number>;\n\treadonly shutdownLatch: Ref.Ref<boolean>;\n\treadonly shutdownComplete: Deferred.Deferred<void>;\n\treadonly pluginContext: Context.Context<never>;\n\treadonly sinks: CapabilitySinksShape;\n\treadonly logger: LoggerShape;\n\treadonly identity: Identity;\n\treadonly runtimeRoot: string;\n\treadonly commandHandler?: SupervisorCommandHandler;\n\treadonly postAcquireHook?: SupervisorPostAcquireHook;\n}\n"],"mappings":";;;;;;;;;;;;;;AAwFA,MAAa,sBACZ,OACA,aAEA,OAAO,IAAI,aAAa;AACvB,MAAK,MAAM,OAAO,MAAM,MAAM,MAAM,CAInC,KAAI,CAAC,kBAAkB,OAHD,SACpB,UAAU,IAAI,CACd,KAAK,OAAO,YAAY,OAAO,QAAyB,SAAS,CAAC,CAAC,CACvC,CAAE,QAAO;AAExC,QAAO;EACN"}

package/dist/substrate/runtime/supervisor/teardown.mjs

@@ -0,0 +1,57 @@
+import "../capability-sinks/index.mjs";
+import { planRestart } from "../lifecycle/selective-restart.mjs";
+import "../lifecycle/index.mjs";
+import { bestEffort, publish } from "./wiring.mjs";
+import { acquireKeys } from "./acquire-node.mjs";
+import { Effect, Exit, Scope } from "effect";
+//#region src/substrate/runtime/supervisor/teardown.ts
+/**
+* Tear down a slice in reverse-dep order, parallel within each level.
+* Each node's scope close runs its finalizers; status transitions
+* `ready → stopping → stopped` are emitted.
+*
+* Architecture § Stack lifecycle: "shutdown.requested → parallel
+* teardown (max grace, not sum grace)".
+*/
+const teardownKeys = (graph, registry, keys) => Effect.gen(function* () {
+	const byLevel = graph.levels.map(() => []);
+	const keySet = new Set(keys);
+	for (let i = 0; i < graph.levels.length; i++) for (const key of graph.levels[i]) if (keySet.has(key)) byLevel[i].push(key);
+	for (let i = byLevel.length - 1; i >= 0; i--) {
+		const level = byLevel[i];
+		if (level.length === 0) continue;
+		yield* Effect.all(level.map((key) => teardownNode(registry, key)), {
+			concurrency: "unbounded",
+			discard: true
+		});
+	}
+}).pipe(Effect.withSpan("lifecycle.supervisor.teardownKeys"));
+const teardownNode = (registry, key) => Effect.gen(function* () {
+	const entry = registry.entries.get(key);
+	if (entry === void 0) return;
+	const status = yield* registry.getStatus(key).pipe(Effect.catch(() => Effect.succeed("pending")));
+	if (status === "ready") yield* bestEffort(registry.transition(key, "stopping"));
+	yield* Scope.close(entry.scope, Exit.void).pipe(Effect.catch(() => Effect.void));
+	if (status === "ready") yield* bestEffort(registry.transition(key, "stopped"));
+}).pipe(Effect.withSpan("lifecycle.supervisor.teardownNode"));
+const doSelectiveRestart = (graph, registry, ref, hub, roots, pluginContext, sinks, logger, identity, runtimeRoot, parentScope) => Effect.gen(function* () {
+	const plan = yield* planRestart(graph, roots);
+	const at = Date.now();
+	for (const root of roots) yield* publish(ref, hub, {
+		tag: "restart.requested",
+		target: { pluginKey: root },
+		at
+	});
+	yield* teardownKeys(graph, registry, plan.teardownOrder);
+	for (const key of plan.acquireOrder) yield* registry.resetForRestart(key, parentScope).pipe(Effect.catch(() => Effect.void));
+	yield* acquireKeys(registry, plan.acquireOrder, ref, hub, pluginContext, sinks, logger, identity, runtimeRoot);
+	for (const root of roots) yield* publish(ref, hub, {
+		tag: "restart.completed",
+		target: { pluginKey: root },
+		at: Date.now()
+	});
+}).pipe(Effect.withSpan("lifecycle.supervisor.selectiveRestart"));
+//#endregion
+export { doSelectiveRestart, teardownKeys };
+
+//# sourceMappingURL=teardown.mjs.map

package/dist/substrate/runtime/supervisor/teardown.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"teardown.mjs","names":[],"sources":["../../../../src/substrate/runtime/supervisor/teardown.ts"],"sourcesContent":["// Teardown + selective restart.\n//\n// Plugin scopes close in reverse-dep order, parallel within each level\n// (max grace, not sum grace, per architecture § Stack lifecycle).\n// Selective restart tears a slice down then re-acquires it in\n// dependency order, reusing the per-node acquire pipeline.\n\nimport { Context, Effect, Exit, Queue, Scope, SubscriptionRef } from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport type { EngineEvent } from '../../events.ts';\nimport type { Identity } from '../../identity.ts';\nimport type { LifecycleStatus } from '../../lifecycle.ts';\nimport type { SubscribableState } from '../../projection.ts';\nimport { type CapabilitySinksShape } from '../capability-sinks/index.ts';\nimport type { LoggerShape } from '../observability/index.ts';\nimport {\n\tplanRestart,\n\ttype PluginRegistry,\n\ttype ResolvedGraph,\n\ttype RestartTargetMissing,\n} from '../lifecycle/index.ts';\nimport { acquireKeys } from './acquire-node.ts';\nimport { bestEffort, publish } from './wiring.ts';\n\n// -----------------------------------------------------------------------------\n// Teardown\n// -----------------------------------------------------------------------------\n\n/**\n * Tear down a slice in reverse-dep order, parallel within each level.\n * Each node's scope close runs its finalizers; status transitions\n * `ready → stopping → stopped` are emitted.\n *\n * Architecture § Stack lifecycle: \"shutdown.requested → parallel\n * teardown (max grace, not sum grace)\".\n */\nexport const teardownKeys = (\n\tgraph: ResolvedGraph,\n\tregistry: PluginRegistry,\n\tkeys: ReadonlyArray<PluginKey>,\n): Effect.Effect<void, never, never> =>\n\tEffect.gen(function* () {\n\t\tconst byLevel: Array<Array<PluginKey>> = graph.levels.map(() => []);\n\t\tconst keySet = new Set(keys);\n\t\tfor (let i = 0; i < graph.levels.length; i++) {\n\t\t\tfor (const key of graph.levels[i]!) {\n\t\t\t\tif (keySet.has(key)) byLevel[i]!.push(key);\n\t\t\t}\n\t\t}\n\t\tfor (let i = byLevel.length - 1; i >= 0; i--) {\n\t\t\tconst level = byLevel[i]!;\n\t\t\tif (level.length === 0) continue;\n\t\t\tyield* Effect.all(\n\t\t\t\tlevel.map((key) => teardownNode(registry, key)),\n\t\t\t\t{ concurrency: 'unbounded', discard: true },\n\t\t\t);\n\t\t}\n\t}).pipe(Effect.withSpan('lifecycle.supervisor.teardownKeys'));\n\nexport const teardownNode = (\n\tregistry: PluginRegistry,\n\tkey: PluginKey,\n): Effect.Effect<void, never, never> =>\n\tEffect.gen(function* () {\n\t\tconst entry = registry.entries.get(key);\n\t\tif (entry === undefined) return;\n\t\tconst status = yield* registry\n\t\t\t.getStatus(key)\n\t\t\t.pipe(Effect.catch(() => Effect.succeed<LifecycleStatus>('pending')));\n\t\t// Only `ready` plugins need stopping. `acquiring` plugins are\n\t\t// interrupted by the scope close. `failed` / `stopped` / `done`\n\t\t// are no-ops. `status` is a snapshot read above, so a concurrent\n\t\t// off-table move (e.g. a racing restart driving the node to\n\t\t// `failed`) can make `transition` hit `assertTransition` and\n\t\t// `Effect.die` — `bestEffort` (Effect.exit) swallows that defect\n\t\t// as well as the typed channel, keeping teardown's unbounded\n\t\t// fan-out from bubbling an unguarded die through the scope-close\n\t\t// finalizer.\n\t\tif (status === 'ready') {\n\t\t\tyield* bestEffort(registry.transition(key, 'stopping'));\n\t\t}\n\t\tyield* Scope.close(entry.scope, Exit.void).pipe(Effect.catch(() => Effect.void));\n\t\tif (status === 'ready') {\n\t\t\tyield* bestEffort(registry.transition(key, 'stopped'));\n\t\t}\n\t}).pipe(Effect.withSpan('lifecycle.supervisor.teardownNode'));\n\n// -----------------------------------------------------------------------------\n// Selective restart\n// -----------------------------------------------------------------------------\n\nexport const doSelectiveRestart = (\n\tgraph: ResolvedGraph,\n\tregistry: PluginRegistry,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n\troots: ReadonlySet<PluginKey>,\n\tpluginContext: Context.Context<never>,\n\tsinks: CapabilitySinksShape,\n\tlogger: LoggerShape,\n\tidentity: Identity,\n\truntimeRoot: string,\n\tparentScope: Scope.Scope,\n): Effect.Effect<void, RestartTargetMissing> =>\n\tEffect.gen(function* () {\n\t\tconst plan = yield* planRestart(graph, roots);\n\t\tconst at = Date.now();\n\t\tfor (const root of roots) {\n\t\t\tyield* publish(ref, hub, {\n\t\t\t\ttag: 'restart.requested',\n\t\t\t\ttarget: { pluginKey: root },\n\t\t\t\tat,\n\t\t\t});\n\t\t}\n\t\tyield* teardownKeys(graph, registry, plan.teardownOrder);\n\t\t// Re-acquire the slice in parallel. Each node waits on its own\n\t\t// upstream ready gate, so a downstream node in the slice can't\n\t\t// acquire until its upstream is back to `ready`; unrelated\n\t\t// siblings do not act as a level barrier. Nodes outside the\n\t\t// slice are already `ready`. `resetForRestart` rebuilds each\n\t\t// node's scope + ready gate AND authoritatively resets its\n\t\t// status to `pending` regardless of prior state (a node may\n\t\t// still be `acquiring` when its scope close interrupts it), so\n\t\t// the acquire below performs a clean `pending → acquiring`\n\t\t// transition for every slice node.\n\t\tfor (const key of plan.acquireOrder) {\n\t\t\tyield* registry.resetForRestart(key, parentScope).pipe(Effect.catch(() => Effect.void));\n\t\t}\n\t\tyield* acquireKeys(\n\t\t\tregistry,\n\t\t\tplan.acquireOrder,\n\t\t\tref,\n\t\t\thub,\n\t\t\tpluginContext,\n\t\t\tsinks,\n\t\t\tlogger,\n\t\t\tidentity,\n\t\t\truntimeRoot,\n\t\t);\n\t\tfor (const root of roots) {\n\t\t\tyield* publish(ref, hub, {\n\t\t\t\ttag: 'restart.completed',\n\t\t\t\ttarget: { pluginKey: root },\n\t\t\t\tat: Date.now(),\n\t\t\t});\n\t\t}\n\t}).pipe(Effect.withSpan('lifecycle.supervisor.selectiveRestart'));\n"],"mappings":";;;;;;;;;;;;;;;AAqCA,MAAa,gBACZ,OACA,UACA,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,UAAmC,MAAM,OAAO,UAAU,EAAE,CAAC;CACnE,MAAM,SAAS,IAAI,IAAI,KAAK;AAC5B,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,OAAO,QAAQ,IACxC,MAAK,MAAM,OAAO,MAAM,OAAO,GAC9B,KAAI,OAAO,IAAI,IAAI,CAAE,SAAQ,GAAI,KAAK,IAAI;AAG5C,MAAK,IAAI,IAAI,QAAQ,SAAS,GAAG,KAAK,GAAG,KAAK;EAC7C,MAAM,QAAQ,QAAQ;AACtB,MAAI,MAAM,WAAW,EAAG;AACxB,SAAO,OAAO,IACb,MAAM,KAAK,QAAQ,aAAa,UAAU,IAAI,CAAC,EAC/C;GAAE,aAAa;GAAa,SAAS;GAAM,CAC3C;;EAED,CAAC,KAAK,OAAO,SAAS,oCAAoC,CAAC;AAE9D,MAAa,gBACZ,UACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,QAAQ,SAAS,QAAQ,IAAI,IAAI;AACvC,KAAI,UAAU,KAAA,EAAW;CACzB,MAAM,SAAS,OAAO,SACpB,UAAU,IAAI,CACd,KAAK,OAAO,YAAY,OAAO,QAAyB,UAAU,CAAC,CAAC;AAUtE,KAAI,WAAW,QACd,QAAO,WAAW,SAAS,WAAW,KAAK,WAAW,CAAC;AAExD,QAAO,MAAM,MAAM,MAAM,OAAO,KAAK,KAAK,CAAC,KAAK,OAAO,YAAY,OAAO,KAAK,CAAC;AAChF,KAAI,WAAW,QACd,QAAO,WAAW,SAAS,WAAW,KAAK,UAAU,CAAC;EAEtD,CAAC,KAAK,OAAO,SAAS,oCAAoC,CAAC;AAM9D,MAAa,sBACZ,OACA,UACA,KACA,KACA,OACA,eACA,OACA,QACA,UACA,aACA,gBAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO,YAAY,OAAO,MAAM;CAC7C,MAAM,KAAK,KAAK,KAAK;AACrB,MAAK,MAAM,QAAQ,MAClB,QAAO,QAAQ,KAAK,KAAK;EACxB,KAAK;EACL,QAAQ,EAAE,WAAW,MAAM;EAC3B;EACA,CAAC;AAEH,QAAO,aAAa,OAAO,UAAU,KAAK,cAAc;AAWxD,MAAK,MAAM,OAAO,KAAK,aACtB,QAAO,SAAS,gBAAgB,KAAK,YAAY,CAAC,KAAK,OAAO,YAAY,OAAO,KAAK,CAAC;AAExF,QAAO,YACN,UACA,KAAK,cACL,KACA,KACA,eACA,OACA,QACA,UACA,YACA;AACD,MAAK,MAAM,QAAQ,MAClB,QAAO,QAAQ,KAAK,KAAK;EACxB,KAAK;EACL,QAAQ,EAAE,WAAW,MAAM;EAC3B,IAAI,KAAK,KAAK;EACd,CAAC;EAEF,CAAC,KAAK,OAAO,SAAS,wCAAwC,CAAC"}

package/dist/substrate/runtime/supervisor/types.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/substrate/runtime/supervisor/wiring.mjs

@@ -0,0 +1,133 @@
+import { StrategyNotFoundError } from "../errors.mjs";
+import { serviceKeyFor } from "../observability/log-store.mjs";
+import "../observability/index.mjs";
+import { updateRef } from "../projection/update.mjs";
+import { Context, Effect, Option, Queue, SubscriptionRef } from "effect";
+//#region src/substrate/runtime/supervisor/wiring.ts
+/**
+* Swallow BOTH the typed failure and any defect of a best-effort
+* effect, discarding its outcome. Lifecycle mutations
+* (`registry.transition` / `markReady` / `markFailed`) validate against
+* the transition table via `assertTransition`, which `Effect.die`s (a
+* DEFECT, not a typed failure) on an off-table move — reachable when a
+* concurrent selective-restart races an in-flight acquire. `Effect.catch`
+* only intercepts the typed `E` channel, so a die would escape and bubble
+* unguarded through the unbounded acquire fan-out (supervisor wedge).
+* `Effect.exit` captures failure AND defect into an `Exit` we discard,
+* keeping these mutations genuinely best-effort.
+*/
+const bestEffort = (effect) => Effect.exit(effect);
+/**
+* Read an optional service from a `Context.Context<never>` or fall back
+* to a default. The supervisor's `pluginContext` is name-blind: a
+* caller may or may not have layered a `Logger`, `RuntimeRoot`, or
+* `CapabilitySinksService`. The lookup pattern was open-coded in three
+* sites until backlog #40 lifted it here.
+*
+* Two surfaces, mirroring the prior `getOrDefault` / `getOrDefaultEffect`
+* helpers:
+*
+* - `read(ctx)` — value fallback (Logger, RuntimeRoot).
+* - `readEffect(ctx)` — Effect fallback so the substrate only pays the
+*   "build the default Layer" cost when nothing is in context
+*   (CapabilitySinksService).
+*
+* Upstream-watch (Phase 5 reviewer): Effect v4 exposes `Context.getOption`
+* (returns `Option<S>`) and `Context.getUnsafe` (throws on missing), but
+* NO `getOptionUnchecked`-style variant that returns `Option<S>` over a
+* `Context<never>` without the typed cast we perform here. The wrapper
+* stays until upstream adds an unchecked optional getter — at which
+* point the body collapses to a thin alias.
+*/
+const OptionalService = (tag) => ({
+	read: (ctx, fallback) => {
+		const opt = Context.getOption(ctx, tag);
+		return Option.isSome(opt) ? opt.value : fallback;
+	},
+	readEffect: (ctx, fallback) => {
+		const opt = Context.getOption(ctx, tag);
+		return Option.isSome(opt) ? Effect.succeed(opt.value) : fallback;
+	}
+});
+/** Fallback used when the supervisor's `pluginContext` doesn't carry a
+*  Logger service. Swallows every line — the trade-off is that bare
+*  `supervise()` smoke tests stay log-free, while the wired CLI / e2e
+*  layer stack picks up the real Logger. */
+const noopLogger = {
+	log: () => Effect.void,
+	readTag: () => Effect.succeed({
+		lines: [],
+		truncated: false
+	}),
+	readAll: Effect.succeed(/* @__PURE__ */ new Map()),
+	clearTag: () => Effect.void
+};
+const noopStrategyRegistry = {
+	get: (key) => Effect.fail(new StrategyNotFoundError({
+		capabilityKey: key,
+		registeredKeys: []
+	})),
+	list: () => Effect.succeed([]),
+	register: () => Effect.void
+};
+/** Publishing helper: writes the event to the projection ref AND
+*  enqueues it onto the live event hub for renderers that subscribe to
+*  the raw stream. */
+const publish = (ref, hub, event) => Effect.gen(function* () {
+	yield* updateRef(ref, event);
+	yield* Queue.offer(hub, event);
+});
+const setCyclePhase = (ref, phase) => SubscriptionRef.update(ref, (state) => ({
+	...state,
+	cycle: {
+		...state.cycle,
+		startedAt: state.cycle.startedAt === 0 ? Date.now() : state.cycle.startedAt,
+		phase
+	}
+}));
+const projectionLevel = (level) => {
+	switch (level) {
+		case "trace":
+		case "debug": return null;
+		case "info": return "info";
+		case "warn": return "warn";
+		case "error":
+		case "fatal": return "error";
+		default: return "info";
+	}
+};
+const withEventPublishingLogger = (base, ref, hub, logStore = null) => ({
+	...base,
+	log: (tag, pluginKey, payload) => Effect.gen(function* () {
+		yield* base.log(tag, pluginKey, payload);
+		if (logStore !== null) yield* logStore.append({
+			level: payload.level,
+			service: serviceKeyFor(tag, pluginKey),
+			message: payload.message,
+			fields: payload.fields
+		});
+		if (pluginKey === null) return;
+		const level = projectionLevel(payload.level);
+		if (level === null) return;
+		yield* publish(ref, hub, {
+			tag: "log.appended",
+			pluginKey,
+			line: payload.message,
+			level,
+			at: Date.now()
+		});
+	})
+});
+/** Build the registry's `onTransition` callback — turns status changes
+*  into typed events. */
+const buildTransitionEmitter = (ref, hub) => (key, from, to) => publish(ref, hub, {
+	tag: "lifecycle.statusChanged",
+	pluginKey: key,
+	from,
+	to,
+	at: Date.now()
+});
+//#endregion
+export { OptionalService, bestEffort, buildTransitionEmitter, noopLogger, noopStrategyRegistry, publish, setCyclePhase, withEventPublishingLogger };
+
+//# sourceMappingURL=wiring.mjs.map

package/dist/substrate/runtime/supervisor/wiring.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.mjs","names":[],"sources":["../../../../src/substrate/runtime/supervisor/wiring.ts"],"sourcesContent":["// Supervisor wiring helpers.\n//\n// Tiny support module for the supervisor's substrate-wiring concerns:\n// fallback Logger, fallback StrategyRegistry, event publishing helpers,\n// projection-level mapping, the transition emitter builder, and the\n// OptionalService<T> helper that centralises the \"look up an optional\n// service in pluginContext, fall back if absent\" pattern endemic to\n// the supervisor boundary.\n//\n// Split out of the monolith per backlog #38 + #40.\n\nimport { Context, Effect, type Exit, Option, Queue, SubscriptionRef } from 'effect';\n\nimport type { StrategyRegistry } from '../../../contracts/strategy-contributor.ts';\nimport type { PluginKey } from '../../brand.ts';\nimport type { EngineEvent } from '../../events.ts';\nimport type { LifecycleStatus } from '../../lifecycle.ts';\nimport type { SubscribableState } from '../../projection.ts';\nimport { StrategyNotFoundError } from '../errors.ts';\nimport type { LoggerShape, LogStoreShape } from '../observability/index.ts';\nimport { serviceKeyFor } from '../observability/index.ts';\nimport { updateRef } from '../projection/update.ts';\n\n// -----------------------------------------------------------------------------\n// Best-effort lifecycle mutation\n// -----------------------------------------------------------------------------\n\n/**\n * Swallow BOTH the typed failure and any defect of a best-effort\n * effect, discarding its outcome. Lifecycle mutations\n * (`registry.transition` / `markReady` / `markFailed`) validate against\n * the transition table via `assertTransition`, which `Effect.die`s (a\n * DEFECT, not a typed failure) on an off-table move — reachable when a\n * concurrent selective-restart races an in-flight acquire. `Effect.catch`\n * only intercepts the typed `E` channel, so a die would escape and bubble\n * unguarded through the unbounded acquire fan-out (supervisor wedge).\n * `Effect.exit` captures failure AND defect into an `Exit` we discard,\n * keeping these mutations genuinely best-effort.\n */\nexport const bestEffort = <A, E, R>(\n\teffect: Effect.Effect<A, E, R>,\n): Effect.Effect<Exit.Exit<A, E>, never, R> => Effect.exit(effect);\n\n// -----------------------------------------------------------------------------\n// OptionalService<T> — substrate-wide \"service-or-default\" helper\n// -----------------------------------------------------------------------------\n\n/**\n * Read an optional service from a `Context.Context<never>` or fall back\n * to a default. The supervisor's `pluginContext` is name-blind: a\n * caller may or may not have layered a `Logger`, `RuntimeRoot`, or\n * `CapabilitySinksService`. The lookup pattern was open-coded in three\n * sites until backlog #40 lifted it here.\n *\n * Two surfaces, mirroring the prior `getOrDefault` / `getOrDefaultEffect`\n * helpers:\n *\n * - `read(ctx)` — value fallback (Logger, RuntimeRoot).\n * - `readEffect(ctx)` — Effect fallback so the substrate only pays the\n *   \"build the default Layer\" cost when nothing is in context\n *   (CapabilitySinksService).\n *\n * Upstream-watch (Phase 5 reviewer): Effect v4 exposes `Context.getOption`\n * (returns `Option<S>`) and `Context.getUnsafe` (throws on missing), but\n * NO `getOptionUnchecked`-style variant that returns `Option<S>` over a\n * `Context<never>` without the typed cast we perform here. The wrapper\n * stays until upstream adds an unchecked optional getter — at which\n * point the body collapses to a thin alias.\n */\nexport const OptionalService = <S, I>(tag: Context.Key<I, S>) => ({\n\tread: (ctx: Context.Context<never>, fallback: S): S => {\n\t\tconst opt = Context.getOption(ctx as Context.Context<I>, tag);\n\t\treturn Option.isSome(opt) ? opt.value : fallback;\n\t},\n\treadEffect: <E, R>(\n\t\tctx: Context.Context<never>,\n\t\tfallback: Effect.Effect<S, E, R>,\n\t): Effect.Effect<S, E, R> => {\n\t\tconst opt = Context.getOption(ctx as Context.Context<I>, tag);\n\t\treturn Option.isSome(opt) ? Effect.succeed(opt.value) : fallback;\n\t},\n});\n\n// -----------------------------------------------------------------------------\n// Fallback services for bare smoke-test `supervise()` paths\n// -----------------------------------------------------------------------------\n\n/** Fallback used when the supervisor's `pluginContext` doesn't carry a\n *  Logger service. Swallows every line — the trade-off is that bare\n *  `supervise()` smoke tests stay log-free, while the wired CLI / e2e\n *  layer stack picks up the real Logger. */\nexport const noopLogger: LoggerShape = {\n\tlog: () => Effect.void,\n\treadTag: () => Effect.succeed({ lines: [], truncated: false }),\n\treadAll: Effect.succeed(new Map()),\n\tclearTag: () => Effect.void,\n};\n\nexport const noopStrategyRegistry: StrategyRegistry = {\n\tget: (key) =>\n\t\tEffect.fail(\n\t\t\tnew StrategyNotFoundError({\n\t\t\t\tcapabilityKey: key,\n\t\t\t\tregisteredKeys: [],\n\t\t\t}),\n\t\t),\n\tlist: () => Effect.succeed([]),\n\tregister: () => Effect.void,\n};\n\n// -----------------------------------------------------------------------------\n// Event publishing\n// -----------------------------------------------------------------------------\n\n/** Publishing helper: writes the event to the projection ref AND\n *  enqueues it onto the live event hub for renderers that subscribe to\n *  the raw stream. */\nexport const publish = (\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n\tevent: EngineEvent,\n): Effect.Effect<void> =>\n\tEffect.gen(function* () {\n\t\tyield* updateRef(ref, event);\n\t\tyield* Queue.offer(hub, event);\n\t});\n\nexport const setCyclePhase = (\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\tphase: SubscribableState['cycle']['phase'],\n): Effect.Effect<void> =>\n\tSubscriptionRef.update(ref, (state) => ({\n\t\t...state,\n\t\tcycle: {\n\t\t\t...state.cycle,\n\t\t\tstartedAt: state.cycle.startedAt === 0 ? Date.now() : state.cycle.startedAt,\n\t\t\tphase,\n\t\t},\n\t}));\n\n// -----------------------------------------------------------------------------\n// Logger overlay — projects structured log lines into `log.appended`\n// -----------------------------------------------------------------------------\n\nexport const projectionLevel = (\n\tlevel: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal',\n): Extract<EngineEvent, { tag: 'log.appended' }>['level'] | null => {\n\tswitch (level) {\n\t\tcase 'trace':\n\t\tcase 'debug':\n\t\t\treturn null;\n\t\tcase 'info':\n\t\t\treturn 'info';\n\t\tcase 'warn':\n\t\t\treturn 'warn';\n\t\tcase 'error':\n\t\tcase 'fatal':\n\t\t\treturn 'error';\n\t\tdefault: {\n\t\t\tconst _exhaustive: never = level;\n\t\t\tvoid _exhaustive;\n\t\t\treturn 'info';\n\t\t}\n\t}\n};\n\nexport const withEventPublishingLogger = (\n\tbase: LoggerShape,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n\t/** Optional cross-service queryable store. Every logged line is teed\n\t *  into it (the SAME source that feeds the projection's per-row tail —\n\t *  see log-store.ts), so the dashboard's \"Logs\" tab gets a filterable\n\t *  cross-service history without a second log reader. Absent in bare\n\t *  smoke-test paths that don't wire a LogStore. */\n\tlogStore: LogStoreShape | null = null,\n): LoggerShape => ({\n\t...base,\n\tlog: (tag, pluginKey, payload) =>\n\t\tEffect.gen(function* () {\n\t\t\tyield* base.log(tag, pluginKey, payload);\n\t\t\t// Tee into the cross-service store regardless of plugin key —\n\t\t\t// the queryable surface keeps supervisor-level lines too (the\n\t\t\t// projection tail below is row-scoped, so it only takes\n\t\t\t// plugin-attributed lines).\n\t\t\tif (logStore !== null) {\n\t\t\t\tyield* logStore.append({\n\t\t\t\t\tlevel: payload.level,\n\t\t\t\t\tservice: serviceKeyFor(tag, pluginKey),\n\t\t\t\t\tmessage: payload.message,\n\t\t\t\t\tfields: payload.fields,\n\t\t\t\t});\n\t\t\t}\n\t\t\tif (pluginKey === null) return;\n\t\t\tconst level = projectionLevel(payload.level);\n\t\t\tif (level === null) return;\n\t\t\tyield* publish(ref, hub, {\n\t\t\t\ttag: 'log.appended',\n\t\t\t\tpluginKey,\n\t\t\t\tline: payload.message,\n\t\t\t\tlevel,\n\t\t\t\tat: Date.now(),\n\t\t\t});\n\t\t}),\n});\n\n// -----------------------------------------------------------------------------\n// Transition emitter\n// -----------------------------------------------------------------------------\n\n/** Build the registry's `onTransition` callback — turns status changes\n *  into typed events. */\nexport const buildTransitionEmitter =\n\t(\n\t\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\t\thub: Queue.Enqueue<EngineEvent>,\n\t): ((key: PluginKey, from: LifecycleStatus, to: LifecycleStatus) => Effect.Effect<void>) =>\n\t(key, from, to) =>\n\t\tpublish(ref, hub, {\n\t\t\ttag: 'lifecycle.statusChanged',\n\t\t\tpluginKey: key,\n\t\t\tfrom,\n\t\t\tto,\n\t\t\tat: Date.now(),\n\t\t});\n"],"mappings":";;;;;;;;;;;;;;;;;;AAuCA,MAAa,cACZ,WAC8C,OAAO,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;AA4BlE,MAAa,mBAAyB,SAA4B;CACjE,OAAO,KAA6B,aAAmB;EACtD,MAAM,MAAM,QAAQ,UAAU,KAA2B,IAAI;AAC7D,SAAO,OAAO,OAAO,IAAI,GAAG,IAAI,QAAQ;;CAEzC,aACC,KACA,aAC4B;EAC5B,MAAM,MAAM,QAAQ,UAAU,KAA2B,IAAI;AAC7D,SAAO,OAAO,OAAO,IAAI,GAAG,OAAO,QAAQ,IAAI,MAAM,GAAG;;CAEzD;;;;;AAUD,MAAa,aAA0B;CACtC,WAAW,OAAO;CAClB,eAAe,OAAO,QAAQ;EAAE,OAAO,EAAE;EAAE,WAAW;EAAO,CAAC;CAC9D,SAAS,OAAO,wBAAQ,IAAI,KAAK,CAAC;CAClC,gBAAgB,OAAO;CACvB;AAED,MAAa,uBAAyC;CACrD,MAAM,QACL,OAAO,KACN,IAAI,sBAAsB;EACzB,eAAe;EACf,gBAAgB,EAAE;EAClB,CAAC,CACF;CACF,YAAY,OAAO,QAAQ,EAAE,CAAC;CAC9B,gBAAgB,OAAO;CACvB;;;;AASD,MAAa,WACZ,KACA,KACA,UAEA,OAAO,IAAI,aAAa;AACvB,QAAO,UAAU,KAAK,MAAM;AAC5B,QAAO,MAAM,MAAM,KAAK,MAAM;EAC7B;AAEH,MAAa,iBACZ,KACA,UAEA,gBAAgB,OAAO,MAAM,WAAW;CACvC,GAAG;CACH,OAAO;EACN,GAAG,MAAM;EACT,WAAW,MAAM,MAAM,cAAc,IAAI,KAAK,KAAK,GAAG,MAAM,MAAM;EAClE;EACA;CACD,EAAE;AAMJ,MAAa,mBACZ,UACmE;AACnE,SAAQ,OAAR;EACC,KAAK;EACL,KAAK,QACJ,QAAO;EACR,KAAK,OACJ,QAAO;EACR,KAAK,OACJ,QAAO;EACR,KAAK;EACL,KAAK,QACJ,QAAO;EACR,QAGC,QAAO;;;AAKV,MAAa,6BACZ,MACA,KACA,KAMA,WAAiC,UACf;CAClB,GAAG;CACH,MAAM,KAAK,WAAW,YACrB,OAAO,IAAI,aAAa;AACvB,SAAO,KAAK,IAAI,KAAK,WAAW,QAAQ;AAKxC,MAAI,aAAa,KAChB,QAAO,SAAS,OAAO;GACtB,OAAO,QAAQ;GACf,SAAS,cAAc,KAAK,UAAU;GACtC,SAAS,QAAQ;GACjB,QAAQ,QAAQ;GAChB,CAAC;AAEH,MAAI,cAAc,KAAM;EACxB,MAAM,QAAQ,gBAAgB,QAAQ,MAAM;AAC5C,MAAI,UAAU,KAAM;AACpB,SAAO,QAAQ,KAAK,KAAK;GACxB,KAAK;GACL;GACA,MAAM,QAAQ;GACd;GACA,IAAI,KAAK,KAAK;GACd,CAAC;GACD;CACH;;;AAQD,MAAa,0BAEX,KACA,SAEA,KAAK,MAAM,OACX,QAAQ,KAAK,KAAK;CACjB,KAAK;CACL,WAAW;CACX;CACA;CACA,IAAI,KAAK,KAAK;CACd,CAAC"}

package/dist/substrate/runtime/typed-env.mjs

@@ -0,0 +1,8 @@
+//#region src/substrate/runtime/typed-env.ts
+const readEnv = (name) => {
+	return globalThis.process?.env?.[name];
+};
+//#endregion
+export { readEnv };
+
+//# sourceMappingURL=typed-env.mjs.map

package/dist/substrate/runtime/typed-env.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-env.mjs","names":[],"sources":["../../../src/substrate/runtime/typed-env.ts"],"sourcesContent":["// Typed `process.env` accessor.\n//\n// The devstack package is consumed from both Node and browser-like\n// runtimes (Playwright fixtures, vitest browser mode), so we can't\n// reach for `process.env` directly — TypeScript with `\"types\": []`\n// rejects the global. Callers used to inline a one-off\n// `globalThis as { process?: { env?: ... } }` cast every time they\n// needed to read an env var. This centralises the cast so the rest of\n// the code reads `readEnv('FOO')` cleanly.\n//\n// Returns `undefined` when the runtime has no `process.env` (browser),\n// or when the env var is unset. Callers treat `undefined` and `''` as\n// equivalent \"absent\" sentinels.\n\nexport const readEnv = (name: string): string | undefined => {\n\tconst process = (\n\t\tglobalThis as { process?: { env?: Record<string, string | undefined> } }\n\t).process;\n\treturn process?.env?.[name];\n};\n"],"mappings":";AAcA,MAAa,WAAW,SAAqC;AAI5D,QAFC,WACC,SACc,MAAM"}

package/dist/substrate/state-store.d.mts

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

package/dist/substrate/versioned-doc-schema.mjs

@@ -0,0 +1,17 @@
+import { Schema } from "effect";
+//#region src/substrate/versioned-doc-schema.ts
+/** Construct a versioned cross-process document schema —
+*  `{ version: Literal<N>, ...payloadFields }` in one call.
+*
+*  The resulting schema is structurally identical to a hand-written
+*  `Schema.Struct({ version: Schema.Literal(N), ...payload })`; the
+*  `version` field becomes a literal-typed discriminator suitable for
+*  forward-compatible `Schema.Union`s. */
+const versionedDocSchema = (version, payload) => Schema.Struct({
+	version: Schema.Literal(version),
+	...payload
+});
+//#endregion
+export { versionedDocSchema };
+
+//# sourceMappingURL=versioned-doc-schema.mjs.map

package/dist/substrate/versioned-doc-schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-doc-schema.mjs","names":[],"sources":["../../src/substrate/versioned-doc-schema.ts"],"sourcesContent":["// Versioned cross-process document schema helper.\n//\n// Centralizes the `{ version: Literal<N>, ...payload }` discriminator\n// shape that every cross-process document the substrate persists shares\n// (roster, container claim, snapshot reservation, port reservation).\n//\n// Future v2 migration becomes mechanical: replace the call with\n// `Schema.Union(versionedDocSchema(1, ...), versionedDocSchema(2, ...))`\n// at exactly one site per document, rather than hand-rolling the\n// discriminator field in each consumer.\n//\n// Lives at substrate L0 (depends only on `effect`'s Schema) so L0\n// declarations such as `substrate/cross-process.ts` can use it without\n// reaching into the L1 runtime tree.\n\nimport { Schema } from 'effect';\n\n/** Construct a versioned cross-process document schema —\n *  `{ version: Literal<N>, ...payloadFields }` in one call.\n *\n *  The resulting schema is structurally identical to a hand-written\n *  `Schema.Struct({ version: Schema.Literal(N), ...payload })`; the\n *  `version` field becomes a literal-typed discriminator suitable for\n *  forward-compatible `Schema.Union`s. */\nexport const versionedDocSchema = <const V extends number, Fields extends Schema.Struct.Fields>(\n\tversion: V,\n\tpayload: Fields,\n): Schema.Struct<{ readonly version: Schema.Literal<V> } & Fields> =>\n\t// Cast is load-bearing: spreading a generic `Fields` into an object\n\t// literal makes TS infer the resulting `Schema.Struct` over a widened\n\t// field type, not the precise `{ version } & Fields` intersection, so\n\t// the literal-typed `version` discriminator would be lost without it.\n\tSchema.Struct({\n\t\tversion: Schema.Literal(version),\n\t\t...payload,\n\t}) as unknown as Schema.Struct<{ readonly version: Schema.Literal<V> } & Fields>;\n"],"mappings":";;;;;;;;;AAwBA,MAAa,sBACZ,SACA,YAMA,OAAO,OAAO;CACb,SAAS,OAAO,QAAQ,QAAQ;CAChC,GAAG;CACH,CAAC"}