@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/substrate/runtime/supervisor/acquire-node.mjs

@@ -1,17 +1,142 @@
 import { resolvePluginDependencies } from "../../plugin.mjs";
-import { annotateOp, annotatePhase, withPluginSpan } from "../observability/spans.mjs";
-import "../capability-sinks/index.mjs";
-import { prettyErrorStructured } from "../observability/pretty-error.mjs";
-import "../observability/index.mjs";
 import { buildDependencyReaderFor, makeEntry, makeRegistry } from "../lifecycle/plugin-registry.mjs";
 import { awaitUpstreams } from "../lifecycle/ready-gate.mjs";
 import "../lifecycle/index.mjs";
+import { prettyErrorStructured } from "../observability/pretty-error.mjs";
+import "../observability/index.mjs";
 import { CurrentPluginKey, CurrentPluginProgress } from "../current-plugin.mjs";
+import { PluginContext } from "../../plugin-ctx.mjs";
+import { StrategyRegistryService } from "../strategy-registry/service.mjs";
 import { operationalEndpointEventsFromResolvedValue } from "../projection/operational-endpoints.mjs";
-import { bestEffort, publish } from "./wiring.mjs";
-import { dispatchContributions, resolveCapabilities } from "./dispatch-contributions.mjs";
-import { Cause, Context, Effect, Exit, Scope } from "effect";
+import { OptionalService, bestEffort, noopStrategyRegistry, publish } from "./wiring.mjs";
+import { Cause, Context, Deferred, Effect, Exit, Fiber, Scope } from "effect";
 //#region src/substrate/runtime/supervisor/acquire-node.ts
