@mysten-incubation/devstack 0.0.0

package/dist/substrate/runtime/lifecycle/lifecycle-fact.mjs

@@ -0,0 +1,31 @@
+//#region src/substrate/runtime/lifecycle/lifecycle-fact.ts
+/** Project a lifecycle-shaped `EngineEvent` into a per-plugin delta.
+*  Returns `null` for events that don't carry lifecycle information so
+*  the reducer can short-circuit. The substrate stays event-name-blind
+*  by routing through this single mapping table. */
+const factFromEvent = (event) => {
+	switch (event.tag) {
+		case "lifecycle.statusChanged": return {
+			pluginKey: event.pluginKey,
+			delta: { status: event.to }
+		};
+		case "lifecycle.phaseSet": return {
+			pluginKey: event.pluginKey,
+			delta: { phase: event.phase }
+		};
+		default: return null;
+	}
+};
+/** Apply a fact delta to a row. Pure. Fields not in the delta are
+*  preserved verbatim — the merge-not-replace shape `LifecycleFact`
+*  promises. */
+const applyLifecycleFact = (row, delta) => ({
+	...row,
+	...delta.status !== void 0 ? { status: delta.status } : {},
+	...delta.phase !== void 0 ? { phase: delta.phase } : {},
+	...delta.selectiveRestartHighlight !== void 0 ? { selectiveRestartHighlight: delta.selectiveRestartHighlight } : {}
+});
+//#endregion
+export { applyLifecycleFact, factFromEvent };
+
+//# sourceMappingURL=lifecycle-fact.mjs.map

package/dist/substrate/runtime/lifecycle/lifecycle-fact.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-fact.mjs","names":[],"sources":["../../../../src/substrate/runtime/lifecycle/lifecycle-fact.ts"],"sourcesContent":["// LifecycleFact bridge.\n//\n// `substrate/lifecycle.ts` declares `LifecycleFact` — the merge-not-\n// replace per-plugin lifecycle slice the projection consumes. Until\n// now the projection updater consumed raw `EngineEvent` cases directly\n// and the `LifecycleFact` type was orphan.\n//\n// This module is the typed bridge: it projects an `EngineEvent` into a\n// `LifecycleFact` delta (when the event represents a lifecycle change)\n// and exposes a single applier `applyLifecycleFact(row, fact)` the\n// projection updater calls instead of writing out each\n// status / phase / restart field independently. The reducer for non-\n// lifecycle events is unchanged.\n\nimport type { Row } from '../../projection.ts';\nimport type { LifecycleFact, LifecycleStatus } from '../../lifecycle.ts';\nimport type { EngineEvent } from '../../events.ts';\n\n/** Per-plugin fact delta. Each field is optional — only the fields the\n *  source event carries are populated. The projection's `applyLifecycleFact`\n *  merges a delta into the existing `Row`. */\nexport interface LifecycleFactDelta {\n\treadonly status?: LifecycleStatus;\n\treadonly phase?: LifecycleFact['phase'];\n\treadonly selectiveRestartHighlight?: boolean;\n}\n\n/** Project a lifecycle-shaped `EngineEvent` into a per-plugin delta.\n *  Returns `null` for events that don't carry lifecycle information so\n *  the reducer can short-circuit. The substrate stays event-name-blind\n *  by routing through this single mapping table. */\nexport const factFromEvent = (\n\tevent: EngineEvent,\n): { readonly pluginKey: string; readonly delta: LifecycleFactDelta } | null => {\n\tswitch (event.tag) {\n\t\tcase 'lifecycle.statusChanged':\n\t\t\treturn {\n\t\t\t\tpluginKey: event.pluginKey,\n\t\t\t\tdelta: { status: event.to },\n\t\t\t};\n\t\tcase 'lifecycle.phaseSet':\n\t\t\treturn {\n\t\t\t\tpluginKey: event.pluginKey,\n\t\t\t\tdelta: { phase: event.phase },\n\t\t\t};\n\t\tdefault:\n\t\t\t// `restart.requested` ALSO updates cycle.phase + clears\n\t\t\t// other rows' highlights — that's a multi-row reducer\n\t\t\t// concern the projection handles directly. We deliberately\n\t\t\t// keep the bridge scoped to the closed `LifecycleFact`\n\t\t\t// shape (status / phase / selectiveRestartHighlight) so\n\t\t\t// callers can derive per-plugin facts without rebuilding\n\t\t\t// the cycle phase too.\n\t\t\treturn null;\n\t}\n};\n\n/** Apply a fact delta to a row. Pure. Fields not in the delta are\n *  preserved verbatim — the merge-not-replace shape `LifecycleFact`\n *  promises. */\nexport const applyLifecycleFact = (row: Row, delta: LifecycleFactDelta): Row => ({\n\t...row,\n\t...(delta.status !== undefined ? { status: delta.status } : {}),\n\t...(delta.phase !== undefined ? { phase: delta.phase } : {}),\n\t...(delta.selectiveRestartHighlight !== undefined\n\t\t? { selectiveRestartHighlight: delta.selectiveRestartHighlight }\n\t\t: {}),\n});\n\n/** Reconstruct the closed `LifecycleFact` shape from a `Row`. Used by\n *  diagnostic surfaces that want the typed fact instead of the wider\n *  display Row. */\nexport const factFromRow = (row: Row): LifecycleFact => ({\n\tstatus: row.status,\n\tphase: row.phase,\n\tselectiveRestartHighlight: row.selectiveRestartHighlight,\n});\n"],"mappings":";;;;;AA+BA,MAAa,iBACZ,UAC+E;AAC/E,SAAQ,MAAM,KAAd;EACC,KAAK,0BACJ,QAAO;GACN,WAAW,MAAM;GACjB,OAAO,EAAE,QAAQ,MAAM,IAAI;GAC3B;EACF,KAAK,qBACJ,QAAO;GACN,WAAW,MAAM;GACjB,OAAO,EAAE,OAAO,MAAM,OAAO;GAC7B;EACF,QAQC,QAAO;;;;;;AAOV,MAAa,sBAAsB,KAAU,WAAoC;CAChF,GAAG;CACH,GAAI,MAAM,WAAW,KAAA,IAAY,EAAE,QAAQ,MAAM,QAAQ,GAAG,EAAE;CAC9D,GAAI,MAAM,UAAU,KAAA,IAAY,EAAE,OAAO,MAAM,OAAO,GAAG,EAAE;CAC3D,GAAI,MAAM,8BAA8B,KAAA,IACrC,EAAE,2BAA2B,MAAM,2BAA2B,GAC9D,EAAE;CACL"}

package/dist/substrate/runtime/lifecycle/plugin-registry.d.mts

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

package/dist/substrate/runtime/lifecycle/plugin-registry.mjs

