@mysten-incubation/devstack 0.0.0

package/dist/substrate/runtime/supervisor.mjs

@@ -0,0 +1,831 @@
+import { resolvePluginDependencies } from "../plugin.mjs";
+import { RuntimeRoot } from "./paths.mjs";
+import { annotateOp, annotatePhase, withPluginSpan, withStackSpan } from "./observability/spans.mjs";
+import { CurrentPluginKey, CurrentPluginProgress } from "./current-plugin.mjs";
+import { Logger as Logger$1 } from "./observability/logger.mjs";
+import { prettyErrorStructured } from "./observability/pretty-error.mjs";
+import { declareAccount, setIdentity, updateRef } from "./projection/update.mjs";
+import { StrategyRegistryService } from "./strategy-registry/service.mjs";
+import { isReadyOrTerminal } from "./lifecycle/state-machine.mjs";
+import { resolveGraph } from "./lifecycle/dep-graph.mjs";
+import { buildDependencyReaderFor, makeEntry, makeRegistry } from "./lifecycle/plugin-registry.mjs";
+import { awaitUpstreams } from "./lifecycle/ready-gate.mjs";
+import { buildWatchIndex, exactPrefixMatch } from "./lifecycle/watch-attribution.mjs";
+import { planFullDrain, planRestart } from "./lifecycle/selective-restart.mjs";
+import { installSignalHandler } from "./lifecycle/signals.mjs";
+import { PostAcquireTaskFailed } from "./post-acquire-tasks.mjs";
+import { CapabilitySinksService } from "./capability-sinks/service.mjs";
+import { layerCapabilitySinksDefault } from "./capability-sinks/layer.mjs";
+import { getOrDefault, getOrDefaultEffect } from "./context-helpers.mjs";
+import { operationalEndpointEventsFromResolvedValue } from "./projection/operational-endpoints.mjs";
+import { Cause, Context, Data, Deferred, Effect, Exit, Fiber, Layer, Queue, Ref, Scope, SubscriptionRef } from "effect";
+//#region src/substrate/runtime/supervisor.ts
+var SupervisorBootError = class extends Data.TaggedError("SupervisorBootError") {};
+var SupervisorPostAcquireFailed = class extends Data.TaggedError("SupervisorPostAcquireFailed") {};
+var CapabilityFactoryFailed = class extends Data.TaggedError("CapabilityFactoryFailed") {};
+/** 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 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) => ({
+	...base,
+	log: (tag, pluginKey, payload) => Effect.gen(function* () {
+		yield* base.log(tag, pluginKey, payload);
+		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()
+		});
+	})
+});
+const noopStrategyRegistry = {
+	get: (key) => Effect.fail({
+		_tag: "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
+	}
+}));
+/** 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()
+});
+const buildRegistry = (graph, parentScope, emit) => Effect.gen(function* () {
+	const entries = /* @__PURE__ */ new Map();
+	for (const [key, node] of graph.nodes) {
+		const entry = yield* makeEntry(node, parentScope);
+		entries.set(key, entry);
+	}
+	return makeRegistry(entries, emit);
+});
+/**
+* Resolve a plugin's `capabilities` field to a concrete decl tuple.
+*
+* Two accepted shapes (see `Plugin.capabilities` for the
+* authoring-side contract):
+*
+*   (a) Static — a plain `ReadonlyArray<CapabilityDecl>`. Returned
+*       as-is.
+*
+*   (b) Dynamic — a `CapabilitiesFactory<…>` function. Invoked with
+*       the resolved plugin value + the acquire context built from
+*       the supervisor's identity + runtime root. The function is
+*       called once per acquire (post-success); the returned tuple
+*       flows into `dispatchContributions` like a static one.
+*
+* The dynamic seam exists so plugins' snapshot subtrees, codegen
+* bindings, routable URLs, strategy contributions, etc. can stamp
+* the REAL chain id / package id / network alias produced by their
+* acquire body, instead of the factory-time placeholder strings the
+* static form forces.
+*
+* The substrate stays generic: this resolver doesn't know any
+* service name; the discrimination is purely structural
+* (`typeof === 'function'`).
+*/
+const resolveCapabilities = (pluginKey, field, resolved, acquireContext) => {
+	if (field === void 0) return Effect.succeed([]);
+	if (typeof field === "function") return Effect.try({
+		try: () => field(resolved, acquireContext),
+		catch: (cause) => new CapabilityFactoryFailed({
+			pluginKey,
+			message: `capability factory failed for ${pluginKey}`,
+			cause
+		})
+	});
+	return Effect.succeed(field);
+};
+/**
+* Walk a plugin's `capabilities` tuple + `errorContributions` after a
+* successful acquire, route every contribution through the
+* substrate-owned `CapabilitySinksService`. The plugin's scope is
+* provided so each sink's `addFinalizer` lands on the plugin's scope —
+* registrations reap on selective-restart / shutdown.
+*
+* The supervisor stays kind-blind: it builds the contribution union
+* (`{source: 'capability'|'error', ...}`) and the dispatch happens
+* inside the service. Unknown kinds are downgraded to no-ops here so
+* the substrate-open-by-default contract holds — plugin authors can
+* emit a custom-kind decl that is observed only by the orchestrators
+* that registered the matching sink.
+*/
+const dispatchContributions = (pluginKey, capabilities, errorContributions, pluginRole, identity, pluginContext, pluginScope, sinks, ref, hub) => Effect.gen(function* () {
+	const strategyRegistry = getOrDefault(pluginContext, StrategyRegistryService, noopStrategyRegistry);
+	const harvestCtx = {
+		pluginKey,
+		identity,
+		publish: (event) => publish(ref, hub, event),
+		registerStrategy: (decl) => strategyRegistry.register(decl.capabilityKey, decl.strategy, {
+			autoMounted: decl.autoMounted,
+			...decl.priority === void 0 ? {} : { priority: decl.priority }
+		})
+	};
+	const items = [...capabilities.map((decl) => ({
+		source: "capability",
+		decl
+	})), ...errorContributions.map((contribution) => ({
+		source: "error",
+		contribution
+	}))];
+	for (const item of items) {
+		const dispatch = sinks.dispatch(item, harvestCtx).pipe(Effect.catchTag("UnknownContributionKind", () => Effect.void));
+		yield* Scope.provide(dispatch, pluginScope);
+	}
+}).pipe(withPluginSpan("lifecycle.supervisor.dispatchContributions", {
+	app: identity.app,
+	stack: identity.stack,
+	network: identity.chain,
+	pluginKey,
+	role: pluginRole
+}));
+/**
+* Run one node's `start` under its own scope. Steps:
+*  1. Await upstreams (their ready-gates).
+*  2. Transition `pending → acquiring` (publishes the event).
+*  3. Build resolved dependency values from declared resource refs.
+*  4. Run the plugin's `start` Effect inside the entry's Scope,
+*     after providing the substrate-context services bundle so the
+*     plugin's R-channel yields (`IdentityContext`,
+*     `ContainerRuntimeService`, etc.) resolve to live instances.
+*  5. On success: stash the resolved value + `markReady` (publishes
+*     the `ready` transition).
+*  6. On failure: `markFailed` (publishes the `failed` transition, fails
+*     the deferred so downstream consumers short-circuit).
+*
+* Errors are caught and stashed onto the registry entry — the outer
+* scheduler doesn't propagate per-plugin failures; ready-gate failure
+* propagation handles the downstream blocking. The supervisor's outer
+* fiber surfaces the union via `Fiber.join` when the user asks for
+* "stack ready or err".
+*/
+const acquireNode = (registry, key, ref, hub, pluginContext, sinks, logger, identity, runtimeRoot) => Effect.gen(function* () {
+	const entry = registry.entries.get(key);
+	if (entry === void 0) return;
+	if ((yield* awaitUpstreams(registry, entry.node).pipe(Effect.matchEffect({
+		onFailure: (cause) => Effect.gen(function* () {
+			yield* registry.markFailed(key, cause).pipe(Effect.catch(() => Effect.void));
+			return false;
+		}),
+		onSuccess: () => Effect.succeed(true)
+	}))) !== true) {
+		yield* logger.log(`supervisor/${key}`, key, {
+			level: "warn",
+			message: "plugin acquire skipped — upstream failed"
+		});
+		return;
+	}
+	yield* annotatePhase("acquire");
+	yield* logger.log(`supervisor/${key}`, key, {
+		level: "debug",
+		message: "plugin acquire start",
+		fields: { role: entry.node.member.role }
+	});
+	yield* registry.transition(key, "acquiring").pipe(Effect.catch(() => Effect.void));
+	const readDependency = buildDependencyReaderFor(registry, entry.node);
+	const deps = resolvePluginDependencies(entry.node.member, readDependency);
+	const start = entry.node.member.start;
+	const currentPluginContext = pluginContext.pipe(Context.add(CurrentPluginKey, { key }), Context.add(CurrentPluginProgress, { setPhase: (phase) => publish(ref, hub, {
+		tag: "lifecycle.phaseSet",
+		pluginKey: key,
+		phase,
+		at: Date.now()
+	}) }));
+	const providedAcquire = Effect.provide(start(deps), currentPluginContext);
+	const result = yield* Scope.provide(providedAcquire, entry.scope).pipe(Effect.matchEffect({
+		onFailure: (cause) => Effect.gen(function* () {
+			yield* registry.markFailed(key, cause).pipe(Effect.catch(() => Effect.void));
+			yield* publish(ref, hub, {
+				tag: "error.reported",
+				error: prettyErrorStructured(Cause.fail(cause), {
+					pluginKey: key,
+					severity: "error",
+					at: Date.now()
+				})
+			});
+			return { ok: false };
+		}),
+		onSuccess: (value) => Effect.succeed({
+			ok: true,
+			value
+		})
+	}));
+	if (result.ok) {
+		const acquireContext = {
+			identity,
+			chain: identity.chain,
+			runtimeRoot
+		};
+		const capsExit = yield* Effect.exit(resolveCapabilities(key, entry.node.member.capabilities, result.value, acquireContext));
+		if (Exit.isFailure(capsExit)) {
+			yield* registry.markFailed(key, capsExit.cause).pipe(Effect.catch(() => Effect.void));
+			yield* publish(ref, hub, {
+				tag: "error.reported",
+				error: prettyErrorStructured(capsExit.cause, {
+					pluginKey: key,
+					severity: "error",
+					at: Date.now()
+				})
+			});
+			yield* logger.log(`supervisor/${key}`, key, {
+				level: "error",
+				message: "plugin capability factory failed"
+			});
+			return;
+		}
+		const caps = capsExit.value;
+		const errorContributions = entry.node.member.errorContributions ?? [];
+		if (caps.length > 0 || errorContributions.length > 0) {
+			const dispatchExit = yield* Effect.exit(dispatchContributions(key, caps, errorContributions, entry.node.member.role, identity, pluginContext, entry.scope, sinks, ref, hub));
+			if (Exit.isFailure(dispatchExit)) {
+				yield* registry.markFailed(key, dispatchExit.cause).pipe(Effect.catch(() => Effect.void));
+				yield* publish(ref, hub, {
+					tag: "error.reported",
+					error: prettyErrorStructured(dispatchExit.cause, {
+						pluginKey: key,
+						severity: "error",
+						at: Date.now()
+					})
+				});
+				yield* logger.log(`supervisor/${key}`, key, {
+					level: "error",
+					message: "plugin capability dispatch failed"
+				});
+				return;
+			}
+		}
+		const routablesPresent = caps.some((capability) => capability.kind === "routable");
+		for (const event of operationalEndpointEventsFromResolvedValue(key, result.value, Date.now(), { routablesPresent })) yield* publish(ref, hub, event);
+		yield* publish(ref, hub, {
+			tag: "lifecycle.phaseSet",
+			pluginKey: key,
+			phase: null,
+			at: Date.now()
+		});
+		yield* registry.markReady(key, result.value).pipe(Effect.catch(() => Effect.void));
+		if (entry.node.member.role === "task") yield* registry.transition(key, "done").pipe(Effect.catch(() => Effect.void));
+		yield* logger.log(`supervisor/${key}`, key, {
+			level: "debug",
+			message: entry.node.member.role === "task" ? "plugin done" : "plugin ready",
+			fields: {
+				capabilities: caps.length,
+				errorContributions: errorContributions.length
+			}
+		});
+	} else yield* logger.log(`supervisor/${key}`, key, {
+		level: "debug",
+		message: "plugin acquire failed"
+	});
+}).pipe(withPluginSpan("lifecycle.supervisor.acquireNode", {
+	app: identity.app,
+	stack: identity.stack,
+	network: identity.chain,
+	pluginKey: key,
+	role: registry.entries.get(key)?.node.member.role ?? "service"
+}));
+const acquireKeys = (registry, keys, ref, hub, pluginContext, sinks, logger, identity, runtimeRoot) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({ "devstack.level.size": keys.length });
+	yield* Effect.all(keys.map((key) => acquireNode(registry, key, ref, hub, pluginContext, sinks, logger, identity, runtimeRoot)), {
+		concurrency: "unbounded",
+		discard: true
+	});
+}).pipe(Effect.withSpan("lifecycle.supervisor.acquireKeys"));
+const acquireFullGraph = (graph, registry, ref, hub, pluginContext, sinks, logger, identity, runtimeRoot) => Effect.gen(function* () {
+	yield* annotateOp("acquireFullGraph");
+	yield* acquireKeys(registry, [...graph.nodes.keys()], ref, hub, pluginContext, sinks, logger, identity, runtimeRoot);
+}).pipe(Effect.withSpan("lifecycle.supervisor.acquireFullGraph"));
+/**
+* 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* registry.transition(key, "stopping").pipe(Effect.catch(() => Effect.void));
+	yield* Scope.close(entry.scope, Exit.void).pipe(Effect.catch(() => Effect.void));
+	if (status === "ready") yield* registry.transition(key, "stopped").pipe(Effect.catch(() => Effect.void));
+}).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* registry.transition(key, "pending").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"));
+const runInjectedCommandHandler = (deps, cmd) => Effect.gen(function* () {
+	if (deps.commandHandler === void 0) return;
+	const publishFromHandler = (event) => publish(deps.ref, deps.hub, event);
+	const exit = yield* Effect.exit(deps.commandHandler(cmd, { publish: publishFromHandler }));
+	if (Exit.isSuccess(exit)) {
+		for (const event of exit.value) yield* publish(deps.ref, deps.hub, event);
+		return;
+	}
+	if (Cause.hasInterruptsOnly(exit.cause)) return;
+	if (cmd.tag === "snapshot.capture") yield* publish(deps.ref, deps.hub, {
+		tag: "snapshot.captureFailed",
+		...cmd.snapshotId === void 0 ? {} : { snapshotId: cmd.snapshotId },
+		...cmd.name === void 0 ? {} : { name: cmd.name },
+		summary: Cause.pretty(exit.cause).split("\n")[0] ?? "snapshot capture failed",
+		at: Date.now()
+	});
+	yield* publish(deps.ref, deps.hub, {
+		tag: "error.reported",
+		error: prettyErrorStructured(exit.cause, {
+			pluginKey: null,
+			severity: "error",
+			at: Date.now()
+		})
+	});
+	yield* deps.logger.log("supervisor", null, {
+		level: "error",
+		message: `command handler failed for ${cmd.tag}`
+	});
+}).pipe(Effect.withSpan("lifecycle.supervisor.injectedCommandHandler"));
+const startBackgroundSnapshotCapture = (deps, cmd) => Effect.gen(function* () {
+	const token = yield* Ref.updateAndGet(deps.snapshotCaptureSeq, (n) => n + 1);
+	if (!(yield* Ref.modify(deps.snapshotCaptureTask, (state) => state.tag === "idle" ? [true, {
+		tag: "starting",
+		token,
+		snapshotId: cmd.snapshotId ?? null
+	}] : [false, state]))) {
+		yield* publish(deps.ref, deps.hub, {
+			tag: "snapshot.captureSkipped",
+			reason: "already-running",
+			at: Date.now()
+		});
+		return;
+	}
+	yield* publish(deps.ref, deps.hub, {
+		tag: "snapshot.captureStarted",
+		...cmd.snapshotId === void 0 ? {} : { snapshotId: cmd.snapshotId },
+		...cmd.name === void 0 ? {} : { name: cmd.name },
+		at: Date.now()
+	});
+	const fiber = yield* runInjectedCommandHandler(deps, cmd).pipe(Effect.ensuring(Ref.update(deps.snapshotCaptureTask, (state) => state.tag !== "idle" && state.token === token ? { tag: "idle" } : state)), Effect.forkIn(deps.parentScope));
+	yield* Ref.update(deps.snapshotCaptureTask, (state) => state.tag === "starting" && state.token === token ? {
+		tag: "running",
+		token,
+		snapshotId: cmd.snapshotId ?? null,
+		fiber
+	} : state);
+}).pipe(Effect.withSpan("lifecycle.supervisor.backgroundSnapshotCapture"));
+const requestBackgroundSnapshotInterrupt = (deps) => Effect.gen(function* () {
+	const fiber = yield* Ref.modify(deps.snapshotCaptureTask, (state) => state.tag === "running" ? [state.fiber, { tag: "idle" }] : [null, state]);
+	if (fiber !== null) yield* Effect.sync(() => {
+		fiber.interruptUnsafe();
+	});
+}).pipe(Effect.withSpan("lifecycle.supervisor.interruptSnapshotCapture"));
+const startBackgroundStackRestart = (deps) => Effect.gen(function* () {
+	const token = yield* Ref.updateAndGet(deps.stackRestartSeq, (n) => n + 1);
+	if (!(yield* Ref.modify(deps.stackRestartTask, (state) => state.tag === "idle" ? [true, {
+		tag: "starting",
+		token
+	}] : [false, state]))) {
+		yield* deps.logger.log("supervisor", null, {
+			level: "debug",
+			message: "stack restart skipped because one is already running"
+		});
+		return;
+	}
+	const fiber = yield* handleCommand(deps, { tag: "stack.restart" }).pipe(Effect.catch(() => Effect.void), Effect.ensuring(Ref.update(deps.stackRestartTask, (state) => state.tag !== "idle" && state.token === token ? { tag: "idle" } : state)), Effect.forkIn(deps.parentScope));
+	yield* Ref.update(deps.stackRestartTask, (state) => state.tag === "starting" && state.token === token ? {
+		tag: "running",
+		token,
+		fiber
+	} : state);
+}).pipe(Effect.withSpan("lifecycle.supervisor.backgroundStackRestart"));
+const requestBackgroundStackRestartInterrupt = (deps) => Effect.gen(function* () {
+	const fiber = yield* Ref.modify(deps.stackRestartTask, (state) => state.tag === "running" ? [state.fiber, { tag: "idle" }] : [null, state]);
+	if (fiber !== null) yield* Fiber.interrupt(fiber);
+}).pipe(Effect.withSpan("lifecycle.supervisor.interruptStackRestart"));
+const publishHookFailure = (deps, cause, message, pluginKey = null) => Effect.gen(function* () {
+	yield* publish(deps.ref, deps.hub, {
+		tag: "error.reported",
+		error: prettyErrorStructured(cause, {
+			pluginKey,
+			severity: "error",
+			at: Date.now()
+		})
+	});
+	yield* deps.logger.log("supervisor", null, {
+		level: "error",
+		message
+	});
+});
+const findPostAcquireTaskFailure = (cause) => {
+	for (const reason of cause.reasons) {
+		if (!Cause.isFailReason(reason)) continue;
+		if (reason.error instanceof PostAcquireTaskFailed) return reason.error;
+	}
+	return null;
+};
+const runPostAcquireHook = (deps) => Effect.gen(function* () {
+	if (deps.postAcquireHook === void 0) return;
+	const exit = yield* Effect.exit(deps.postAcquireHook({
+		graph: deps.graph,
+		registry: deps.registry,
+		identity: deps.identity,
+		runtimeRoot: deps.runtimeRoot
+	}));
+	if (Exit.isSuccess(exit)) {
+		for (const event of exit.value) yield* publish(deps.ref, deps.hub, event);
+		return;
+	}
+	const taskFailure = findPostAcquireTaskFailure(exit.cause);
+	if (taskFailure !== null) yield* deps.registry.markFailed(taskFailure.pluginKey, taskFailure.cause).pipe(Effect.catch(() => Effect.void));
+	yield* publishHookFailure(deps, exit.cause, taskFailure === null ? "post-acquire hook failed" : `post-acquire task failed: ${taskFailure.label}`, taskFailure?.pluginKey ?? null);
+	return yield* Effect.fail(new SupervisorPostAcquireFailed({ cause: exit.cause }));
+}).pipe(Effect.withSpan("lifecycle.supervisor.postAcquireHook"));
+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;
+});
+const handleCommand = (deps, cmd, options = {}) => Effect.gen(function* () {
+	const { graph, registry, ref, hub, shutdownLatch, pluginContext, sinks, logger, identity, runtimeRoot, parentScope } = deps;
+	switch (cmd.tag) {
+		case "shutdown.requested":
+		case "stack.stop":
+			yield* requestBackgroundSnapshotInterrupt(deps);
+			yield* setCyclePhase(ref, "shutting-down");
+			yield* Ref.set(shutdownLatch, true);
+			yield* logger.log("supervisor", null, {
+				level: "info",
+				message: "shutdown requested"
+			});
+			yield* requestBackgroundStackRestartInterrupt(deps);
+			yield* setCyclePhase(ref, "shutting-down");
+			yield* teardownKeys(graph, registry, planFullDrain(graph).teardownOrder);
+			yield* Effect.yieldNow;
+			yield* Deferred.succeed(deps.shutdownComplete, void 0).pipe(Effect.ignore);
+			return;
+		case "shutdown.hardKillRequested":
+			yield* requestBackgroundSnapshotInterrupt(deps);
+			yield* publish(ref, hub, {
+				tag: "shutdown.escalated",
+				signal: cmd.signal,
+				exitCode: cmd.exitCode,
+				at: cmd.at
+			});
+			yield* setCyclePhase(ref, "shutting-down");
+			yield* Ref.set(shutdownLatch, true);
+			yield* requestBackgroundStackRestartInterrupt(deps);
+			yield* setCyclePhase(ref, "shutting-down");
+			yield* Deferred.succeed(deps.shutdownComplete, void 0).pipe(Effect.ignore);
+			yield* logger.log("supervisor", null, {
+				level: "fatal",
+				message: `shutdown escalated by ${cmd.signal}`,
+				fields: {
+					signal: cmd.signal,
+					exitCode: cmd.exitCode
+				}
+			});
+			return;
+		case "stack.restart": {
+			const plan = planFullDrain(graph);
+			if ((yield* doSelectiveRestart(graph, registry, ref, hub, new Set(plan.slice), pluginContext, sinks, logger, identity, runtimeRoot, parentScope).pipe(Effect.as(true), Effect.catch(() => Effect.succeed(false)))) && (yield* allReadyOrTerminal(graph, registry))) if (options.failOnPostAcquireHook === true) yield* runPostAcquireHook(deps);
+			else yield* runPostAcquireHook(deps).pipe(Effect.catch(() => Effect.void));
+			return;
+		}
+		case "selective-restart.requested":
+			if ((yield* doSelectiveRestart(graph, registry, ref, hub, new Set([cmd.pluginKey]), pluginContext, sinks, logger, identity, runtimeRoot, parentScope).pipe(Effect.as(true), Effect.catch(() => Effect.succeed(false)))) && (yield* allReadyOrTerminal(graph, registry))) if (options.failOnPostAcquireHook === true) yield* runPostAcquireHook(deps);
+			else yield* runPostAcquireHook(deps).pipe(Effect.catch(() => Effect.void));
+			return;
+		case "apply.requested":
+			if (cmd.pluginKey !== void 0) {
+				if ((yield* doSelectiveRestart(graph, registry, ref, hub, new Set([cmd.pluginKey]), pluginContext, sinks, logger, identity, runtimeRoot, parentScope).pipe(Effect.as(true), Effect.catch(() => Effect.succeed(false)))) && (yield* allReadyOrTerminal(graph, registry))) if (options.failOnPostAcquireHook === true) yield* runPostAcquireHook(deps);
+				else yield* runPostAcquireHook(deps).pipe(Effect.catch(() => Effect.void));
+				return;
+			}
+			if (yield* allReadyOrTerminal(graph, registry)) if (options.failOnPostAcquireHook === true) yield* runPostAcquireHook(deps);
+			else yield* runPostAcquireHook(deps).pipe(Effect.catch(() => Effect.void));
+			return;
+		case "codegen.requested":
+			if (yield* allReadyOrTerminal(graph, registry)) if (options.failOnPostAcquireHook === true) yield* runPostAcquireHook(deps);
+			else yield* runPostAcquireHook(deps).pipe(Effect.catch(() => Effect.void));
+			return;
+		case "snapshot.capture":
+			yield* startBackgroundSnapshotCapture(deps, cmd);
+			return;
+		case "snapshot.restore":
+		case "snapshot.list":
+		case "snapshot.delete":
+		case "wipe.requested":
+		case "prune.requested":
+			yield* runInjectedCommandHandler(deps, cmd);
+			return;
+		case "advance-clock.requested":
+		case "stack.start": return;
+	}
+}).pipe(Effect.withSpan("lifecycle.supervisor.handleCommand"));
+const commandLoop = (deps) => Effect.gen(function* () {
+	while (true) {
+		const next = yield* Queue.take(deps.queuedCommands);
+		if (next.kind === "submitted") {
+			const exit = yield* Effect.exit(handleCommand(deps, next.submission.command, { failOnPostAcquireHook: true }));
+			yield* Deferred.succeed(next.submission.completion, exit).pipe(Effect.ignore);
+		} else if (next.command.tag === "stack.restart") yield* startBackgroundStackRestart(deps);
+		else yield* handleCommand(deps, next.command).pipe(Effect.catch(() => Effect.void));
+		if (yield* Ref.get(deps.shutdownLatch)) return;
+	}
+}).pipe(Effect.withSpan("lifecycle.supervisor.commandLoop"));
+/**
+* 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). The orchestrator layer (L3)
+* builds this context once per stack from its layer stack and hands
+* it to the supervisor; substrate doesn't name the services itself
+* (the context is opaque `Context.Context<never>` at this boundary).
+*
+* `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. This is
+* the seam plugin authors use to register custom-kind sinks: compose
+* `layerCapabilitySinksDefault(orchestratorSinks)` with one or more
+* `Layer.effectDiscard` overlays that yield `CapabilitySinksService`
+* and call `registerSink({ kind: 'my-custom', accept: ... })`. The
+* `sinks: OrchestratorSinks` parameter is ignored when context carries
+* a pre-built service (the caller's Layer already supplies whatever
+* sink registrations it wants).
+*
+* Architecture § Stack lifecycle:
+*   "defineStack(config) → Identity validated → NetworkResolver
+*    consulted → Plugin dep-graph computed → level-batched parallel
+*    acquire → manifest.flushed → ready event → cycle running."
+*/
+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 = getOrDefault(pluginContext, Logger$1, 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 logger = withEventPublishingLogger(baseLogger, state, hub);
+	const pluginRuntimeContext = pluginContext.pipe(Context.add(Logger$1, Logger$1.of(logger)));
+	const supervisorScope = yield* Effect.scope;
+	const registry = yield* buildRegistry(graph, supervisorScope, buildTransitionEmitter(state, hub));
+	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
+			}]
+		}));
+	}
+	const runtimeRoot = getOrDefault(pluginContext, RuntimeRoot, { root: "" }).root;
+	const sinksService = yield* getOrDefaultEffect(pluginRuntimeContext, CapabilitySinksService, Effect.gen(function* () {
+		return Context.get(yield* Layer.build(layerCapabilitySinksDefault(sinks)), CapabilitySinksService);
+	}));
+	const enableCommandLoop = options.commandLoop !== false;
+	if (enableCommandLoop) {
+		yield* Effect.forkScoped(installSignalHandler(commands));
+		yield* Effect.forkScoped(Effect.gen(function* () {
+			while (true) {
+				const command = yield* Queue.take(commands);
+				yield* Queue.offer(queuedCommands, {
+					kind: "fire-and-forget",
+					command
+				});
+			}
+		}));
+	}
+	const commandLoopDeps = {
+		graph,
+		registry,
+		ref: state,
+		hub,
+		queuedCommands,
+		stackRestartTask,
+		stackRestartSeq,
+		snapshotCaptureTask,
+		snapshotCaptureSeq,
+		shutdownLatch,
+		shutdownComplete,
+		pluginContext: pluginRuntimeContext,
+		sinks: sinksService,
+		logger,
+		identity,
+		runtimeRoot,
+		parentScope: supervisorScope,
+		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(commandLoopDeps);
+			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"));
+	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;
+		yield* Queue.offer(commands, {
+			tag: "selective-restart.requested",
+			pluginKey: [...matched][0]
+		});
+		const rest = [...matched].slice(1);
+		for (const key of rest) yield* Queue.offer(commands, {
+			tag: "selective-restart.requested",
+			pluginKey: key
+		});
+	}).pipe(Effect.withSpan("lifecycle.supervisor.notifyWatchFire"));
+	if (enableCommandLoop) yield* Effect.forkScoped(commandLoop(commandLoopDeps));
+	yield* Effect.addFinalizer(() => 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"));
+	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"));
+	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
+}));
+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
+	};
+};
+//#endregion
+export { startSupervisor };
+
+//# sourceMappingURL=supervisor.mjs.map