+/**
+* Thrown (as a DEFECT, not a typed failure) when a plugin emits a ctx
+* contribution AFTER its `start` returned and the buffer was sealed
+* (PR#3). The buffer is the SOLE source of post-start contributions and
+* is read exactly once after `start`; a late async emission — e.g. a verb
+* called from a fiber the plugin forked but did not await — would
+* otherwise be silently dropped (a route that never registers, a codegen
+* file that never emits, with the plugin still `ready`). Sealing turns
+* that silent loss into a loud, attributable crash on the OFFENDING
+* fiber. The verb signatures return `void`, so this surfaces as a thrown
+* defect rather than an Effect failure. */
+var ContributionBufferSealedError = class extends Error {
+	_tag = "ContributionBufferSealedError";
+	constructor(pluginKey, kind) {
+		super(`plugin${pluginKey === null ? "" : ` '${pluginKey}'`} emitted a '${kind}' contribution after start() returned (the contribution buffer is sealed). Emit all ctx.* contributions synchronously within start(); a late async emission would be silently dropped.`);
+		this.name = "ContributionBufferSealedError";
+	}
+};
+const strategyRegistryAccess = OptionalService(StrategyRegistryService);
+/**
+* Build the per-plugin `PluginCtx` + its replay buffer. The four
+* declarative verbs (`codegen`/`endpoint`/`snapshotExtra`/`publish`) and
+* the strategy-bus writer (`provides`) PUSH a typed `BufferedContribution`
+* into `buffer` IN EMIT ORDER; the supervisor replays that buffer through
+* the closed `ContributionDispatcher` after a successful `start`. The
+* buffer is the SOLE source of post-start contributions.
+*/
+const makePluginCtx = (pluginKey) => {
+	const buffer = [];
+	let frozen = false;
+	const pushOrThrow = (kind, decl) => {
+		if (frozen) throw new ContributionBufferSealedError(pluginKey, kind);
+		buffer.push(decl);
+	};
+	return {
+		ctx: {
+			codegen: (decl) => {
+				pushOrThrow("codegenable", decl);
+			},
+			endpoint: (decl) => {
+				pushOrThrow("routable", decl);
+			},
+			snapshotExtra: (decl) => {
+				pushOrThrow("snapshotable", decl);
+			},
+			publish: (decl) => {
+				pushOrThrow("projection", decl);
+			},
+			provides: (decl) => {
+				pushOrThrow("strategy-contributor", decl);
+			}
+		},
+		buffer,
+		sealBuffer: () => {
+			frozen = true;
+		}
+	};
+};
+/**
+* Render the underlying cause of a contribution-dispatch failure to a
+* single operator-facing string. A failing dispatch body (e.g. a router
+* route collision) may reject with an Effect `Cause`, a tagged domain
+* error (carrying a spec-mismatch `detail`), a plain `Error`, or an
+* arbitrary value. The plugin stays `ready`, so without this the
+* operator would see a healthy-looking stack with dead routing.
+*/
+const formatCause = (cause) => {
+	if (Cause.isCause(cause)) return Cause.pretty(cause);
+	if (cause instanceof Error) return cause.stack ?? cause.message;
+	if (typeof cause === "string") return cause;
+	try {
+		return JSON.stringify(cause) ?? String(cause);
+	} catch {
+		return String(cause);
+	}
+};
+/** Best-effort `_tag` of the failing cause for the additive `causeType`
+*  on the `dispatchFailed` event. */
+const causeTagOf = (cause) => {
+	if (typeof cause === "object" && cause !== null && "_tag" in cause && typeof cause._tag === "string") return cause._tag;
+};
+/**
+* Replay one plugin's buffered contributions through the closed
+* `ContributionDispatcher` after a successful `start`.
+*
+* Failure semantics: a dispatch BODY failure is an orchestrator-fault —
+* the supervisor publishes
+* `engine.orchestrator.dispatchFailed` + logs a warning, and the plugin
+* stays `ready` (NOT `markFailed`). The contribution kinds are a CLOSED
+* union, so the dispatch is an exhaustive switch on the decl
+* discriminant (no UnknownContributionKind arm).
+*
+* Runs on the plugin's scope (`pluginScope`) so any finalizer a dispatch
+* body arms (e.g. `strategy.unregistered`) reaps on plugin teardown.
+*/
+const dispatchBufferedContributions = (pluginKey, buffer, pluginContext, pluginScope, dispatcher, ref, hub) => Effect.gen(function* () {
+	const dispatchCtx = {
+		pluginKey,
+		publish: (event) => publish(ref, hub, event),
+		strategyRegistry: strategyRegistryAccess.read(pluginContext, noopStrategyRegistry)
+	};
+	for (const decl of buffer) {
+		const guarded = (() => {
+			switch (decl.kind) {
+				case "snapshotable": return dispatcher.snapshotable(decl, dispatchCtx);
+				case "codegenable": return dispatcher.codegenable(decl, dispatchCtx);
+				case "routable": return dispatcher.routable(decl, dispatchCtx);
+				case "projection": return dispatcher.projection(decl, dispatchCtx);
+				case "strategy-contributor": return dispatcher.strategyContributor(decl, dispatchCtx);
+				default: return Effect.void;
+			}
+		})().pipe(Effect.catch((cause) => Effect.gen(function* () {
+			const causeType = causeTagOf(cause);
+			yield* publish(ref, hub, {
+				tag: "engine.orchestrator.dispatchFailed",
+				pluginKey,
+				kind: decl.kind,
+				message: `routing/contribution sink '${decl.kind}' failed`,
+				...causeType === void 0 ? {} : { causeType },
+				at: Date.now()
+			});
+			yield* Effect.logWarning(`routing/contribution sink '${decl.kind}' failed for plugin '${pluginKey}': ${formatCause(cause)}`);
+		})));
+		yield* Scope.provide(guarded, pluginScope);
+	}
+});
 const buildRegistry = (graph, parentScope, emit) => Effect.gen(function* () {
 	const entries = /* @__PURE__ */ new Map();
 	for (const [key, node] of graph.nodes) {
@@ -40,7 +165,7 @@ const buildRegistry = (graph, parentScope, emit) => Effect.gen(function* () {
 * 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 acquireNode = (registry, key, ref, hub, pluginContext, dispatcher, logger, _identity) => Effect.gen(function* () {
 	const entry = registry.entries.get(key);
 	if (entry === void 0) return;
 	if ((yield* awaitUpstreams(registry, entry.node).pipe(Effect.matchEffect({
@@ -56,7 +181,6 @@ const acquireNode = (registry, key, ref, hub, pluginContext, sinks, logger, iden
 		});
 		return;
 	}
-	yield* annotatePhase("acquire");
 	yield* logger.log(`supervisor/${key}`, key, {
 		level: "debug",
 		message: "plugin acquire start",
@@ -66,7 +190,8 @@ const acquireNode = (registry, key, ref, hub, pluginContext, sinks, logger, iden
 	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, {
+	const { ctx: pluginCtx, buffer, sealBuffer } = makePluginCtx(key);
+	const currentPluginContext = pluginContext.pipe(Context.add(CurrentPluginKey, { key }), Context.add(PluginContext, pluginCtx), Context.add(CurrentPluginProgress, { setPhase: (phase) => publish(ref, hub, {
 		tag: "lifecycle.phaseSet",
 		pluginKey: key,
 		phase,
@@ -91,33 +216,10 @@ const acquireNode = (registry, key, ref, hub, pluginContext, sinks, logger, iden
 			value
 		})
 	}));
+	sealBuffer();
 	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* bestEffort(registry.markFailed(key, capsExit.cause));
-			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 (buffer.length > 0) {
+			const dispatchExit = yield* Effect.exit(dispatchBufferedContributions(key, buffer, pluginContext, entry.scope, dispatcher, ref, hub));
 			if (Exit.isFailure(dispatchExit)) {
 				yield* bestEffort(registry.markFailed(key, dispatchExit.cause));
 				yield* publish(ref, hub, {
@@ -135,7 +237,7 @@ const acquireNode = (registry, key, ref, hub, pluginContext, sinks, logger, iden
 				return;
 			}
 		}
-		const routablesPresent = caps.some((capability) => capability.kind === "routable");
+		const routablesPresent = buffer.some((decl) => decl.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",
@@ -148,33 +250,63 @@ const acquireNode = (registry, key, ref, hub, pluginContext, sinks, logger, iden
 		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
-			}
+			fields: { contributions: buffer.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)), {
+});
+var PluginAcquireInterruptedBeforeReady = class extends Error {
+	pluginKey;
+	_tag = "PluginAcquireInterruptedBeforeReady";
+	constructor(pluginKey) {
+		super(`plugin '${pluginKey}' acquire was interrupted before readiness`);
+		this.pluginKey = pluginKey;
+		this.name = "PluginAcquireInterruptedBeforeReady";
+	}
+};
+const failIfAcquireInterruptedBeforeReady = (registry, key, entry) => Effect.gen(function* () {
+	if (registry.entries.get(key) !== entry) return;
+	const status = yield* registry.getStatus(key).pipe(Effect.catch(() => Effect.succeed(null)));
+	if (registry.entries.get(key) !== entry) return;
+	if (status !== "pending" && status !== "acquiring") return;
+	yield* bestEffort(registry.markFailed(key, new PluginAcquireInterruptedBeforeReady(key)));
+});
+const acquireKeys = (registry, keys, ref, hub, pluginContext, dispatcher, logger, identity, parentScope) => Effect.gen(function* () {
+	const fibers = yield* Effect.all(keys.map((key) => Effect.gen(function* () {
+		const entry = registry.entries.get(key);
+		if (entry === void 0) return yield* Effect.forkIn(Effect.void, parentScope);
+		const registeredGate = yield* Deferred.make();
+		const readyToRegister = yield* Deferred.make();
+		const guarded = Effect.gen(function* () {
+			const selfId = yield* Effect.fiberId;
+			yield* Effect.gen(function* () {
+				yield* Deferred.succeed(readyToRegister, void 0);
+				yield* Deferred.await(registeredGate);
+				yield* acquireNode(registry, key, ref, hub, pluginContext, dispatcher, logger, identity);
+			}).pipe(Effect.onInterrupt(() => failIfAcquireInterruptedBeforeReady(registry, key, entry)), Effect.ensuring(registry.clearAcquireFiberIfEntry(key, entry, selfId).pipe(Effect.catch(() => Effect.void))));
+		});
+		const fiber = yield* Effect.forkIn(Scope.provide(guarded, parentScope), parentScope);
+		yield* Deferred.await(readyToRegister);
+		if (!(yield* registry.setAcquireFiberIfEntry(key, entry, fiber).pipe(Effect.catch(() => Effect.succeed(false))))) {
+			yield* Fiber.interrupt(fiber).pipe(Effect.asVoid);
+			return fiber;
+		}
+		yield* Deferred.succeed(registeredGate, void 0);
+		return fiber;
+	})), { concurrency: "unbounded" });
+	yield* Effect.all(fibers.map((fiber) => Fiber.await(fiber).pipe(Effect.flatMap((exit) => {
+		if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause)) return Effect.void;
+		return Effect.failCause(exit.cause);
+	}))), {
 		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"));
+});
+const acquireFullGraph = (graph, registry, ref, hub, pluginContext, dispatcher, logger, identity, parentScope) => Effect.gen(function* () {
+	yield* acquireKeys(registry, [...graph.nodes.keys()], ref, hub, pluginContext, dispatcher, logger, identity, parentScope);
+});
 //#endregion
 export { acquireFullGraph, acquireKeys, buildRegistry };
 

package/dist/substrate/runtime/supervisor/acquire-node.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"acquire-node.mjs","names":[],"sources":["../../../../src/substrate/runtime/supervisor/acquire-node.ts"],"sourcesContent":["// Per-plugin acquire pipeline.\n//\n// Three entrypoints:\n//   - `buildRegistry(graph, parentScope, emit)` — boots the plugin\n//     registry from a resolved graph; each plugin's scope is parented\n//     to the supervisor's outer scope.\n//   - `acquireNode(...)` — runs one plugin's `start` body inside its\n//     entry scope; on success harvests `capabilities` +\n//     `errorContributions` and registers them through `CapabilitySinks`.\n//   - `acquireKeys` / `acquireFullGraph` — fan out per-node acquires\n//     in parallel; each node waits on its own upstream ready gate.\n\nimport { Cause, Context, Effect, Exit, Queue, Scope, SubscriptionRef } from 'effect';\n\nimport type { CapabilityDecl } from '../../../contracts/capability-decl.ts';\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 { resolvePluginDependencies, type AcquireContext } from '../../plugin.ts';\nimport type { SubscribableState } from '../../projection.ts';\nimport { type CapabilitySinksShape } from '../capability-sinks/index.ts';\nimport { CurrentPluginKey, CurrentPluginProgress } from '../current-plugin.ts';\nimport {\n\tannotateOp,\n\tannotatePhase,\n\tprettyErrorStructured,\n\twithPluginSpan,\n\ttype LoggerShape,\n} from '../observability/index.ts';\nimport {\n\tawaitUpstreams,\n\tbuildDependencyReaderFor,\n\tmakeEntry,\n\tmakeRegistry,\n\ttype PluginEntry,\n\ttype PluginRegistry,\n\ttype ResolvedGraph,\n} from '../lifecycle/index.ts';\nimport { operationalEndpointEventsFromResolvedValue } from '../projection/operational-endpoints.ts';\nimport { dispatchContributions, resolveCapabilities } from './dispatch-contributions.ts';\nimport { bestEffort, publish } from './wiring.ts';\n\n// -----------------------------------------------------------------------------\n// Boot the registry from a graph\n// -----------------------------------------------------------------------------\n\nexport const buildRegistry = (\n\tgraph: ResolvedGraph,\n\tparentScope: Scope.Scope,\n\temit: (key: PluginKey, from: LifecycleStatus, to: LifecycleStatus) => Effect.Effect<void>,\n): Effect.Effect<PluginRegistry, never, never> =>\n\tEffect.gen(function* () {\n\t\tconst entries = new Map<PluginKey, PluginEntry>();\n\t\tfor (const [key, node] of graph.nodes) {\n\t\t\tconst entry = yield* makeEntry(node, parentScope);\n\t\t\tentries.set(key, entry);\n\t\t}\n\t\treturn makeRegistry(entries, emit);\n\t});\n\n// -----------------------------------------------------------------------------\n// Acquire one node\n// -----------------------------------------------------------------------------\n\n/**\n * Run one node's `start` under its own scope. Steps:\n *  1. Await upstreams (their ready-gates).\n *  2. Transition `pending → acquiring` (publishes the event).\n *  3. Build resolved dependency values from declared resource refs.\n *  4. Run the plugin's `start` Effect inside the entry's Scope,\n *     after providing the substrate-context services bundle so the\n *     plugin's R-channel yields (`IdentityContext`,\n *     `ContainerRuntimeService`, etc.) resolve to live instances.\n *  5. On success: stash the resolved value + `markReady` (publishes\n *     the `ready` transition).\n *  6. On failure: `markFailed` (publishes the `failed` transition, fails\n *     the deferred so downstream consumers short-circuit).\n *\n * Errors are caught and stashed onto the registry entry — the outer\n * scheduler doesn't propagate per-plugin failures; ready-gate failure\n * propagation handles the downstream blocking. The supervisor's outer\n * fiber surfaces the union via `Fiber.join` when the user asks for\n * \"stack ready or err\".\n */\nexport const acquireNode = (\n\tregistry: PluginRegistry,\n\tkey: PluginKey,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n\tpluginContext: Context.Context<never>,\n\tsinks: CapabilitySinksShape,\n\tlogger: LoggerShape,\n\tidentity: Identity,\n\truntimeRoot: string,\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 upstreamWait = awaitUpstreams(registry, entry.node).pipe(\n\t\t\tEffect.matchEffect({\n\t\t\t\tonFailure: (cause) =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* bestEffort(registry.markFailed(key, cause));\n\t\t\t\t\t\treturn false as const;\n\t\t\t\t\t}),\n\t\t\t\tonSuccess: () => Effect.succeed(true as const),\n\t\t\t}),\n\t\t);\n\t\tconst ok = yield* upstreamWait;\n\t\tif (ok !== true) {\n\t\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\t\tlevel: 'warn',\n\t\t\t\tmessage: 'plugin acquire skipped — upstream failed',\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tyield* annotatePhase('acquire');\n\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\tlevel: 'debug',\n\t\t\tmessage: 'plugin acquire start',\n\t\t\tfields: { role: entry.node.member.role },\n\t\t});\n\t\t// Best-effort claim. `transition` `Effect.die`s on an off-table move,\n\t\t// which a concurrent acquire can trigger: an in-flight initial\n\t\t// `acquireNode` racing a selective-restart re-acquire of the same key\n\t\t// hits `acquiring → acquiring`. `Effect.catch` (used originally here)\n\t\t// cannot catch that DEFECT, so it would escape and kill the\n\t\t// command-loop fiber (supervisor wedge — same class as the lifecycle\n\t\t// reset fix). `Effect.exit` swallows BOTH failure and defect, keeping\n\t\t// this the best-effort transition it was always meant to be.\n\t\t// NOTE: this prevents the wedge but not the underlying double-acquire\n\t\t// (two fibers running one node's `start`). A complete fix must\n\t\t// interrupt a node's in-flight acquire fiber before a restart\n\t\t// re-acquires it — tracked as a follow-up (needs per-node acquire-fiber\n\t\t// handles, which `acquireKeys`' `Effect.all` does not retain today).\n\t\tyield* Effect.exit(registry.transition(key, 'acquiring'));\n\t\tconst readDependency = buildDependencyReaderFor(registry, entry.node);\n\t\tconst deps = resolvePluginDependencies(entry.node.member, readDependency);\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst start = entry.node.member.start as (\n\t\t\tdeps: unknown,\n\t\t) => Effect.Effect<unknown, unknown, any>;\n\t\tconst currentPluginContext = pluginContext.pipe(\n\t\t\tContext.add(CurrentPluginKey, { key }),\n\t\t\tContext.add(CurrentPluginProgress, {\n\t\t\t\tsetPhase: (phase) =>\n\t\t\t\t\tpublish(ref, hub, {\n\t\t\t\t\t\ttag: 'lifecycle.phaseSet',\n\t\t\t\t\t\tpluginKey: key,\n\t\t\t\t\t\tphase,\n\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t}),\n\t\t\t}),\n\t\t);\n\t\tconst providedAcquire = Effect.provide(start(deps), currentPluginContext) as Effect.Effect<\n\t\t\tunknown,\n\t\t\tunknown,\n\t\t\tScope.Scope\n\t\t>;\n\t\tconst result = yield* Scope.provide(providedAcquire, entry.scope).pipe(\n\t\t\tEffect.matchEffect({\n\t\t\t\tonFailure: (cause) =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* bestEffort(registry.markFailed(key, cause));\n\t\t\t\t\t\tyield* publish(ref, hub, {\n\t\t\t\t\t\t\ttag: 'error.reported',\n\t\t\t\t\t\t\terror: prettyErrorStructured(Cause.fail(cause), {\n\t\t\t\t\t\t\t\tpluginKey: key,\n\t\t\t\t\t\t\t\tseverity: 'error',\n\t\t\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t});\n\t\t\t\t\t\treturn { ok: false as const };\n\t\t\t\t\t}),\n\t\t\t\tonSuccess: (value: unknown) =>\n\t\t\t\t\tEffect.succeed({ ok: true as const, value: value as unknown }),\n\t\t\t}),\n\t\t);\n\t\tif (result.ok) {\n\t\t\tconst acquireContext: AcquireContext = {\n\t\t\t\tidentity,\n\t\t\t\tchain: identity.chain,\n\t\t\t\truntimeRoot,\n\t\t\t};\n\t\t\tconst capsExit = yield* Effect.exit(\n\t\t\t\tresolveCapabilities(\n\t\t\t\t\tkey,\n\t\t\t\t\tentry.node.member.capabilities as\n\t\t\t\t\t\t| ReadonlyArray<CapabilityDecl>\n\t\t\t\t\t\t| ((r: unknown, c: AcquireContext) => ReadonlyArray<CapabilityDecl>)\n\t\t\t\t\t\t| undefined,\n\t\t\t\t\tresult.value,\n\t\t\t\t\tacquireContext,\n\t\t\t\t),\n\t\t\t);\n\t\t\tif (Exit.isFailure(capsExit)) {\n\t\t\t\tyield* bestEffort(registry.markFailed(key, capsExit.cause));\n\t\t\t\tyield* publish(ref, hub, {\n\t\t\t\t\ttag: 'error.reported',\n\t\t\t\t\terror: prettyErrorStructured(capsExit.cause, {\n\t\t\t\t\t\tpluginKey: key,\n\t\t\t\t\t\tseverity: 'error',\n\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t}),\n\t\t\t\t});\n\t\t\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\t\t\tlevel: 'error',\n\t\t\t\t\tmessage: 'plugin capability factory failed',\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst caps = capsExit.value;\n\t\t\tconst errorContributions = entry.node.member.errorContributions ?? [];\n\t\t\tif (caps.length > 0 || errorContributions.length > 0) {\n\t\t\t\tconst dispatchExit = yield* Effect.exit(\n\t\t\t\t\tdispatchContributions(\n\t\t\t\t\t\tkey,\n\t\t\t\t\t\tcaps,\n\t\t\t\t\t\terrorContributions,\n\t\t\t\t\t\tentry.node.member.role,\n\t\t\t\t\t\tidentity,\n\t\t\t\t\t\tpluginContext,\n\t\t\t\t\t\tentry.scope,\n\t\t\t\t\t\tsinks,\n\t\t\t\t\t\tref,\n\t\t\t\t\t\thub,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tif (Exit.isFailure(dispatchExit)) {\n\t\t\t\t\t// dispatchContributions catches both UnknownContributionKind\n\t\t\t\t\t// (no-op) and ContributionSinkFailed (orchestrator event +\n\t\t\t\t\t// warning) internally. A surfaced failure here therefore\n\t\t\t\t\t// reflects an unexpected defect — keep the legacy\n\t\t\t\t\t// markFailed projection so the unknown shape doesn't\n\t\t\t\t\t// silently degrade the plugin.\n\t\t\t\t\tyield* bestEffort(registry.markFailed(key, dispatchExit.cause));\n\t\t\t\t\tyield* publish(ref, hub, {\n\t\t\t\t\t\ttag: 'error.reported',\n\t\t\t\t\t\terror: prettyErrorStructured(dispatchExit.cause, {\n\t\t\t\t\t\t\tpluginKey: key,\n\t\t\t\t\t\t\tseverity: 'error',\n\t\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t\t}),\n\t\t\t\t\t});\n\t\t\t\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\t\t\t\tlevel: 'error',\n\t\t\t\t\t\tmessage: 'plugin capability dispatch failed',\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst routablesPresent = caps.some((capability) => capability.kind === 'routable');\n\t\t\tfor (const event of operationalEndpointEventsFromResolvedValue(\n\t\t\t\tkey,\n\t\t\t\tresult.value,\n\t\t\t\tDate.now(),\n\t\t\t\t{\n\t\t\t\t\troutablesPresent,\n\t\t\t\t},\n\t\t\t)) {\n\t\t\t\tyield* publish(ref, hub, event);\n\t\t\t}\n\t\t\tyield* publish(ref, hub, {\n\t\t\t\ttag: 'lifecycle.phaseSet',\n\t\t\t\tpluginKey: key,\n\t\t\t\tphase: null,\n\t\t\t\tat: Date.now(),\n\t\t\t});\n\t\t\tyield* bestEffort(registry.markReady(key, result.value));\n\t\t\tif (entry.node.member.role === 'task') {\n\t\t\t\tyield* bestEffort(registry.transition(key, 'done'));\n\t\t\t}\n\t\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\t\tlevel: 'debug',\n\t\t\t\tmessage: entry.node.member.role === 'task' ? 'plugin done' : 'plugin ready',\n\t\t\t\tfields: {\n\t\t\t\t\tcapabilities: caps.length,\n\t\t\t\t\terrorContributions: errorContributions.length,\n\t\t\t\t},\n\t\t\t});\n\t\t} else {\n\t\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\t\tlevel: 'debug',\n\t\t\t\tmessage: 'plugin acquire failed',\n\t\t\t});\n\t\t}\n\t}).pipe(\n\t\twithPluginSpan('lifecycle.supervisor.acquireNode', {\n\t\t\tapp: identity.app,\n\t\t\tstack: identity.stack,\n\t\t\tnetwork: identity.chain,\n\t\t\tpluginKey: key,\n\t\t\trole: registry.entries.get(key)?.node.member.role ?? 'service',\n\t\t}),\n\t);\n\n// -----------------------------------------------------------------------------\n// Acquire a key set in parallel. Each node waits on its own upstreams,\n// so downstream nodes begin as soon as their dependencies are ready\n// instead of waiting for unrelated nodes in the same topological level.\n// -----------------------------------------------------------------------------\n\nexport const acquireKeys = (\n\tregistry: PluginRegistry,\n\tkeys: ReadonlyArray<PluginKey>,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n\tpluginContext: Context.Context<never>,\n\tsinks: CapabilitySinksShape,\n\tlogger: LoggerShape,\n\tidentity: Identity,\n\truntimeRoot: string,\n): Effect.Effect<void, never, never> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({ 'devstack.level.size': keys.length });\n\t\tyield* Effect.all(\n\t\t\tkeys.map((key) =>\n\t\t\t\tacquireNode(registry, key, ref, hub, pluginContext, sinks, logger, identity, runtimeRoot),\n\t\t\t),\n\t\t\t{ concurrency: 'unbounded', discard: true },\n\t\t);\n\t}).pipe(Effect.withSpan('lifecycle.supervisor.acquireKeys'));\n\nexport const acquireFullGraph = (\n\tgraph: ResolvedGraph,\n\tregistry: PluginRegistry,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n\tpluginContext: Context.Context<never>,\n\tsinks: CapabilitySinksShape,\n\tlogger: LoggerShape,\n\tidentity: Identity,\n\truntimeRoot: string,\n): Effect.Effect<void, never, never> =>\n\tEffect.gen(function* () {\n\t\tyield* annotateOp('acquireFullGraph');\n\t\tyield* acquireKeys(\n\t\t\tregistry,\n\t\t\t[...graph.nodes.keys()],\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}).pipe(Effect.withSpan('lifecycle.supervisor.acquireFullGraph'));\n"],"mappings":"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"}
+{"version":3,"file":"acquire-node.mjs","names":[],"sources":["../../../../src/substrate/runtime/supervisor/acquire-node.ts"],"sourcesContent":["// Per-plugin acquire pipeline.\n//\n// Three entrypoints:\n//   - `buildRegistry(graph, parentScope, emit)` — boots the plugin\n//     registry from a resolved graph; each plugin's scope is parented\n//     to the supervisor's outer scope.\n//   - `acquireNode(...)` — runs one plugin's `start` body inside its\n//     entry scope; on success replays the ctx-buffered contributions\n//     through the closed `ContributionDispatcher`.\n//   - `acquireKeys` / `acquireFullGraph` — fan out per-node acquires\n//     in parallel; each node waits on its own upstream ready gate.\n\nimport {\n\tCause,\n\tContext,\n\tDeferred,\n\tEffect,\n\tExit,\n\tFiber,\n\tQueue,\n\tScope,\n\tSubscriptionRef,\n} from 'effect';\n\nimport type { CodegenableDecl } from '../../../contracts/codegenable.ts';\nimport type { ProjectionDecl } from '../../../contracts/projection.ts';\nimport type { RoutableDecl } from '../../../contracts/routable.ts';\nimport type { SnapshotableDecl } from '../../../contracts/snapshotable.ts';\nimport type { StrategyContributorDecl } from '../../../contracts/strategy-contributor.ts';\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 { PluginCtx } from '../../plugin-ctx.ts';\nimport { PluginContext } from '../../plugin-ctx.ts';\nimport { resolvePluginDependencies } from '../../plugin.ts';\nimport type { SubscribableState } from '../../projection.ts';\nimport { StrategyRegistryService } from '../strategy-registry/service.ts';\nimport { CurrentPluginKey, CurrentPluginProgress } from '../current-plugin.ts';\nimport { prettyErrorStructured, type LoggerShape } from '../observability/index.ts';\nimport {\n\tawaitUpstreams,\n\tbuildDependencyReaderFor,\n\tmakeEntry,\n\tmakeRegistry,\n\ttype PluginEntry,\n\ttype PluginRegistry,\n\ttype ResolvedGraph,\n} from '../lifecycle/index.ts';\nimport { operationalEndpointEventsFromResolvedValue } from '../projection/operational-endpoints.ts';\nimport type {\n\tContributionDispatcher,\n\tContributionDispatchContext,\n} from './contribution-dispatcher.ts';\nimport { bestEffort, noopStrategyRegistry, OptionalService, publish } from './wiring.ts';\n\n// A single buffered contribution — a discriminated union over the five\n// closed decl kinds, in the order the plugin's `start` emitted them.\ntype BufferedContribution =\n\t| SnapshotableDecl\n\t| CodegenableDecl<string>\n\t| RoutableDecl\n\t| ProjectionDecl\n\t| StrategyContributorDecl<string, unknown>;\n\n/**\n * Thrown (as a DEFECT, not a typed failure) when a plugin emits a ctx\n * contribution AFTER its `start` returned and the buffer was sealed\n * (PR#3). The buffer is the SOLE source of post-start contributions and\n * is read exactly once after `start`; a late async emission — e.g. a verb\n * called from a fiber the plugin forked but did not await — would\n * otherwise be silently dropped (a route that never registers, a codegen\n * file that never emits, with the plugin still `ready`). Sealing turns\n * that silent loss into a loud, attributable crash on the OFFENDING\n * fiber. The verb signatures return `void`, so this surfaces as a thrown\n * defect rather than an Effect failure. */\nexport class ContributionBufferSealedError extends Error {\n\treadonly _tag = 'ContributionBufferSealedError' as const;\n\tconstructor(pluginKey: PluginKey | null, kind: string) {\n\t\tsuper(\n\t\t\t`plugin${pluginKey === null ? '' : ` '${pluginKey}'`} emitted a '${kind}' contribution ` +\n\t\t\t\t`after start() returned (the contribution buffer is sealed). Emit all ctx.* ` +\n\t\t\t\t`contributions synchronously within start(); a late async emission would be ` +\n\t\t\t\t`silently dropped.`,\n\t\t);\n\t\tthis.name = 'ContributionBufferSealedError';\n\t}\n}\n\n// -----------------------------------------------------------------------------\n// Per-plugin PluginCtx\n// -----------------------------------------------------------------------------\n\nconst strategyRegistryAccess = OptionalService(StrategyRegistryService);\n\n/**\n * Build the per-plugin `PluginCtx` + its replay buffer. The four\n * declarative verbs (`codegen`/`endpoint`/`snapshotExtra`/`publish`) and\n * the strategy-bus writer (`provides`) PUSH a typed `BufferedContribution`\n * into `buffer` IN EMIT ORDER; the supervisor replays that buffer through\n * the closed `ContributionDispatcher` after a successful `start`. The\n * buffer is the SOLE source of post-start contributions.\n */\nconst makePluginCtx = (\n\tpluginKey: PluginKey,\n): {\n\treadonly ctx: PluginCtx;\n\treadonly buffer: BufferedContribution[];\n\treadonly sealBuffer: () => void;\n} => {\n\tconst buffer: BufferedContribution[] = [];\n\t// PR#3: the buffer is read exactly once after `start` returns, then\n\t// frozen. A push afterwards is a late async emission that would be\n\t// silently dropped — throw a loud, attributable defect instead.\n\tlet frozen = false;\n\tconst pushOrThrow = (kind: string, decl: BufferedContribution): void => {\n\t\tif (frozen) throw new ContributionBufferSealedError(pluginKey, kind);\n\t\tbuffer.push(decl);\n\t};\n\tconst ctx: PluginCtx = {\n\t\tcodegen: <E extends string>(decl: CodegenableDecl<E>): void => {\n\t\t\tpushOrThrow('codegenable', decl);\n\t\t},\n\t\tendpoint: (decl: RoutableDecl): void => {\n\t\t\tpushOrThrow('routable', decl);\n\t\t},\n\t\tsnapshotExtra: (decl: SnapshotableDecl): void => {\n\t\t\tpushOrThrow('snapshotable', decl);\n\t\t},\n\t\tpublish: (decl: ProjectionDecl): void => {\n\t\t\tpushOrThrow('projection', decl);\n\t\t},\n\t\tprovides: <K extends string, S>(decl: StrategyContributorDecl<K, S>): void => {\n\t\t\tpushOrThrow('strategy-contributor', decl);\n\t\t},\n\t};\n\treturn {\n\t\tctx,\n\t\tbuffer,\n\t\tsealBuffer: () => {\n\t\t\tfrozen = true;\n\t\t},\n\t};\n};\n\n// -----------------------------------------------------------------------------\n// Static post-start dispatch\n// -----------------------------------------------------------------------------\n\n/**\n * Render the underlying cause of a contribution-dispatch failure to a\n * single operator-facing string. A failing dispatch body (e.g. a router\n * route collision) may reject with an Effect `Cause`, a tagged domain\n * error (carrying a spec-mismatch `detail`), a plain `Error`, or an\n * arbitrary value. The plugin stays `ready`, so without this the\n * operator would see a healthy-looking stack with dead routing.\n */\nconst formatCause = (cause: unknown): string => {\n\tif (Cause.isCause(cause)) return Cause.pretty(cause);\n\tif (cause instanceof Error) return cause.stack ?? cause.message;\n\tif (typeof cause === 'string') return cause;\n\ttry {\n\t\treturn JSON.stringify(cause) ?? String(cause);\n\t} catch {\n\t\treturn String(cause);\n\t}\n};\n\n/** Best-effort `_tag` of the failing cause for the additive `causeType`\n *  on the `dispatchFailed` event. */\nconst causeTagOf = (cause: unknown): string | undefined => {\n\tif (\n\t\ttypeof cause === 'object' &&\n\t\tcause !== null &&\n\t\t'_tag' in cause &&\n\t\ttypeof (cause as { _tag: unknown })._tag === 'string'\n\t) {\n\t\treturn (cause as { _tag: string })._tag;\n\t}\n\treturn undefined;\n};\n\n/**\n * Replay one plugin's buffered contributions through the closed\n * `ContributionDispatcher` after a successful `start`.\n *\n * Failure semantics: a dispatch BODY failure is an orchestrator-fault —\n * the supervisor publishes\n * `engine.orchestrator.dispatchFailed` + logs a warning, and the plugin\n * stays `ready` (NOT `markFailed`). The contribution kinds are a CLOSED\n * union, so the dispatch is an exhaustive switch on the decl\n * discriminant (no UnknownContributionKind arm).\n *\n * Runs on the plugin's scope (`pluginScope`) so any finalizer a dispatch\n * body arms (e.g. `strategy.unregistered`) reaps on plugin teardown.\n */\nconst dispatchBufferedContributions = (\n\tpluginKey: PluginKey,\n\tbuffer: ReadonlyArray<BufferedContribution>,\n\tpluginContext: Context.Context<never>,\n\tpluginScope: Scope.Scope,\n\tdispatcher: ContributionDispatcher,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n): Effect.Effect<void, never, never> =>\n\tEffect.gen(function* () {\n\t\tconst strategyRegistry = strategyRegistryAccess.read(pluginContext, noopStrategyRegistry);\n\t\tconst dispatchCtx: ContributionDispatchContext = {\n\t\t\tpluginKey,\n\t\t\tpublish: (event) => publish(ref, hub, event),\n\t\t\tstrategyRegistry,\n\t\t};\n\n\t\tfor (const decl of buffer) {\n\t\t\tconst body = ((): Effect.Effect<void, unknown, Scope.Scope> => {\n\t\t\t\tswitch (decl.kind) {\n\t\t\t\t\tcase 'snapshotable':\n\t\t\t\t\t\treturn dispatcher.snapshotable(decl, dispatchCtx);\n\t\t\t\t\tcase 'codegenable':\n\t\t\t\t\t\treturn dispatcher.codegenable(decl, dispatchCtx);\n\t\t\t\t\tcase 'routable':\n\t\t\t\t\t\treturn dispatcher.routable(decl, dispatchCtx);\n\t\t\t\t\tcase 'projection':\n\t\t\t\t\t\treturn dispatcher.projection(decl, dispatchCtx);\n\t\t\t\t\tcase 'strategy-contributor':\n\t\t\t\t\t\treturn dispatcher.strategyContributor(decl, dispatchCtx);\n\t\t\t\t\tdefault: {\n\t\t\t\t\t\tconst _exhaustive: never = decl;\n\t\t\t\t\t\tvoid _exhaustive;\n\t\t\t\t\t\treturn Effect.void;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t})();\n\t\t\t// Orchestrator-fault path: a dispatch body failure surfaces the\n\t\t\t// typed `dispatchFailed` event + warning WITHOUT marking the\n\t\t\t// plugin failed (the plugin already reached a good `start`).\n\t\t\tconst guarded = body.pipe(\n\t\t\t\tEffect.catch((cause) =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tconst causeType = causeTagOf(cause);\n\t\t\t\t\t\tyield* publish(ref, hub, {\n\t\t\t\t\t\t\ttag: 'engine.orchestrator.dispatchFailed',\n\t\t\t\t\t\t\tpluginKey,\n\t\t\t\t\t\t\tkind: decl.kind,\n\t\t\t\t\t\t\tmessage: `routing/contribution sink '${decl.kind}' failed`,\n\t\t\t\t\t\t\t...(causeType === undefined ? {} : { causeType }),\n\t\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t\t});\n\t\t\t\t\t\tyield* Effect.logWarning(\n\t\t\t\t\t\t\t`routing/contribution sink '${decl.kind}' failed for plugin '${pluginKey}': ${formatCause(cause)}`,\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\tyield* Scope.provide(guarded, pluginScope);\n\t\t}\n\t});\n\n// -----------------------------------------------------------------------------\n// Boot the registry from a graph\n// -----------------------------------------------------------------------------\n\nexport const buildRegistry = (\n\tgraph: ResolvedGraph,\n\tparentScope: Scope.Scope,\n\temit: (key: PluginKey, from: LifecycleStatus, to: LifecycleStatus) => Effect.Effect<void>,\n): Effect.Effect<PluginRegistry, never, never> =>\n\tEffect.gen(function* () {\n\t\tconst entries = new Map<PluginKey, PluginEntry>();\n\t\tfor (const [key, node] of graph.nodes) {\n\t\t\tconst entry = yield* makeEntry(node, parentScope);\n\t\t\tentries.set(key, entry);\n\t\t}\n\t\treturn makeRegistry(entries, emit);\n\t});\n\n// -----------------------------------------------------------------------------\n// Acquire one node\n// -----------------------------------------------------------------------------\n\n/**\n * Run one node's `start` under its own scope. Steps:\n *  1. Await upstreams (their ready-gates).\n *  2. Transition `pending → acquiring` (publishes the event).\n *  3. Build resolved dependency values from declared resource refs.\n *  4. Run the plugin's `start` Effect inside the entry's Scope,\n *     after providing the substrate-context services bundle so the\n *     plugin's R-channel yields (`IdentityContext`,\n *     `ContainerRuntimeService`, etc.) resolve to live instances.\n *  5. On success: stash the resolved value + `markReady` (publishes\n *     the `ready` transition).\n *  6. On failure: `markFailed` (publishes the `failed` transition, fails\n *     the deferred so downstream consumers short-circuit).\n *\n * Errors are caught and stashed onto the registry entry — the outer\n * scheduler doesn't propagate per-plugin failures; ready-gate failure\n * propagation handles the downstream blocking. The supervisor's outer\n * fiber surfaces the union via `Fiber.join` when the user asks for\n * \"stack ready or err\".\n */\nexport const acquireNode = (\n\tregistry: PluginRegistry,\n\tkey: PluginKey,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n\tpluginContext: Context.Context<never>,\n\tdispatcher: ContributionDispatcher,\n\tlogger: LoggerShape,\n\t// Threaded through the acquire path for parity with acquireKeys/\n\t// acquireFullGraph; no longer read here (only the removed span used it).\n\t_identity: Identity,\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 upstreamWait = awaitUpstreams(registry, entry.node).pipe(\n\t\t\tEffect.matchEffect({\n\t\t\t\tonFailure: (cause) =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* bestEffort(registry.markFailed(key, cause));\n\t\t\t\t\t\treturn false as const;\n\t\t\t\t\t}),\n\t\t\t\tonSuccess: () => Effect.succeed(true as const),\n\t\t\t}),\n\t\t);\n\t\tconst ok = yield* upstreamWait;\n\t\tif (ok !== true) {\n\t\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\t\tlevel: 'warn',\n\t\t\t\tmessage: 'plugin acquire skipped — upstream failed',\n\t\t\t});\n\t\t\treturn;\n\t\t}\n\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\tlevel: 'debug',\n\t\t\tmessage: 'plugin acquire start',\n\t\t\tfields: { role: entry.node.member.role },\n\t\t});\n\t\t// Best-effort claim. `transition` `Effect.die`s on an off-table move,\n\t\t// which a concurrent acquire can trigger: an in-flight initial\n\t\t// `acquireNode` racing a selective-restart re-acquire of the same key\n\t\t// hits `acquiring → acquiring`. `Effect.catch` (used originally here)\n\t\t// cannot catch that DEFECT, so it would escape and kill the\n\t\t// command-loop fiber (supervisor wedge — same class as the lifecycle\n\t\t// reset fix). `Effect.exit` swallows BOTH failure and defect, keeping\n\t\t// this the best-effort transition it was always meant to be.\n\t\t// NOTE: this prevents the wedge but not the underlying double-acquire\n\t\t// (two fibers running one node's `start`). A complete fix must\n\t\t// interrupt a node's in-flight acquire fiber before a restart\n\t\t// re-acquires it — tracked as a follow-up (needs per-node acquire-fiber\n\t\t// handles, which `acquireKeys`' `Effect.all` does not retain today).\n\t\tyield* Effect.exit(registry.transition(key, 'acquiring'));\n\t\tconst readDependency = buildDependencyReaderFor(registry, entry.node);\n\t\tconst deps = resolvePluginDependencies(entry.node.member, readDependency);\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\tconst start = entry.node.member.start as (\n\t\t\tdeps: unknown,\n\t\t) => Effect.Effect<unknown, unknown, any>;\n\t\t// Build the per-plugin ctx + replay buffer. Every plugin emits its\n\t\t// contributions inline via the typed `ctx` verbs during `start`; the\n\t\t// buffer is the SOLE source of the post-start dispatch.\n\t\t// The ctx is delivered through the `PluginContext` service tag (a\n\t\t// plugin reaches it with `yield* PluginContext`), provided into the\n\t\t// start Effect's requirement channel below — NOT as a 2nd positional\n\t\t// argument — which keeps `start` single-arg and `deps` auto-inferred.\n\t\tconst { ctx: pluginCtx, buffer, sealBuffer } = makePluginCtx(key);\n\t\tconst currentPluginContext = pluginContext.pipe(\n\t\t\tContext.add(CurrentPluginKey, { key }),\n\t\t\tContext.add(PluginContext, pluginCtx),\n\t\t\tContext.add(CurrentPluginProgress, {\n\t\t\t\tsetPhase: (phase) =>\n\t\t\t\t\tpublish(ref, hub, {\n\t\t\t\t\t\ttag: 'lifecycle.phaseSet',\n\t\t\t\t\t\tpluginKey: key,\n\t\t\t\t\t\tphase,\n\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t}),\n\t\t\t}),\n\t\t);\n\t\tconst providedAcquire = Effect.provide(start(deps), currentPluginContext) as Effect.Effect<\n\t\t\tunknown,\n\t\t\tunknown,\n\t\t\tScope.Scope\n\t\t>;\n\t\tconst result = yield* Scope.provide(providedAcquire, entry.scope).pipe(\n\t\t\tEffect.matchEffect({\n\t\t\t\tonFailure: (cause) =>\n\t\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\t\tyield* bestEffort(registry.markFailed(key, cause));\n\t\t\t\t\t\tyield* publish(ref, hub, {\n\t\t\t\t\t\t\ttag: 'error.reported',\n\t\t\t\t\t\t\terror: prettyErrorStructured(Cause.fail(cause), {\n\t\t\t\t\t\t\t\tpluginKey: key,\n\t\t\t\t\t\t\t\tseverity: 'error',\n\t\t\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t});\n\t\t\t\t\t\treturn { ok: false as const };\n\t\t\t\t\t}),\n\t\t\t\tonSuccess: (value: unknown) =>\n\t\t\t\t\tEffect.succeed({ ok: true as const, value: value as unknown }),\n\t\t\t}),\n\t\t);\n\t\t// PR#3: `start` has resolved — the contribution buffer is now FINAL and\n\t\t// is read exactly once below. Freeze it so any late async `ctx.*`\n\t\t// emission (a verb called from a fiber the plugin forked but did not\n\t\t// await) crashes the OFFENDING fiber with a typed defect instead of\n\t\t// being silently dropped.\n\t\tsealBuffer();\n\t\tif (result.ok) {\n\t\t\t// The ctx buffer (decls the 5 verbs pushed during `start`, in\n\t\t\t// emit order) is the SOLE source of post-start contributions.\n\t\t\t// The dispatch is a closed exhaustive switch on the decl\n\t\t\t// discriminant — its internal dual-catch keeps an\n\t\t\t// orchestrator-fault (a failing dispatch body) off the plugin's\n\t\t\t// `markFailed` path, so a surfaced failure here would be an\n\t\t\t// unexpected defect only.\n\t\t\tif (buffer.length > 0) {\n\t\t\t\tconst dispatchExit = yield* Effect.exit(\n\t\t\t\t\tdispatchBufferedContributions(\n\t\t\t\t\t\tkey,\n\t\t\t\t\t\tbuffer,\n\t\t\t\t\t\tpluginContext,\n\t\t\t\t\t\tentry.scope,\n\t\t\t\t\t\tdispatcher,\n\t\t\t\t\t\tref,\n\t\t\t\t\t\thub,\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tif (Exit.isFailure(dispatchExit)) {\n\t\t\t\t\tyield* bestEffort(registry.markFailed(key, dispatchExit.cause));\n\t\t\t\t\tyield* publish(ref, hub, {\n\t\t\t\t\t\ttag: 'error.reported',\n\t\t\t\t\t\terror: prettyErrorStructured(dispatchExit.cause, {\n\t\t\t\t\t\t\tpluginKey: key,\n\t\t\t\t\t\t\tseverity: 'error',\n\t\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t\t}),\n\t\t\t\t\t});\n\t\t\t\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\t\t\t\tlevel: 'error',\n\t\t\t\t\t\tmessage: 'plugin capability dispatch failed',\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst routablesPresent = buffer.some((decl) => decl.kind === 'routable');\n\t\t\tfor (const event of operationalEndpointEventsFromResolvedValue(\n\t\t\t\tkey,\n\t\t\t\tresult.value,\n\t\t\t\tDate.now(),\n\t\t\t\t{\n\t\t\t\t\troutablesPresent,\n\t\t\t\t},\n\t\t\t)) {\n\t\t\t\tyield* publish(ref, hub, event);\n\t\t\t}\n\t\t\tyield* publish(ref, hub, {\n\t\t\t\ttag: 'lifecycle.phaseSet',\n\t\t\t\tpluginKey: key,\n\t\t\t\tphase: null,\n\t\t\t\tat: Date.now(),\n\t\t\t});\n\t\t\tyield* bestEffort(registry.markReady(key, result.value));\n\t\t\tif (entry.node.member.role === 'task') {\n\t\t\t\tyield* bestEffort(registry.transition(key, 'done'));\n\t\t\t}\n\t\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\t\tlevel: 'debug',\n\t\t\t\tmessage: entry.node.member.role === 'task' ? 'plugin done' : 'plugin ready',\n\t\t\t\tfields: {\n\t\t\t\t\tcontributions: buffer.length,\n\t\t\t\t},\n\t\t\t});\n\t\t} else {\n\t\t\tyield* logger.log(`supervisor/${key}`, key, {\n\t\t\t\tlevel: 'debug',\n\t\t\t\tmessage: 'plugin acquire failed',\n\t\t\t});\n\t\t}\n\t});\n\nclass PluginAcquireInterruptedBeforeReady extends Error {\n\treadonly _tag = 'PluginAcquireInterruptedBeforeReady' as const;\n\tconstructor(readonly pluginKey: PluginKey) {\n\t\tsuper(`plugin '${pluginKey}' acquire was interrupted before readiness`);\n\t\tthis.name = 'PluginAcquireInterruptedBeforeReady';\n\t}\n}\n\nconst failIfAcquireInterruptedBeforeReady = (\n\tregistry: PluginRegistry,\n\tkey: PluginKey,\n\tentry: PluginEntry,\n): Effect.Effect<void, never, never> =>\n\tEffect.gen(function* () {\n\t\tif (registry.entries.get(key) !== entry) return;\n\t\tconst status = yield* registry\n\t\t\t.getStatus(key)\n\t\t\t.pipe(Effect.catch(() => Effect.succeed<LifecycleStatus | null>(null)));\n\t\tif (registry.entries.get(key) !== entry) return;\n\t\tif (status !== 'pending' && status !== 'acquiring') return;\n\t\tyield* bestEffort(registry.markFailed(key, new PluginAcquireInterruptedBeforeReady(key)));\n\t});\n\n// -----------------------------------------------------------------------------\n// Acquire a key set in parallel. Each node waits on its own upstreams,\n// so downstream nodes begin as soon as their dependencies are ready\n// instead of waiting for unrelated nodes in the same topological level.\n// -----------------------------------------------------------------------------\n\nexport const acquireKeys = (\n\tregistry: PluginRegistry,\n\tkeys: ReadonlyArray<PluginKey>,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n\tpluginContext: Context.Context<never>,\n\tdispatcher: ContributionDispatcher,\n\tlogger: LoggerShape,\n\tidentity: Identity,\n\tparentScope: Scope.Scope,\n): Effect.Effect<void, never, never> =>\n\tEffect.gen(function* () {\n\t\tconst fibers = yield* Effect.all(\n\t\t\tkeys.map((key) =>\n\t\t\t\tEffect.gen(function* () {\n\t\t\t\t\tconst entry = registry.entries.get(key);\n\t\t\t\t\tif (entry === undefined) return yield* Effect.forkIn(Effect.void, parentScope);\n\t\t\t\t\tconst registeredGate = yield* Deferred.make<void, never>();\n\t\t\t\t\tconst readyToRegister = yield* Deferred.make<void, never>();\n\t\t\t\t\tconst guarded = Effect.gen(function* () {\n\t\t\t\t\t\tconst selfId = yield* Effect.fiberId;\n\t\t\t\t\t\tyield* Effect.gen(function* () {\n\t\t\t\t\t\t\tyield* Deferred.succeed(readyToRegister, void 0);\n\t\t\t\t\t\t\tyield* Deferred.await(registeredGate);\n\t\t\t\t\t\t\tyield* acquireNode(\n\t\t\t\t\t\t\t\tregistry,\n\t\t\t\t\t\t\t\tkey,\n\t\t\t\t\t\t\t\tref,\n\t\t\t\t\t\t\t\thub,\n\t\t\t\t\t\t\t\tpluginContext,\n\t\t\t\t\t\t\t\tdispatcher,\n\t\t\t\t\t\t\t\tlogger,\n\t\t\t\t\t\t\t\tidentity,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t}).pipe(\n\t\t\t\t\t\t\tEffect.onInterrupt(() => failIfAcquireInterruptedBeforeReady(registry, key, entry)),\n\t\t\t\t\t\t\tEffect.ensuring(\n\t\t\t\t\t\t\t\tregistry\n\t\t\t\t\t\t\t\t\t.clearAcquireFiberIfEntry(key, entry, selfId)\n\t\t\t\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.void)),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t});\n\t\t\t\t\tconst fiber = yield* Effect.forkIn(Scope.provide(guarded, parentScope), parentScope);\n\t\t\t\t\tyield* Deferred.await(readyToRegister);\n\t\t\t\t\tconst registered = yield* registry\n\t\t\t\t\t\t.setAcquireFiberIfEntry(key, entry, fiber)\n\t\t\t\t\t\t.pipe(Effect.catch(() => Effect.succeed(false)));\n\t\t\t\t\tif (!registered) {\n\t\t\t\t\t\tyield* Fiber.interrupt(fiber).pipe(Effect.asVoid);\n\t\t\t\t\t\treturn fiber;\n\t\t\t\t\t}\n\t\t\t\t\tyield* Deferred.succeed(registeredGate, void 0);\n\t\t\t\t\treturn fiber;\n\t\t\t\t}),\n\t\t\t),\n\t\t\t{ concurrency: 'unbounded' },\n\t\t);\n\t\tyield* Effect.all(\n\t\t\tfibers.map((fiber) =>\n\t\t\t\tFiber.await(fiber).pipe(\n\t\t\t\t\tEffect.flatMap((exit) => {\n\t\t\t\t\t\tif (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause)) {\n\t\t\t\t\t\t\treturn Effect.void;\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn Effect.failCause(exit.cause);\n\t\t\t\t\t}),\n\t\t\t\t),\n\t\t\t),\n\t\t\t{ concurrency: 'unbounded', discard: true },\n\t\t);\n\t});\n\nexport const acquireFullGraph = (\n\tgraph: ResolvedGraph,\n\tregistry: PluginRegistry,\n\tref: SubscriptionRef.SubscriptionRef<SubscribableState>,\n\thub: Queue.Enqueue<EngineEvent>,\n\tpluginContext: Context.Context<never>,\n\tdispatcher: ContributionDispatcher,\n\tlogger: LoggerShape,\n\tidentity: Identity,\n\tparentScope: Scope.Scope,\n): Effect.Effect<void, never, never> =>\n\tEffect.gen(function* () {\n\t\tyield* acquireKeys(\n\t\t\tregistry,\n\t\t\t[...graph.nodes.keys()],\n\t\t\tref,\n\t\t\thub,\n\t\t\tpluginContext,\n\t\t\tdispatcher,\n\t\t\tlogger,\n\t\t\tidentity,\n\t\t\tparentScope,\n\t\t);\n\t});\n"],"mappings":"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"}

package/dist/substrate/runtime/supervisor/background-tasks.mjs

@@ -3,26 +3,40 @@ import { prettyErrorStructured } from "../observability/pretty-error.mjs";
 import "../observability/index.mjs";
 import { bestEffort, publish } from "./wiring.mjs";
 import { PostAcquireTaskFailed } from "../post-acquire-tasks.mjs";
-import { Cause, Effect, Exit, Fiber, Ref } from "effect";
+import { Cause, Effect, Exit, Fiber, Ref, Scope } from "effect";
 //#region src/substrate/runtime/supervisor/background-tasks.ts
 /** `snapshot.captureFailed` / `snapshot.captureSkipped` carry a REQUIRED
 *  `snapshotId`. When the originating command carried an id, surfaces
 *  correlate the outcome with it (the CLI's pending-capture map keys on
 *  it). When the command omitted an id there is nothing to correlate
 *  against — the CLI's bridge does NOT register a pending-capture entry
-*  for an id-less capture (`cli/wirings/up.ts` falls through to a
-*  legacy auto-ack and never keys this synthetic id) — so the minted
+*  for an id-less capture (`cli/wirings/up.ts` falls through to a plain
+*  auto-ack and never keys this synthetic id) — so the minted
 *  `snap-<ts>` here only satisfies the event's required field. */
 const effectiveSnapshotId = (cmd) => cmd.snapshotId ?? `snap-${Date.now()}`;
-const runInjectedCommandHandler = (deps, cmd) => Effect.gen(function* () {
-	if (deps.commandHandler === void 0) return;
+/**
+* Run the injected L3 command handler and report the typed outcome.
+*
+* On success the handler's events are published and `ok: true` is
+* returned. On failure the failure is surfaced on the event stream
+* (`snapshot.captureFailed` for a capture, plus `error.reported`) AND
+* the cause is returned to the caller so a command that must NOT
+* proceed on a half-applied handler (e.g. `snapshot.restore`, which
+* otherwise drains + re-acquires every service off a half-restored
+* tree) can short-circuit and propagate the failure to `submitCommand`.
+*
+* Interrupt-only causes return `ok: true` (the interrupting sibling
+* owns the lifecycle decision) — same as the void runner below.
+*/
+const runInjectedCommandHandlerExit = (deps, cmd) => Effect.gen(function* () {
+	if (deps.commandHandler === void 0) return { ok: true };
 	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;
+		return { ok: true };
 	}
-	if (Cause.hasInterruptsOnly(exit.cause)) return;
+	if (Cause.hasInterruptsOnly(exit.cause)) return { ok: true };
 	if (cmd.tag === "snapshot.capture") yield* publish(deps.ref, deps.hub, {
 		tag: "snapshot.captureFailed",
 		snapshotId: effectiveSnapshotId(cmd),
@@ -42,65 +56,65 @@ const runInjectedCommandHandler = (deps, cmd) => Effect.gen(function* () {
 		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",
-			snapshotId: effectiveSnapshotId(cmd),
-			...cmd.name === void 0 ? {} : { name: cmd.name },
-			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()
+	return {
+		ok: false,
+		cause: exit.cause
+	};
+});
+/**
+* Fire-and-forget wrapper over {@link runInjectedCommandHandlerExit}:
+* the handler's failure is already surfaced on the event stream, so the
+* void channel suffices for capture / list / delete / wipe / prune,
+* whose callers don't branch on the outcome.
+*/
+const runInjectedCommandHandler = (deps, cmd) => Effect.asVoid(runInjectedCommandHandlerExit(deps, cmd));
+/**
+* Fork `body` into the supervisor-lifetime scope and claim a background
+* task slot atomically.
+*
+* `Effect.forkIn(supervisorScope)` parents the fiber to the supervisor's
+* lifetime — NOT the command-loop fiber that triggered it — so a
+* long-running capture/restart does not block the command loop and
+* cannot wedge a subsequent `shutdown.requested` (Bug #13). The forked
+* fiber is created suspended (`forkIn`'s default `startImmediately`), so
+* the CAS below runs before it executes a single step.
+*
+* Skip-dedup: the slot is the running state. If it is already occupied
+* the just-forked fiber is interrupted (it never ran) and the function
+* returns `'skipped'` so the caller can publish/log the skip. Otherwise
+* the fiber is installed, its `ensuring` clears the slot on completion,
+* and the function returns `'started'`.
+*/
+const forkIntoSlot = (supervisorScope, slot, body) => Effect.gen(function* () {
+	const guarded = Effect.gen(function* () {
+		const selfId = yield* Effect.fiberId;
+		yield* body.pipe(Effect.ensuring(Ref.update(slot, (current) => current !== null && current.id === selfId ? null : current)));
 	});
-	const fiber = yield* runInjectedCommandHandler(deps, cmd).pipe(Effect.ensuring(Ref.update(deps.snapshotCaptureTask, (state) => state.tag !== "idle" && state.token === token ? { tag: "idle" } : state)), Effect.forkScoped);
-	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* Fiber.interrupt(fiber);
-}).pipe(Effect.withSpan("lifecycle.supervisor.interruptSnapshotCapture"));
-const startBackgroundStackRestart = (deps, handleCommand) => 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* Effect.forkIn(Scope.provide(guarded, supervisorScope), supervisorScope);
+	if (!(yield* Ref.modify(slot, (current) => current === null ? [true, fiber] : [false, current]))) {
+		yield* Fiber.interrupt(fiber);
+		return "skipped";
 	}
-	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.forkScoped);
-	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]);
+	return "started";
+});
+/**
+* Read-and-clear a background task slot, then await the fiber's
+* interrupt. Awaiting matters: a follow-up snapshot capture must not
+* begin while the previous fiber is still inside `pauseAndCommit` /
+* `saveImages`, and shutdown must not race a half-torn-down restart.
+*/
+const interruptSlot = (slot) => Effect.gen(function* () {
+	const fiber = yield* Ref.getAndSet(slot, null);
 	if (fiber !== null) yield* Fiber.interrupt(fiber);
-}).pipe(Effect.withSpan("lifecycle.supervisor.interruptStackRestart"));
-const publishHookFailure = (deps, cause, message, pluginKey = null) => Effect.gen(function* () {
+});
+const startBackgroundStackRestart = (deps, handleCommand) => Effect.gen(function* () {
+	if ((yield* forkIntoSlot(deps.supervisorScope, deps.stackRestartTask, handleCommand(deps, { tag: "stack.restart" }).pipe(Effect.catch(() => Effect.void)))) === "skipped") yield* deps.logger.log("supervisor", null, {
+		level: "debug",
+		message: "stack restart skipped because one is already running"
+	});
+});
+const requestBackgroundStackRestartInterrupt = (deps) => interruptSlot(deps.stackRestartTask);
+const publishHookFailure = (deps, cause, message, pluginKey) => Effect.gen(function* () {
 	yield* publish(deps.ref, deps.hub, {
 		tag: "error.reported",
 		error: prettyErrorStructured(cause, {
@@ -137,8 +151,8 @@ const runPostAcquireHook = (deps) => Effect.gen(function* () {
 	if (taskFailure !== null) yield* bestEffort(deps.registry.markFailed(taskFailure.pluginKey, taskFailure.cause));
 	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"));
+});
 //#endregion
-export { requestBackgroundSnapshotInterrupt, requestBackgroundStackRestartInterrupt, runInjectedCommandHandler, runPostAcquireHook, startBackgroundSnapshotCapture, startBackgroundStackRestart };
+export { requestBackgroundStackRestartInterrupt, runInjectedCommandHandler, runInjectedCommandHandlerExit, runPostAcquireHook, startBackgroundStackRestart };
 
 //# sourceMappingURL=background-tasks.mjs.map