@@ -0,0 +1,133 @@
+import { assertTransition } from "./state-machine.mjs";
+import { Data, Deferred, Effect, Ref, Scope } from "effect";
+//#region src/substrate/runtime/lifecycle/plugin-registry.ts
+/** Tagged failure: a plugin's `start` rejected. Carries the cause and
+*  the failing plugin's key so the cause walker / cascade formatter can
+*  attribute it. */
+var PluginAcquireFailed = class extends Data.TaggedError("PluginAcquireFailed") {};
+/** Tagged failure: a downstream plugin tried to read a resolved value
+*  whose entry isn't registered or hasn't reached `ready`. Programmer-
+*  level error class — the dep-graph guarantees this can't happen on
+*  the supervisor's own scheduling path. Surfaced when a plugin author
+*  reaches outside their declared dependencies. */
+var UnknownDependency = class extends Data.TaggedError("UnknownDependency") {};
+/** Build a fresh entry for `node`. Caller still owns the entry — the
+*  registry below holds a `ReadonlyMap` of these. */
+const makeEntry = (node, parentScope) => Effect.gen(function* () {
+	return {
+		node,
+		statusRef: yield* Ref.make("pending"),
+		readyGate: yield* Deferred.make(),
+		scope: yield* Scope.fork(parentScope)
+	};
+});
+/** Build a registry from a map of entries. The `onTransition` callback
+*  is the supervisor's published event sink — every status change
+*  flows through here. */
+const makeRegistry = (entries, onTransition) => {
+	const mutableEntries = new Map(entries);
+	const resolved = /* @__PURE__ */ new Map();
+	const getEntry = (key) => {
+		const entry = mutableEntries.get(key);
+		if (entry === void 0) return Effect.fail(new UnknownDependency({
+			pluginKey: key,
+			requestedResourceId: ""
+		}));
+		return Effect.succeed(entry);
+	};
+	return {
+		entries: mutableEntries,
+		__resolved: resolved,
+		getStatus: (key) => Effect.gen(function* () {
+			const entry = yield* getEntry(key);
+			return yield* Ref.get(entry.statusRef);
+		}),
+		transition: (key, to) => Effect.gen(function* () {
+			const entry = yield* getEntry(key);
+			const from = yield* Ref.get(entry.statusRef);
+			yield* assertTransition(from, to);
+			yield* Ref.set(entry.statusRef, to);
+			yield* onTransition(key, from, to);
+			return {
+				from,
+				to
+			};
+		}),
+		markReady: (key, value) => Effect.gen(function* () {
+			const entry = yield* getEntry(key);
+			const from = yield* Ref.get(entry.statusRef);
+			resolved.set(key, value);
+			if (from !== "ready") if (from === "pending") {
+				yield* assertTransition(from, "acquiring");
+				yield* Ref.set(entry.statusRef, "acquiring");
+				yield* onTransition(key, from, "acquiring");
+				yield* assertTransition("acquiring", "ready");
+				yield* Ref.set(entry.statusRef, "ready");
+				yield* onTransition(key, "acquiring", "ready");
+			} else {
+				yield* assertTransition(from, "ready");
+				yield* Ref.set(entry.statusRef, "ready");
+				yield* onTransition(key, from, "ready");
+			}
+			yield* Deferred.succeed(entry.readyGate, value);
+		}),
+		markFailed: (key, cause) => Effect.gen(function* () {
+			const entry = yield* getEntry(key);
+			const from = yield* Ref.get(entry.statusRef);
+			resolved.delete(key);
+			yield* assertTransition(from, "failed");
+			yield* Ref.set(entry.statusRef, "failed");
+			yield* onTransition(key, from, "failed");
+			yield* Deferred.fail(entry.readyGate, new PluginAcquireFailed({
+				pluginKey: key,
+				cause
+			}));
+		}),
+		resetForRestart: (key, parentScope) => Effect.gen(function* () {
+			const entry = yield* getEntry(key);
+			resolved.delete(key);
+			const readyGate = yield* Deferred.make();
+			const scope = yield* Scope.fork(parentScope);
+			mutableEntries.set(key, {
+				node: entry.node,
+				statusRef: entry.statusRef,
+				readyGate,
+				scope
+			});
+		}),
+		awaitReady: (key) => Effect.gen(function* () {
+			const entry = yield* getEntry(key);
+			return yield* Deferred.await(entry.readyGate);
+		})
+	};
+};
+/** Synchronous accessor: snapshot the resolved value for `key`.
+*  Returns `undefined` if the plugin isn't ready yet OR isn't
+*  registered. The supervisor guarantees readiness before any
+*  consumer calls this; it's the ONLY synchronous path. */
+const readResolvedSync = (registry, key) => {
+	return registry.__resolved?.get(key);
+};
+/**
+* Build a synchronous dependency reader over the registry for one
+* plugin. The upstream key must already be `ready`; the supervisor
+* ensures this by awaiting upstream ready-gates before invoking start.
+*/
+const buildDependencyReaderFor = (registry, node) => {
+	const resourceIdToKey = /* @__PURE__ */ new Map();
+	node.upstreamResources.forEach((resource, i) => {
+		const upstream = node.upstreamKeys[i];
+		if (upstream !== void 0) resourceIdToKey.set(resource.id, upstream);
+	});
+	return (resource) => {
+		const key = resourceIdToKey.get(resource.id);
+		if (key === void 0) throw new Error(`DependencyReader: resource '${resource.id}' not in this plugin's declared dependencies`);
+		const value = readResolvedSync(registry, key);
+		if (value === void 0) throw new Error(`DependencyReader: upstream '${key}' has no resolved value yet — supervisor must mark the entry ready before downstream acquire.`);
+		return value;
+	};
+};
+//#endregion
+export { buildDependencyReaderFor, makeEntry, makeRegistry, readResolvedSync };
+
+//# sourceMappingURL=plugin-registry.mjs.map

package/dist/substrate/runtime/lifecycle/plugin-registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.mjs","names":[],"sources":["../../../../src/substrate/runtime/lifecycle/plugin-registry.ts"],"sourcesContent":["// Per-plugin lifecycle bookkeeping.\n//\n// One `PluginEntry` per node in the resolved dep-graph. The entry\n// holds:\n//   - the live `LifecycleStatus` (Ref, single-fiber linearizable),\n//   - the resolved value (set when status transitions to `ready`),\n//   - the scope owning the plugin's `start` finalizers,\n//   - a `Deferred` that downstream consumers await for the ready gate.\n//\n// The registry tracks per-key lifecycle only; projection concerns stay\n// in the supervisor and reducer.\n\nimport { Data, Deferred, Effect, Ref, Scope } from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport type { LifecycleStatus } from '../../lifecycle.ts';\nimport type { DepNode } from './dep-graph.ts';\nimport { assertTransition } from './state-machine.ts';\n\n/** Per-registry side channel: synchronously-readable resolved values.\n *  Keyed by plugin key. Populated by `markReady`; consulted by the\n *  synchronous dependency reader. We can't put the value on the\n *  `Deferred` itself in a publicly-supported way, and plugin start\n *  receives dependency values synchronously; this is the safe escape hatch.\n *\n *  Module-private; only `makeRegistry` writes into the map it\n *  allocates. */\ntype ResolvedMap = Map<PluginKey, ResolvedValue>;\n\n// -----------------------------------------------------------------------------\n// Resolved-value shape\n// -----------------------------------------------------------------------------\n\n/** Erased resolved value held in the registry. The supervisor casts\n *  back to the concrete type at the boundary where it threads the\n *  value into a downstream plugin's resolved dependency object. */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport type ResolvedValue = any;\n\n// -----------------------------------------------------------------------------\n// Per-plugin entry\n// -----------------------------------------------------------------------------\n\n/** Mutable lifecycle state for one plugin instance. */\nexport interface PluginEntry {\n\treadonly node: DepNode;\n\treadonly statusRef: Ref.Ref<LifecycleStatus>;\n\t/** Resolved when the plugin reaches `ready`. Downstream consumers\n\t *  await this in the ready-gate. Failure is propagated by interruption\n\t *  via `Deferred.fail` to keep the error chain in the cause walker. */\n\treadonly readyGate: Deferred.Deferred<ResolvedValue, PluginAcquireFailed>;\n\t/** Per-plugin Scope. Closing it runs the `start` finalizers. */\n\treadonly scope: Scope.Closeable;\n}\n\n/** Tagged failure: a plugin's `start` rejected. Carries the cause and\n *  the failing plugin's key so the cause walker / cascade formatter can\n *  attribute it. */\nexport class PluginAcquireFailed extends Data.TaggedError('PluginAcquireFailed')<{\n\treadonly pluginKey: PluginKey;\n\treadonly cause: unknown;\n}> {}\n\n/** Tagged failure: a downstream plugin tried to read a resolved value\n *  whose entry isn't registered or hasn't reached `ready`. Programmer-\n *  level error class — the dep-graph guarantees this can't happen on\n *  the supervisor's own scheduling path. Surfaced when a plugin author\n *  reaches outside their declared dependencies. */\nexport class UnknownDependency extends Data.TaggedError('UnknownDependency')<{\n\treadonly pluginKey: PluginKey;\n\treadonly requestedResourceId: string;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Registry\n// -----------------------------------------------------------------------------\n\n/** Build a fresh entry for `node`. Caller still owns the entry — the\n *  registry below holds a `ReadonlyMap` of these. */\nexport const makeEntry = (\n\tnode: DepNode,\n\tparentScope: Scope.Scope,\n): Effect.Effect<PluginEntry, never, never> =>\n\tEffect.gen(function* () {\n\t\tconst statusRef = yield* Ref.make<LifecycleStatus>('pending');\n\t\tconst readyGate = yield* Deferred.make<ResolvedValue, PluginAcquireFailed>();\n\t\tconst scope = yield* Scope.fork(parentScope);\n\t\treturn { node, statusRef, readyGate, scope } satisfies PluginEntry;\n\t});\n\n/** The lifecycle registry. Holds one entry per dep-graph node. */\nexport interface PluginRegistry {\n\treadonly entries: ReadonlyMap<PluginKey, PluginEntry>;\n\t/** Read a plugin's current status. */\n\treadonly getStatus: (key: PluginKey) => Effect.Effect<LifecycleStatus, UnknownDependency>;\n\t/** Transition a plugin to a new status. Validates against the\n\t *  transition table; emits via `onTransition`. */\n\treadonly transition: (\n\t\tkey: PluginKey,\n\t\tto: LifecycleStatus,\n\t) => Effect.Effect<\n\t\t{ readonly from: LifecycleStatus; readonly to: LifecycleStatus },\n\t\tUnknownDependency\n\t>;\n\t/** Mark a plugin ready with its resolved value. */\n\treadonly markReady: (\n\t\tkey: PluginKey,\n\t\tvalue: ResolvedValue,\n\t) => Effect.Effect<void, UnknownDependency>;\n\t/** Mark a plugin failed. */\n\treadonly markFailed: (key: PluginKey, cause: unknown) => Effect.Effect<void, UnknownDependency>;\n\t/** Prepare a previously torn-down entry for hot restart. Plugin\n\t *  scopes and ready gates are single-use: once a scope has been closed,\n\t *  any finalizer registered during a later acquire would run\n\t *  immediately, and an already-resolved ready gate would leak the old\n\t *  value to downstream consumers. */\n\treadonly resetForRestart: (\n\t\tkey: PluginKey,\n\t\tparentScope: Scope.Scope,\n\t) => Effect.Effect<void, UnknownDependency>;\n\t/** Await `ready` for `key`. Suspends until the plugin's `readyGate`\n\t *  resolves. The deferred's failure channel propagates a\n\t *  `PluginAcquireFailed` so the supervisor's outer error path picks\n\t *  it up. */\n\treadonly awaitReady: (\n\t\tkey: PluginKey,\n\t) => Effect.Effect<ResolvedValue, PluginAcquireFailed | UnknownDependency>;\n}\n\n/** Build a registry from a map of entries. The `onTransition` callback\n *  is the supervisor's published event sink — every status change\n *  flows through here. */\nexport const makeRegistry = (\n\tentries: ReadonlyMap<PluginKey, PluginEntry>,\n\tonTransition: (key: PluginKey, from: LifecycleStatus, to: LifecycleStatus) => Effect.Effect<void>,\n): PluginRegistry => {\n\tconst mutableEntries = new Map(entries);\n\tconst resolved: ResolvedMap = new Map();\n\n\tconst getEntry = (key: PluginKey): Effect.Effect<PluginEntry, UnknownDependency> => {\n\t\tconst entry = mutableEntries.get(key);\n\t\tif (entry === undefined) {\n\t\t\treturn Effect.fail(new UnknownDependency({ pluginKey: key, requestedResourceId: '' }));\n\t\t}\n\t\treturn Effect.succeed(entry);\n\t};\n\n\tconst reg: PluginRegistry & { __resolved: ResolvedMap } = {\n\t\tentries: mutableEntries,\n\t\t__resolved: resolved,\n\t\tgetStatus: (key) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entry = yield* getEntry(key);\n\t\t\t\treturn yield* Ref.get(entry.statusRef);\n\t\t\t}),\n\t\ttransition: (key, to) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entry = yield* getEntry(key);\n\t\t\t\tconst from = yield* Ref.get(entry.statusRef);\n\t\t\t\tyield* assertTransition(from, to);\n\t\t\t\tyield* Ref.set(entry.statusRef, to);\n\t\t\t\tyield* onTransition(key, from, to);\n\t\t\t\treturn { from, to };\n\t\t\t}),\n\t\tmarkReady: (key, value) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entry = yield* getEntry(key);\n\t\t\t\tconst from = yield* Ref.get(entry.statusRef);\n\t\t\t\tresolved.set(key, value);\n\t\t\t\tif (from !== 'ready') {\n\t\t\t\t\t// `pending → ready` is off-table — the state machine\n\t\t\t\t\t// requires the intermediate `acquiring` hop. Bridge it\n\t\t\t\t\t// here so callers reaching `markReady` from a `pending`\n\t\t\t\t\t// entry (test fixtures, callers that mark a synthetic\n\t\t\t\t\t// already-resolved value) don't have to pre-walk the\n\t\t\t\t\t// machine. Both transitions still emit through\n\t\t\t\t\t// `onTransition` so subscribers see the full path.\n\t\t\t\t\tif (from === 'pending') {\n\t\t\t\t\t\tyield* assertTransition(from, 'acquiring');\n\t\t\t\t\t\tyield* Ref.set(entry.statusRef, 'acquiring');\n\t\t\t\t\t\tyield* onTransition(key, from, 'acquiring');\n\t\t\t\t\t\tyield* assertTransition('acquiring', 'ready');\n\t\t\t\t\t\tyield* Ref.set(entry.statusRef, 'ready');\n\t\t\t\t\t\tyield* onTransition(key, 'acquiring', 'ready');\n\t\t\t\t\t} else {\n\t\t\t\t\t\tyield* assertTransition(from, 'ready');\n\t\t\t\t\t\tyield* Ref.set(entry.statusRef, 'ready');\n\t\t\t\t\t\tyield* onTransition(key, from, 'ready');\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tyield* Deferred.succeed(entry.readyGate, value);\n\t\t\t}),\n\t\tmarkFailed: (key, cause) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entry = yield* getEntry(key);\n\t\t\t\tconst from = yield* Ref.get(entry.statusRef);\n\t\t\t\tresolved.delete(key);\n\t\t\t\tyield* assertTransition(from, 'failed');\n\t\t\t\tyield* Ref.set(entry.statusRef, 'failed');\n\t\t\t\tyield* onTransition(key, from, 'failed');\n\t\t\t\tyield* Deferred.fail(entry.readyGate, new PluginAcquireFailed({ pluginKey: key, cause }));\n\t\t\t}),\n\t\tresetForRestart: (key, parentScope) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entry = yield* getEntry(key);\n\t\t\t\tresolved.delete(key);\n\t\t\t\tconst readyGate = yield* Deferred.make<ResolvedValue, PluginAcquireFailed>();\n\t\t\t\tconst scope = yield* Scope.fork(parentScope);\n\t\t\t\tmutableEntries.set(key, {\n\t\t\t\t\tnode: entry.node,\n\t\t\t\t\tstatusRef: entry.statusRef,\n\t\t\t\t\treadyGate,\n\t\t\t\t\tscope,\n\t\t\t\t});\n\t\t\t}),\n\t\tawaitReady: (key) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst entry = yield* getEntry(key);\n\t\t\t\treturn yield* Deferred.await(entry.readyGate);\n\t\t\t}),\n\t};\n\treturn reg;\n};\n\n/** Synchronous accessor: snapshot the resolved value for `key`.\n *  Returns `undefined` if the plugin isn't ready yet OR isn't\n *  registered. The supervisor guarantees readiness before any\n *  consumer calls this; it's the ONLY synchronous path. */\nexport const readResolvedSync = (\n\tregistry: PluginRegistry,\n\tkey: PluginKey,\n): ResolvedValue | undefined => {\n\tconst resolved = (registry as PluginRegistry & { __resolved?: ResolvedMap }).__resolved;\n\treturn resolved?.get(key);\n};\n\n// -----------------------------------------------------------------------------\n// Dependency reader over the registry\n// -----------------------------------------------------------------------------\n\n/**\n * Build a synchronous dependency reader over the registry for one\n * plugin. The upstream key must already be `ready`; the supervisor\n * ensures this by awaiting upstream ready-gates before invoking start.\n */\nexport const buildDependencyReaderFor = (\n\tregistry: PluginRegistry,\n\tnode: DepNode,\n): ((resource: { readonly id: string }) => unknown) => {\n\t// Pre-build a resource-id → upstream-key index for this node so the\n\t// lookups are O(1) instead of scanning dependencies.\n\tconst resourceIdToKey = new Map<string, PluginKey>();\n\tnode.upstreamResources.forEach((resource, i) => {\n\t\tconst upstream = node.upstreamKeys[i];\n\t\tif (upstream !== undefined) resourceIdToKey.set(resource.id, upstream);\n\t});\n\treturn (resource): unknown => {\n\t\tconst key = resourceIdToKey.get(resource.id);\n\t\tif (key === undefined) {\n\t\t\t// Programmer error: the plugin reached outside its declared\n\t\t\t// dependencies. The type system normally rules this out — defending\n\t\t\t// here keeps the runtime honest in the face of cast escapes.\n\t\t\tthrow new Error(\n\t\t\t\t`DependencyReader: resource '${resource.id}' not in this plugin's declared dependencies`,\n\t\t\t);\n\t\t}\n\t\tconst value = readResolvedSync(registry, key);\n\t\tif (value === undefined) {\n\t\t\tthrow new Error(\n\t\t\t\t`DependencyReader: upstream '${key}' has no resolved value yet — ` +\n\t\t\t\t\t'supervisor must mark the entry ready before downstream acquire.',\n\t\t\t);\n\t\t}\n\t\treturn value;\n\t};\n};\n"],"mappings":"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"}

package/dist/substrate/runtime/lifecycle/ready-gate.d.mts

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

package/dist/substrate/runtime/lifecycle/ready-gate.mjs

@@ -0,0 +1,34 @@
+import { Effect } from "effect";
+//#region src/substrate/runtime/lifecycle/ready-gate.ts
+/**
+* Wait for every upstream of `node` to reach `ready`. Returns when
+* they all have; short-circuits on the first upstream failure (the
+* failed deferred propagates `PluginAcquireFailed`).
+*
+* Architecture § Scheduling: "When all upstream keys are `ready`,
+* the node begins `acquiring`."
+*/
+const awaitUpstreams = (registry, node) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({
+		"devstack.plugin.key": node.key,
+		"devstack.plugin.upstreamCount": node.upstreamKeys.length
+	});
+	if (node.upstreamKeys.length === 0) return;
+	yield* Effect.all(node.upstreamKeys.map((key) => registry.awaitReady(key)), {
+		concurrency: "unbounded",
+		discard: true
+	});
+}).pipe(Effect.withSpan("lifecycle.ready-gate.awaitUpstreams"));
+/**
+* Wait for every plugin in `keys` to reach `ready`. Used by the
+* supervisor's "stack is ready" gate after the level-batched parallel
+* acquire completes.
+*/
+const awaitAll = (registry, keys) => Effect.all(keys.map((key) => registry.awaitReady(key)), {
+	concurrency: "unbounded",
+	discard: true
+}).pipe(Effect.withSpan("lifecycle.ready-gate.awaitAll"));
+//#endregion
+export { awaitAll, awaitUpstreams };
+
+//# sourceMappingURL=ready-gate.mjs.map

package/dist/substrate/runtime/lifecycle/ready-gate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ready-gate.mjs","names":[],"sources":["../../../../src/substrate/runtime/lifecycle/ready-gate.ts"],"sourcesContent":["// Ready-gate composition over `PluginRegistry`.\n//\n// Architecture § Plugin lifecycle within a stack § Ready gate:\n//   \"Plugin's acquire procedure returns the resolved value + capability\n//   decls. Substrate writes them to the typed registries. Plugin\n//   transitions to `ready`. Downstream consumers are unblocked.\"\n//\n// This module provides the small `awaitAllReady` / `awaitUpstreams`\n// helpers the supervisor's acquire loop calls. The actual `Deferred`\n// machinery lives on `PluginRegistry`; here we just compose them with\n// span instrumentation and short-circuit on the first upstream\n// failure.\n\nimport { Effect } from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport type { DepNode } from './dep-graph.ts';\nimport type { PluginAcquireFailed, PluginRegistry, UnknownDependency } from './plugin-registry.ts';\n\n/**\n * Wait for every upstream of `node` to reach `ready`. Returns when\n * they all have; short-circuits on the first upstream failure (the\n * failed deferred propagates `PluginAcquireFailed`).\n *\n * Architecture § Scheduling: \"When all upstream keys are `ready`,\n * the node begins `acquiring`.\"\n */\nexport const awaitUpstreams = (\n\tregistry: PluginRegistry,\n\tnode: DepNode,\n): Effect.Effect<void, PluginAcquireFailed | UnknownDependency> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.plugin.key': node.key,\n\t\t\t'devstack.plugin.upstreamCount': node.upstreamKeys.length,\n\t\t});\n\t\tif (node.upstreamKeys.length === 0) return;\n\t\t// Parallelize the awaits — every upstream's ready-gate resolves\n\t\t// once (or fails once); racing them is the right shape.\n\t\tyield* Effect.all(\n\t\t\tnode.upstreamKeys.map((key) => registry.awaitReady(key)),\n\t\t\t{ concurrency: 'unbounded', discard: true },\n\t\t);\n\t}).pipe(Effect.withSpan('lifecycle.ready-gate.awaitUpstreams'));\n\n/**\n * Wait for every plugin in `keys` to reach `ready`. Used by the\n * supervisor's \"stack is ready\" gate after the level-batched parallel\n * acquire completes.\n */\nexport const awaitAll = (\n\tregistry: PluginRegistry,\n\tkeys: ReadonlyArray<PluginKey>,\n): Effect.Effect<void, PluginAcquireFailed | UnknownDependency> =>\n\tEffect.all(\n\t\tkeys.map((key) => registry.awaitReady(key)),\n\t\t{ concurrency: 'unbounded', discard: true },\n\t).pipe(Effect.withSpan('lifecycle.ready-gate.awaitAll'));\n"],"mappings":";;;;;;;;;;AA2BA,MAAa,kBACZ,UACA,SAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB;EACjC,uBAAuB,KAAK;EAC5B,iCAAiC,KAAK,aAAa;EACnD,CAAC;AACF,KAAI,KAAK,aAAa,WAAW,EAAG;AAGpC,QAAO,OAAO,IACb,KAAK,aAAa,KAAK,QAAQ,SAAS,WAAW,IAAI,CAAC,EACxD;EAAE,aAAa;EAAa,SAAS;EAAM,CAC3C;EACA,CAAC,KAAK,OAAO,SAAS,sCAAsC,CAAC;;;;;;AAOhE,MAAa,YACZ,UACA,SAEA,OAAO,IACN,KAAK,KAAK,QAAQ,SAAS,WAAW,IAAI,CAAC,EAC3C;CAAE,aAAa;CAAa,SAAS;CAAM,CAC3C,CAAC,KAAK,OAAO,SAAS,gCAAgC,CAAC"}

package/dist/substrate/runtime/lifecycle/selective-restart.d.mts

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

package/dist/substrate/runtime/lifecycle/selective-restart.mjs

@@ -0,0 +1,43 @@
+import { downstreamClosure, orderByLevel } from "./dep-graph.mjs";
+import { Data, Effect } from "effect";
+//#region src/substrate/runtime/lifecycle/selective-restart.ts
+/** Tagged error: a restart was requested for a key that isn't in the
+*  graph. The supervisor lifts this from `attribute()` callers that
+*  somehow produced a stale key — defensive. */
+var RestartTargetMissing = class extends Data.TaggedError("RestartTargetMissing") {};
+/**
+* Build a restart plan from a set of root invalidation targets. Each
+* root contributes its full downstream closure to the slice.
+*/
+const planRestart = (graph, roots) => Effect.gen(function* () {
+	yield* Effect.annotateCurrentSpan({ "devstack.restart.rootCount": roots.size });
+	for (const root of roots) if (!graph.nodes.has(root)) return yield* Effect.fail(new RestartTargetMissing({ pluginKey: root }));
+	const slice = /* @__PURE__ */ new Set();
+	for (const root of roots) for (const key of downstreamClosure(graph, root)) slice.add(key);
+	return {
+		slice,
+		teardownOrder: orderByLevel(graph, slice, "reverse"),
+		acquireOrder: orderByLevel(graph, slice, "forward")
+	};
+}).pipe(Effect.withSpan("lifecycle.selective-restart.plan"));
+/**
+* Drain plan — for `stack.stop` and graceful shutdown. All keys in
+* dep-graph order, reverse. Architecture § Stack lifecycle:
+*   "shutdown.requested → parallel teardown (max grace, not sum grace)"
+*
+* The "parallel within a level" semantics live in the supervisor's
+* execution loop; this planner just produces the level batches in
+* reverse.
+*/
+const planFullDrain = (graph) => {
+	const slice = new Set(graph.nodes.keys());
+	return {
+		slice,
+		teardownOrder: orderByLevel(graph, slice, "reverse"),
+		acquireOrder: orderByLevel(graph, slice, "forward")
+	};
+};
+//#endregion
+export { planFullDrain, planRestart };
+
+//# sourceMappingURL=selective-restart.mjs.map

package/dist/substrate/runtime/lifecycle/selective-restart.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"selective-restart.mjs","names":[],"sources":["../../../../src/substrate/runtime/lifecycle/selective-restart.ts"],"sourcesContent":["// Selective-restart driver.\n//\n// Architecture § Watch-triggered invalidation:\n//   \"L0 watcher emits a debounced+deduped content-hash event. L3 watch\n//   dispatcher consults plugin watch decls. Matched plugins enter\n//   `selective-restart-pending`. Scheduler runs subset invalidate: evict\n//   shadow-cache entry BEFORE closing scope; run finalizers (parallel\n//   strategy); re-acquire.\"\n//\n// Architecture § Selective restart cascading:\n//   \"Invalidating a producer invalidates downstream consumers along\n//   dep-graph edges (cascade semantics — engine already has this).\"\n//\n// This module is the planner: given a set of root keys to invalidate,\n// compute the downstream slice, order it for teardown and re-acquire.\n// The actual `Scope.close` / `acquire` calls live in `supervisor.ts`\n// so it can fold them into the per-cycle event stream.\n\nimport { Data, Effect } from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport { downstreamClosure, orderByLevel, type ResolvedGraph } from './dep-graph.ts';\n\n/** Tagged error: a restart was requested for a key that isn't in the\n *  graph. The supervisor lifts this from `attribute()` callers that\n *  somehow produced a stale key — defensive. */\nexport class RestartTargetMissing extends Data.TaggedError('RestartTargetMissing')<{\n\treadonly pluginKey: PluginKey;\n}> {}\n\n/** A planned slice of work for selective restart. The supervisor:\n *  1. Tears down `teardownOrder` (reverse-dep, parallel-within-level).\n *  2. Re-acquires `acquireOrder` (forward, level-batched-parallel).\n *\n *  The two arrays cover the same set of keys; the difference is the\n *  iteration direction. */\nexport interface RestartPlan {\n\treadonly slice: ReadonlySet<PluginKey>;\n\treadonly teardownOrder: ReadonlyArray<PluginKey>;\n\treadonly acquireOrder: ReadonlyArray<PluginKey>;\n}\n\n/**\n * Build a restart plan from a set of root invalidation targets. Each\n * root contributes its full downstream closure to the slice.\n */\nexport const planRestart = (\n\tgraph: ResolvedGraph,\n\troots: ReadonlySet<PluginKey>,\n): Effect.Effect<RestartPlan, RestartTargetMissing> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({ 'devstack.restart.rootCount': roots.size });\n\t\tfor (const root of roots) {\n\t\t\tif (!graph.nodes.has(root)) {\n\t\t\t\treturn yield* Effect.fail(new RestartTargetMissing({ pluginKey: root }));\n\t\t\t}\n\t\t}\n\t\tconst slice = new Set<PluginKey>();\n\t\tfor (const root of roots) {\n\t\t\tfor (const key of downstreamClosure(graph, root)) slice.add(key);\n\t\t}\n\t\tconst teardownOrder = orderByLevel(graph, slice, 'reverse');\n\t\tconst acquireOrder = orderByLevel(graph, slice, 'forward');\n\t\treturn { slice, teardownOrder, acquireOrder } satisfies RestartPlan;\n\t}).pipe(Effect.withSpan('lifecycle.selective-restart.plan'));\n\n/**\n * Drain plan — for `stack.stop` and graceful shutdown. All keys in\n * dep-graph order, reverse. Architecture § Stack lifecycle:\n *   \"shutdown.requested → parallel teardown (max grace, not sum grace)\"\n *\n * The \"parallel within a level\" semantics live in the supervisor's\n * execution loop; this planner just produces the level batches in\n * reverse.\n */\nexport const planFullDrain = (graph: ResolvedGraph): RestartPlan => {\n\tconst slice = new Set<PluginKey>(graph.nodes.keys());\n\tconst teardownOrder = orderByLevel(graph, slice, 'reverse');\n\tconst acquireOrder = orderByLevel(graph, slice, 'forward');\n\treturn { slice, teardownOrder, acquireOrder };\n};\n"],"mappings":";;;;;;AA0BA,IAAa,uBAAb,cAA0C,KAAK,YAAY,uBAAuB,CAE/E;;;;;AAkBH,MAAa,eACZ,OACA,UAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB,EAAE,8BAA8B,MAAM,MAAM,CAAC;AAC/E,MAAK,MAAM,QAAQ,MAClB,KAAI,CAAC,MAAM,MAAM,IAAI,KAAK,CACzB,QAAO,OAAO,OAAO,KAAK,IAAI,qBAAqB,EAAE,WAAW,MAAM,CAAC,CAAC;CAG1E,MAAM,wBAAQ,IAAI,KAAgB;AAClC,MAAK,MAAM,QAAQ,MAClB,MAAK,MAAM,OAAO,kBAAkB,OAAO,KAAK,CAAE,OAAM,IAAI,IAAI;AAIjE,QAAO;EAAE;EAAO,eAFM,aAAa,OAAO,OAAO,UAEpB;EAAE,cADV,aAAa,OAAO,OAAO,UACL;EAAE;EAC5C,CAAC,KAAK,OAAO,SAAS,mCAAmC,CAAC;;;;;;;;;;AAW7D,MAAa,iBAAiB,UAAsC;CACnE,MAAM,QAAQ,IAAI,IAAe,MAAM,MAAM,MAAM,CAAC;AAGpD,QAAO;EAAE;EAAO,eAFM,aAAa,OAAO,OAAO,UAEpB;EAAE,cADV,aAAa,OAAO,OAAO,UACL;EAAE"}

package/dist/substrate/runtime/lifecycle/signals.d.mts

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

package/dist/substrate/runtime/lifecycle/signals.mjs

@@ -0,0 +1,64 @@
+import { Effect, Queue } from "effect";
+//#region src/substrate/runtime/lifecycle/signals.ts
+/** Signals the supervisor handles. SIGHUP intentionally omitted —
+*  reconfigure is a command-channel concern, not a signal one. */
+const HANDLED_SIGNALS = ["SIGINT", "SIGTERM"];
+/** Map a signal to the exit code POSIX clients expect — 128 + N. */
+const exitCodeForSignal = (signal) => {
+	switch (signal) {
+		case "SIGINT": return 130;
+		case "SIGTERM": return 143;
+	}
+};
+const scheduleProcessExit = (exitCode) => {
+	setImmediate(() => {
+		process.exit(exitCode);
+	});
+};
+/**
+* Install signal handlers that publish `shutdown.requested` (first
+* signal) and `shutdown.hardKillRequested` before scheduling process
+* exit (second handled signal).
+*
+* Returns an Effect that runs forever in its Scope; the supervisor
+* forks it via `Effect.forkScoped`. Scope close unregisters the
+* listeners — Node's `process` listeners persist past the scope
+* otherwise, leading to "ghost" handlers from prior test boots.
+*/
+const installSignalHandler = (commands, options = {}) => Effect.gen(function* () {
+	const scheduleExit = options.scheduleExit ?? scheduleProcessExit;
+	let shutdownRequested = false;
+	const handlers = [];
+	for (const signal of HANDLED_SIGNALS) {
+		const listener = () => {
+			const exitCode = exitCodeForSignal(signal);
+			if (shutdownRequested) {
+				const offerEffect = Queue.offer(commands, {
+					tag: "shutdown.hardKillRequested",
+					signal,
+					exitCode,
+					at: Date.now()
+				}).pipe(Effect.andThen(Effect.sync(() => scheduleExit(exitCode))));
+				Effect.runFork(offerEffect);
+				return;
+			}
+			shutdownRequested = true;
+			process.exitCode ??= exitCode;
+			const offerEffect = Queue.offer(commands, { tag: "shutdown.requested" });
+			Effect.runFork(offerEffect);
+		};
+		process.on(signal, listener);
+		handlers.push({
+			signal,
+			listener
+		});
+	}
+	yield* Effect.addFinalizer(() => Effect.sync(() => {
+		for (const { signal, listener } of handlers) process.removeListener(signal, listener);
+	}));
+	return yield* Effect.never;
+}).pipe(Effect.withSpan("lifecycle.signals.installSignalHandler"));
+//#endregion
+export { installSignalHandler };
+
+//# sourceMappingURL=signals.mjs.map

package/dist/substrate/runtime/lifecycle/signals.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.mjs","names":[],"sources":["../../../../src/substrate/runtime/lifecycle/signals.ts"],"sourcesContent":["// POSIX signal handling.\n//\n// Architecture § Engine / supervisor split:\n//   \"signals → L0 (one POSIX signal handler at process boot), routed\n//   via the command channel.\"\n//\n// Discipline:\n//   - ONE handler per process. Registering twice is a programmer\n//     error.\n//   - Signals translate to `EngineCommand`s on the typed command stream\n//     (`shutdown.requested` for graceful, `shutdown.hardKillRequested`\n//     for hard).\n//   - Second SIGINT/SIGTERM escalates to abort: the hard-kill command\n//     is offered first, then `process.exit(130)` (or 143 for SIGTERM)\n//     is scheduled.\n//\n// The supervisor wires this fiber once at boot via `Effect.forkScoped`;\n// its scope is the supervisor's outer scope, so the handler unregisters\n// when the supervisor tears down (test environments that boot multiple\n// supervisors must close them before booting the next).\n\nimport { Effect, Queue, Scope } from 'effect';\n\nimport type { EngineCommand, ShutdownSignal } from '../../events.ts';\n\n/** Signals the supervisor handles. SIGHUP intentionally omitted —\n *  reconfigure is a command-channel concern, not a signal one. */\nconst HANDLED_SIGNALS = ['SIGINT', 'SIGTERM'] as const satisfies ReadonlyArray<ShutdownSignal>;\ntype HandledSignal = (typeof HANDLED_SIGNALS)[number];\n\n/** Map a signal to the exit code POSIX clients expect — 128 + N. */\nconst exitCodeForSignal = (signal: HandledSignal): number => {\n\tswitch (signal) {\n\t\tcase 'SIGINT':\n\t\t\treturn 130;\n\t\tcase 'SIGTERM':\n\t\t\treturn 143;\n\t}\n};\n\nexport interface SignalHandlerOptions {\n\treadonly scheduleExit?: (exitCode: number) => void;\n}\n\nconst scheduleProcessExit = (exitCode: number): void => {\n\tsetImmediate(() => {\n\t\tprocess.exit(exitCode);\n\t});\n};\n\n/**\n * Install signal handlers that publish `shutdown.requested` (first\n * signal) and `shutdown.hardKillRequested` before scheduling process\n * exit (second handled signal).\n *\n * Returns an Effect that runs forever in its Scope; the supervisor\n * forks it via `Effect.forkScoped`. Scope close unregisters the\n * listeners — Node's `process` listeners persist past the scope\n * otherwise, leading to \"ghost\" handlers from prior test boots.\n */\nexport const installSignalHandler = (\n\tcommands: Queue.Enqueue<EngineCommand>,\n\toptions: SignalHandlerOptions = {},\n): Effect.Effect<never, never, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst scheduleExit = options.scheduleExit ?? scheduleProcessExit;\n\t\tlet shutdownRequested = false;\n\n\t\tconst handlers: Array<{\n\t\t\treadonly signal: HandledSignal;\n\t\t\treadonly listener: NodeJS.SignalsListener;\n\t\t}> = [];\n\n\t\tfor (const signal of HANDLED_SIGNALS) {\n\t\t\tconst listener: NodeJS.SignalsListener = () => {\n\t\t\t\tconst exitCode = exitCodeForSignal(signal);\n\t\t\t\tif (shutdownRequested) {\n\t\t\t\t\tconst offerEffect = Queue.offer(commands, {\n\t\t\t\t\t\ttag: 'shutdown.hardKillRequested',\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t\texitCode,\n\t\t\t\t\t\tat: Date.now(),\n\t\t\t\t\t} satisfies EngineCommand).pipe(\n\t\t\t\t\t\tEffect.andThen(Effect.sync(() => scheduleExit(exitCode))),\n\t\t\t\t\t);\n\t\t\t\t\tEffect.runFork(offerEffect);\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tshutdownRequested = true;\n\t\t\t\tprocess.exitCode ??= exitCode;\n\t\t\t\t// Publish `shutdown.requested` — same shape regardless of\n\t\t\t\t// which signal fired. The supervisor decides drain vs abort\n\t\t\t\t// on its own loop.\n\t\t\t\tconst offerEffect = Queue.offer(commands, {\n\t\t\t\t\ttag: 'shutdown.requested',\n\t\t\t\t} satisfies EngineCommand);\n\t\t\t\t// We're inside a Node listener; bridge into Effect via the\n\t\t\t\t// process's default runtime. `runFork` returns a fiber but we\n\t\t\t\t// don't track it — the queue is bounded by the supervisor's\n\t\t\t\t// lifetime.\n\t\t\t\tEffect.runFork(offerEffect);\n\t\t\t};\n\t\t\tprocess.on(signal, listener);\n\t\t\thandlers.push({ signal, listener });\n\t\t}\n\n\t\tyield* Effect.addFinalizer(() =>\n\t\t\tEffect.sync(() => {\n\t\t\t\tfor (const { signal, listener } of handlers) {\n\t\t\t\t\tprocess.removeListener(signal, listener);\n\t\t\t\t}\n\t\t\t}),\n\t\t);\n\n\t\t// Park forever; the listeners themselves run synchronously in\n\t\t// Node's event loop, not in this fiber.\n\t\treturn yield* Effect.never;\n\t}).pipe(Effect.withSpan('lifecycle.signals.installSignalHandler'));\n\n/** Re-export the handled-signal list so tests / docs can enumerate. */\nexport const handledSignals: ReadonlyArray<HandledSignal> = HANDLED_SIGNALS;\n"],"mappings":";;;;AA2BA,MAAM,kBAAkB,CAAC,UAAU,UAAU;;AAI7C,MAAM,qBAAqB,WAAkC;AAC5D,SAAQ,QAAR;EACC,KAAK,SACJ,QAAO;EACR,KAAK,UACJ,QAAO;;;AAQV,MAAM,uBAAuB,aAA2B;AACvD,oBAAmB;AAClB,UAAQ,KAAK,SAAS;GACrB;;;;;;;;;;;;AAaH,MAAa,wBACZ,UACA,UAAgC,EAAE,KAElC,OAAO,IAAI,aAAa;CACvB,MAAM,eAAe,QAAQ,gBAAgB;CAC7C,IAAI,oBAAoB;CAExB,MAAM,WAGD,EAAE;AAEP,MAAK,MAAM,UAAU,iBAAiB;EACrC,MAAM,iBAAyC;GAC9C,MAAM,WAAW,kBAAkB,OAAO;AAC1C,OAAI,mBAAmB;IACtB,MAAM,cAAc,MAAM,MAAM,UAAU;KACzC,KAAK;KACL;KACA;KACA,IAAI,KAAK,KAAK;KACd,CAAyB,CAAC,KAC1B,OAAO,QAAQ,OAAO,WAAW,aAAa,SAAS,CAAC,CAAC,CACzD;AACD,WAAO,QAAQ,YAAY;AAC3B;;AAED,uBAAoB;AACpB,WAAQ,aAAa;GAIrB,MAAM,cAAc,MAAM,MAAM,UAAU,EACzC,KAAK,sBACL,CAAyB;AAK1B,UAAO,QAAQ,YAAY;;AAE5B,UAAQ,GAAG,QAAQ,SAAS;AAC5B,WAAS,KAAK;GAAE;GAAQ;GAAU,CAAC;;AAGpC,QAAO,OAAO,mBACb,OAAO,WAAW;AACjB,OAAK,MAAM,EAAE,QAAQ,cAAc,SAClC,SAAQ,eAAe,QAAQ,SAAS;GAExC,CACF;AAID,QAAO,OAAO,OAAO;EACpB,CAAC,KAAK,OAAO,SAAS,yCAAyC,CAAC"}

package/dist/substrate/runtime/lifecycle/state-machine.d.mts

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

package/dist/substrate/runtime/lifecycle/state-machine.mjs

@@ -0,0 +1,38 @@
+import { Data, Effect } from "effect";
+//#region src/substrate/runtime/lifecycle/state-machine.ts
+/** Off-table transition — programmer error. Surfaced as a defect via
+*  `Effect.die` so the renderer / cause walker sees the impossible
+*  transition rather than silently corrupting the projection. */
+var InvalidLifecycleTransition = class extends Data.TaggedError("InvalidLifecycleTransition") {};
+/** Canonical transition table — mirrors the type-level
+*  `LifecycleTransition` from `substrate/lifecycle.ts` exactly. Adding
+*  a transition requires updating BOTH (the type-level union AND this
+*  table). */
+const ALLOWED = new Map([
+	["pending", new Set(["acquiring", "failed"])],
+	["acquiring", new Set(["ready", "failed"])],
+	["ready", new Set([
+		"stopping",
+		"failed",
+		"done"
+	])],
+	["stopping", new Set(["stopped", "failed"])],
+	["failed", new Set(["pending"])],
+	["stopped", new Set(["pending"])],
+	["done", new Set(["pending", "failed"])]
+]);
+/** Returns true iff `from → to` is on the allowed-transition table. */
+const isAllowedTransition = (from, to) => ALLOWED.get(from)?.has(to) ?? false;
+/** Effect-flavored transition assertion. Returns the new status on
+*  success; dies with `InvalidLifecycleTransition` otherwise. */
+const assertTransition = (from, to) => isAllowedTransition(from, to) ? Effect.succeed(to) : Effect.die(new InvalidLifecycleTransition({
+	from,
+	to
+}));
+/** Statuses that count toward "stack is ready" — every plugin must be
+*  in one of these for the stack to surface `running`. */
+const isReadyOrTerminal = (status) => status === "ready" || status === "done";
+//#endregion
+export { assertTransition, isReadyOrTerminal };
+
+//# sourceMappingURL=state-machine.mjs.map

package/dist/substrate/runtime/lifecycle/state-machine.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.mjs","names":[],"sources":["../../../../src/substrate/runtime/lifecycle/state-machine.ts"],"sourcesContent":["// Lifecycle state-machine — runtime guard over `LifecycleTransition`.\n//\n// Architecture § Lifecycle state. The transition table is declared in\n// `substrate/lifecycle.ts`; this file asserts moves against it at runtime\n// so an off-table transition lands as a typed Defect (programmer-error\n// class), not a corrupt projection.\n//\n// The state machine is per-plugin. Callers (the supervisor) hold a\n// `Ref` of `LifecycleStatus` and route every change through\n// `transition`, which:\n//   - validates the move,\n//   - emits the `lifecycle.statusChanged` typed event,\n//   - returns the new status.\n\nimport { Data, Effect } from 'effect';\n\nimport type { LifecycleStatus, LifecycleTransition } from '../../lifecycle.ts';\n\n/** Off-table transition — programmer error. Surfaced as a defect via\n *  `Effect.die` so the renderer / cause walker sees the impossible\n *  transition rather than silently corrupting the projection. */\nexport class InvalidLifecycleTransition extends Data.TaggedError('InvalidLifecycleTransition')<{\n\treadonly from: LifecycleStatus;\n\treadonly to: LifecycleStatus;\n}> {}\n\n/** Canonical transition table — mirrors the type-level\n *  `LifecycleTransition` from `substrate/lifecycle.ts` exactly. Adding\n *  a transition requires updating BOTH (the type-level union AND this\n *  table). */\nconst ALLOWED: ReadonlyMap<LifecycleStatus, ReadonlySet<LifecycleStatus>> = new Map([\n\t['pending', new Set<LifecycleStatus>(['acquiring', 'failed'])],\n\t['acquiring', new Set<LifecycleStatus>(['ready', 'failed'])],\n\t['ready', new Set<LifecycleStatus>(['stopping', 'failed', 'done'])],\n\t['stopping', new Set<LifecycleStatus>(['stopped', 'failed'])],\n\t['failed', new Set<LifecycleStatus>(['pending'])],\n\t['stopped', new Set<LifecycleStatus>(['pending'])],\n\t['done', new Set<LifecycleStatus>(['pending', 'failed'])],\n] as const);\n\n/** Predicate that the type-table and the runtime table agree. The\n *  compiler checks the type-level shape; this conditional verifies the\n *  runtime table covers exactly the same `from` set. */\ntype _AllFroms = LifecycleTransition['from'];\ntype _RuntimeFroms = 'pending' | 'acquiring' | 'ready' | 'stopping' | 'failed' | 'stopped' | 'done';\ntype _TableShape = _AllFroms extends _RuntimeFroms\n\t? _RuntimeFroms extends _AllFroms | 'done'\n\t\t? true\n\t\t: false\n\t: false;\n// Force the check by exporting the assertion.\nexport type __LifecycleTableShape = _TableShape extends true ? true : never;\n\n/** Returns true iff `from → to` is on the allowed-transition table. */\nexport const isAllowedTransition = (from: LifecycleStatus, to: LifecycleStatus): boolean =>\n\tALLOWED.get(from)?.has(to) ?? false;\n\n/** Effect-flavored transition assertion. Returns the new status on\n *  success; dies with `InvalidLifecycleTransition` otherwise. */\nexport const assertTransition = (\n\tfrom: LifecycleStatus,\n\tto: LifecycleStatus,\n): Effect.Effect<LifecycleStatus> =>\n\tisAllowedTransition(from, to)\n\t\t? Effect.succeed(to)\n\t\t: Effect.die(new InvalidLifecycleTransition({ from, to }));\n\n/** Completed task status. It counts as ready, restart can return it to pending,\n *  and post-acquire failures can still mark it failed. */\nexport const isTerminal = (status: LifecycleStatus): boolean => status === 'done';\n\n/** Statuses that count toward \"stack is ready\" — every plugin must be\n *  in one of these for the stack to surface `running`. */\nexport const isReadyOrTerminal = (status: LifecycleStatus): boolean =>\n\tstatus === 'ready' || status === 'done';\n"],"mappings":";;;;;AAqBA,IAAa,6BAAb,cAAgD,KAAK,YAAY,6BAA6B,CAG3F;;;;;AAMH,MAAM,UAAsE,IAAI,IAAI;CACnF,CAAC,WAAW,IAAI,IAAqB,CAAC,aAAa,SAAS,CAAC,CAAC;CAC9D,CAAC,aAAa,IAAI,IAAqB,CAAC,SAAS,SAAS,CAAC,CAAC;CAC5D,CAAC,SAAS,IAAI,IAAqB;EAAC;EAAY;EAAU;EAAO,CAAC,CAAC;CACnE,CAAC,YAAY,IAAI,IAAqB,CAAC,WAAW,SAAS,CAAC,CAAC;CAC7D,CAAC,UAAU,IAAI,IAAqB,CAAC,UAAU,CAAC,CAAC;CACjD,CAAC,WAAW,IAAI,IAAqB,CAAC,UAAU,CAAC,CAAC;CAClD,CAAC,QAAQ,IAAI,IAAqB,CAAC,WAAW,SAAS,CAAC,CAAC;CACzD,CAAU;;AAgBX,MAAa,uBAAuB,MAAuB,OAC1D,QAAQ,IAAI,KAAK,EAAE,IAAI,GAAG,IAAI;;;AAI/B,MAAa,oBACZ,MACA,OAEA,oBAAoB,MAAM,GAAG,GAC1B,OAAO,QAAQ,GAAG,GAClB,OAAO,IAAI,IAAI,2BAA2B;CAAE;CAAM;CAAI,CAAC,CAAC;;;AAQ5D,MAAa,qBAAqB,WACjC,WAAW,WAAW,WAAW"}

package/dist/substrate/runtime/lifecycle/watch-attribution.d.mts

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

package/dist/substrate/runtime/lifecycle/watch-attribution.mjs

@@ -0,0 +1,27 @@
+import "effect";
+//#region src/substrate/runtime/lifecycle/watch-attribution.ts
+/** Build the watch index from a resolved dep-graph's nodes. */
+const buildWatchIndex = (nodes) => {
+	const out = [];
+	for (const [key, node] of nodes) {
+		const watch = node.member.watch;
+		if (watch === void 0 || watch.paths.length === 0) continue;
+		out.push({
+			pluginKey: key,
+			paths: watch.paths,
+			cascade: watch.cascade ?? true
+		});
+	}
+	return out;
+};
+/**
+* Default fallback matcher — exact-prefix only. Provided so unit
+* tests / single-stack boots without a real minimatch dependency
+* still function. The L0 thick watcher's minimatch is the production
+* matcher.
+*/
+const exactPrefixMatch = (pattern, path) => path === pattern || path.startsWith(pattern.replace(/\*+$/, ""));
+//#endregion
+export { buildWatchIndex, exactPrefixMatch };
+
+//# sourceMappingURL=watch-attribution.mjs.map

package/dist/substrate/runtime/lifecycle/watch-attribution.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-attribution.mjs","names":[],"sources":["../../../../src/substrate/runtime/lifecycle/watch-attribution.ts"],"sourcesContent":["// Watch-path → owning plugin attribution.\n//\n// Architecture § L3 Watch dispatcher: \"collects all plugin `watch`\n// declarations, receives watcher events from L0 (which already\n// debounced + dedup'd), triggers selective restart through the\n// scheduler's invalidate-with-cascade.\"\n//\n// L0 owns the file watcher (debounce + content-hash dedup). The\n// supervisor's role at watch time is just: given a fired path, which\n// plugin row(s) should be invalidated? This module builds and queries\n// that index. Selective-restart is the supervisor's concern; watch\n// attribution stays pure.\n\nimport { Effect } from 'effect';\n\nimport type { PluginKey } from '../../brand.ts';\nimport type { DepNode } from './dep-graph.ts';\n\n/** Per-plugin watch entry — a copy of the plugin's declared `watch`\n *  decl with the owning key attached. */\nexport interface WatchEntry {\n\treadonly pluginKey: PluginKey;\n\treadonly paths: ReadonlyArray<string>;\n\t/** Whether downstream consumers should cascade-invalidate when this\n\t *  fires. Defaults to true (architecture § WatchDecl). */\n\treadonly cascade: boolean;\n}\n\n/** Build the watch index from a resolved dep-graph's nodes. */\nexport const buildWatchIndex = (\n\tnodes: ReadonlyMap<PluginKey, DepNode>,\n): ReadonlyArray<WatchEntry> => {\n\tconst out: WatchEntry[] = [];\n\tfor (const [key, node] of nodes) {\n\t\tconst watch = node.member.watch;\n\t\tif (watch === undefined || watch.paths.length === 0) continue;\n\t\tout.push({\n\t\t\tpluginKey: key,\n\t\t\tpaths: watch.paths,\n\t\t\tcascade: watch.cascade ?? true,\n\t\t});\n\t}\n\treturn out;\n};\n\n/**\n * Given the firing `firedPath` (already debounced + content-hash dedup'd\n * by L0), return the plugin keys whose declared paths match.\n *\n * Matching is glob-aware via minimatch semantics — the substrate-level\n * attribution here delegates to a supplied `match` predicate to keep\n * this module dependency-free. The supervisor wires the matcher in.\n */\nexport const attribute = (\n\tindex: ReadonlyArray<WatchEntry>,\n\tfiredPath: string,\n\tmatch: (pattern: string, path: string) => boolean,\n): ReadonlySet<PluginKey> => {\n\tconst out = new Set<PluginKey>();\n\tfor (const entry of index) {\n\t\tfor (const pattern of entry.paths) {\n\t\t\tif (match(pattern, firedPath)) {\n\t\t\t\tout.add(entry.pluginKey);\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\treturn out;\n};\n\n/**\n * Effect-flavored wrapper — span-instrumented for tracing. Wraps the\n * pure `attribute` so the supervisor's invalidate-with-cascade trace\n * shows the watch fan-out alongside the dep-graph restart slice.\n */\nexport const attributeFire = (\n\tindex: ReadonlyArray<WatchEntry>,\n\tfiredPath: string,\n\tmatch: (pattern: string, path: string) => boolean,\n): Effect.Effect<ReadonlySet<PluginKey>> =>\n\tEffect.gen(function* () {\n\t\tconst keys = attribute(index, firedPath, match);\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'devstack.watch.firedPath': firedPath,\n\t\t\t'devstack.watch.matchedCount': keys.size,\n\t\t});\n\t\treturn keys;\n\t}).pipe(Effect.withSpan('lifecycle.watch.attribute'));\n\n/**\n * Default fallback matcher — exact-prefix only. Provided so unit\n * tests / single-stack boots without a real minimatch dependency\n * still function. The L0 thick watcher's minimatch is the production\n * matcher.\n */\nexport const exactPrefixMatch = (pattern: string, path: string): boolean =>\n\tpath === pattern || path.startsWith(pattern.replace(/\\*+$/, ''));\n"],"mappings":";;;AA6BA,MAAa,mBACZ,UAC+B;CAC/B,MAAM,MAAoB,EAAE;AAC5B,MAAK,MAAM,CAAC,KAAK,SAAS,OAAO;EAChC,MAAM,QAAQ,KAAK,OAAO;AAC1B,MAAI,UAAU,KAAA,KAAa,MAAM,MAAM,WAAW,EAAG;AACrD,MAAI,KAAK;GACR,WAAW;GACX,OAAO,MAAM;GACb,SAAS,MAAM,WAAW;GAC1B,CAAC;;AAEH,QAAO;;;;;;;;AAqDR,MAAa,oBAAoB,SAAiB,SACjD,SAAS,WAAW,KAAK,WAAW,QAAQ,QAAQ,QAAQ,GAAG,CAAC"}

package/dist/substrate/runtime/managed-container.d.mts

@@ -0,0 +1,30 @@
+import { ContainerLabelTuple } from "../../contracts/snapshotable.mjs";
+import { ContainerHandle, ContainerRuntime, ContainerRuntimeError, EnsureContainerSpec } from "../../contracts/container-runtime.mjs";
+import { Effect, Scope } from "effect";
+
+//#region src/substrate/runtime/managed-container.d.ts
+declare namespace managed_container_d_exports {
+  export { EnsureManagedContainerOptions, ManagedContainerIdentity, ManagedContainerLabelOptions, ensureManagedContainer, managedContainerLabels };
+}
+interface ManagedContainerIdentity {
+  readonly app: string;
+  readonly stack: string;
+}
+interface ManagedContainerLabelOptions {
+  readonly identity: ManagedContainerIdentity;
+  readonly plugin: string;
+  readonly role: string;
+}
+declare const managedContainerLabels: (options: ManagedContainerLabelOptions) => ContainerLabelTuple;
+type ManagedContainerLabelInput = {
+  readonly labels: ContainerLabelTuple;
+} | ManagedContainerLabelOptions;
+type EnsureManagedContainerOptions<E> = ManagedContainerLabelInput & {
+  readonly runtime: ContainerRuntime;
+  readonly spec: Omit<EnsureContainerSpec, 'labels'>;
+  readonly mapError: (cause: ContainerRuntimeError) => E;
+};
+declare const ensureManagedContainer: <E>(options: EnsureManagedContainerOptions<E>) => Effect.Effect<ContainerHandle, E, Scope.Scope>;
+//#endregion
+export { managed_container_d_exports };
+//# sourceMappingURL=managed-container.d.mts.map

package/dist/substrate/runtime/managed-container.mjs

@@ -0,0 +1,32 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.mjs";
+import { SpanAttr } from "./observability/spans.mjs";
+import { Effect } from "effect";
+//#region src/substrate/runtime/managed-container.ts
+var managed_container_exports = /* @__PURE__ */ __exportAll({
+	ensureManagedContainer: () => ensureManagedContainer,
+	managedContainerLabels: () => managedContainerLabels
+});
+const managedContainerLabels = (options) => ({
+	app: options.identity.app,
+	stack: options.identity.stack,
+	plugin: options.plugin,
+	role: options.role
+});
+const labelsFrom = (input) => "labels" in input ? input.labels : managedContainerLabels(input);
+const ensureManagedContainer = (options) => {
+	const labels = labelsFrom(options);
+	return options.runtime.ensureContainer({
+		...options.spec,
+		labels
+	}).pipe(Effect.mapError(options.mapError), Effect.withSpan("substrate.managedContainer.ensure", { attributes: {
+		[SpanAttr.app]: labels.app,
+		[SpanAttr.stack]: labels.stack,
+		[SpanAttr.plugin]: labels.plugin,
+		[SpanAttr.containerRole]: labels.role,
+		[SpanAttr.containerName]: options.spec.name
+	} }));
+};
+//#endregion
+export { ensureManagedContainer, managed_container_exports };
+
+//# sourceMappingURL=managed-container.mjs.map

package/dist/substrate/runtime/managed-container.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-container.mjs","names":[],"sources":["../../../src/substrate/runtime/managed-container.ts"],"sourcesContent":["import { Effect, type Scope } from 'effect';\n\nimport type {\n\tContainerHandle,\n\tContainerRuntime,\n\tContainerRuntimeError,\n\tEnsureContainerSpec,\n} from '../../contracts/container-runtime.ts';\nimport type { ContainerLabelTuple } from '../../contracts/snapshotable.ts';\nimport { SpanAttr } from './observability/spans.ts';\n\nexport interface ManagedContainerIdentity {\n\treadonly app: string;\n\treadonly stack: string;\n}\n\nexport interface ManagedContainerLabelOptions {\n\treadonly identity: ManagedContainerIdentity;\n\treadonly plugin: string;\n\treadonly role: string;\n}\n\nexport const managedContainerLabels = (\n\toptions: ManagedContainerLabelOptions,\n): ContainerLabelTuple => ({\n\tapp: options.identity.app,\n\tstack: options.identity.stack,\n\tplugin: options.plugin,\n\trole: options.role,\n});\n\ntype ManagedContainerLabelInput =\n\t| { readonly labels: ContainerLabelTuple }\n\t| ManagedContainerLabelOptions;\n\nexport type EnsureManagedContainerOptions<E> = ManagedContainerLabelInput & {\n\treadonly runtime: ContainerRuntime;\n\treadonly spec: Omit<EnsureContainerSpec, 'labels'>;\n\treadonly mapError: (cause: ContainerRuntimeError) => E;\n};\n\nconst labelsFrom = (input: ManagedContainerLabelInput): ContainerLabelTuple =>\n\t'labels' in input ? input.labels : managedContainerLabels(input);\n\nexport const ensureManagedContainer = <E>(\n\toptions: EnsureManagedContainerOptions<E>,\n): Effect.Effect<ContainerHandle, E, Scope.Scope> => {\n\tconst labels = labelsFrom(options);\n\treturn options.runtime\n\t\t.ensureContainer({\n\t\t\t...options.spec,\n\t\t\tlabels,\n\t\t})\n\t\t.pipe(\n\t\t\tEffect.mapError(options.mapError),\n\t\t\tEffect.withSpan('substrate.managedContainer.ensure', {\n\t\t\t\tattributes: {\n\t\t\t\t\t[SpanAttr.app]: labels.app,\n\t\t\t\t\t[SpanAttr.stack]: labels.stack,\n\t\t\t\t\t[SpanAttr.plugin]: labels.plugin,\n\t\t\t\t\t[SpanAttr.containerRole]: labels.role,\n\t\t\t\t\t[SpanAttr.containerName]: options.spec.name,\n\t\t\t\t},\n\t\t\t}),\n\t\t);\n};\n"],"mappings":";;;;;;;;AAsBA,MAAa,0BACZ,aAC0B;CAC1B,KAAK,QAAQ,SAAS;CACtB,OAAO,QAAQ,SAAS;CACxB,QAAQ,QAAQ;CAChB,MAAM,QAAQ;CACd;AAYD,MAAM,cAAc,UACnB,YAAY,QAAQ,MAAM,SAAS,uBAAuB,MAAM;AAEjE,MAAa,0BACZ,YACoD;CACpD,MAAM,SAAS,WAAW,QAAQ;AAClC,QAAO,QAAQ,QACb,gBAAgB;EAChB,GAAG,QAAQ;EACX;EACA,CAAC,CACD,KACA,OAAO,SAAS,QAAQ,SAAS,EACjC,OAAO,SAAS,qCAAqC,EACpD,YAAY;GACV,SAAS,MAAM,OAAO;GACtB,SAAS,QAAQ,OAAO;GACxB,SAAS,SAAS,OAAO;GACzB,SAAS,gBAAgB,OAAO;GAChC,SAAS,gBAAgB,QAAQ,KAAK;EACvC,EACD,CAAC,CACF"}