@mysten-incubation/devstack 0.0.1 → 0.1.0

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

@@ -1 +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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"}
+{"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\t// Authoritatively reset the status to `pending`. The\n\t\t\t\t// transition table only admits `→ pending` from terminal\n\t\t\t\t// states (`failed` / `stopped` / `done`), but a selective\n\t\t\t\t// restart can reset a node that is still `acquiring` or\n\t\t\t\t// `pending` (its scope close interrupted an in-flight\n\t\t\t\t// acquire). Routing that through `transition` would die on\n\t\t\t\t// the off-table move — a defect the supervisor's command\n\t\t\t\t// loop can't catch — so we set the Ref directly and emit\n\t\t\t\t// the `statusChanged` event ourselves to keep the\n\t\t\t\t// projection's restart blip and the \"every status change\n\t\t\t\t// flows through `onTransition`\" contract intact. `acquire`\n\t\t\t\t// then performs a clean `pending → acquiring` for every\n\t\t\t\t// prior node state.\n\t\t\t\tconst from = yield* Ref.get(entry.statusRef);\n\t\t\t\tyield* Ref.set(entry.statusRef, 'pending');\n\t\t\t\tif (from !== 'pending') yield* onTransition(key, from, 'pending');\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 DependencyReaderViolation({\n\t\t\t\tkind: 'undeclared-dependency',\n\t\t\t\ttarget: resource.id,\n\t\t\t});\n\t\t}\n\t\tconst value = readResolvedSync(registry, key);\n\t\tif (value === undefined) {\n\t\t\tthrow new DependencyReaderViolation({\n\t\t\t\tkind: 'unresolved-upstream',\n\t\t\t\ttarget: key,\n\t\t\t});\n\t\t}\n\t\treturn value;\n\t};\n};\n\n/** Tagged defect surfaced when a plugin's `start` callback reads a\n *  dependency outside its declared `dependsOn` set, or an upstream\n *  that hasn't been marked ready yet. Throws synchronously inside the\n *  dependency-reader closure; the Effect runtime captures it as a\n *  defect the cascade-formatter projects via `_tag`. The `kind`\n *  discriminator and `target` carry the offending name; consumers\n *  read both. */\nexport class DependencyReaderViolation extends Data.TaggedError('DependencyReaderViolation')<{\n\treadonly kind: 'undeclared-dependency' | 'unresolved-upstream';\n\treadonly target: string;\n}> {}\n"],"mappings":"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"}

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

@@ -38,6 +38,6 @@ const planFullDrain = (graph) => {
 	};
 };
 //#endregion
-export { planFullDrain, planRestart };
+export { RestartTargetMissing, planFullDrain, planRestart };
 
 //# sourceMappingURL=selective-restart.mjs.map

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

@@ -27,25 +27,25 @@ const scheduleProcessExit = (exitCode) => {
 */
 const installSignalHandler = (commands, options = {}) => Effect.gen(function* () {
 	const scheduleExit = options.scheduleExit ?? scheduleProcessExit;
+	const supervisorContext = yield* Effect.context();
+	const runForkInherited = Effect.runForkWith(supervisorContext);
 	let shutdownRequested = false;
 	const handlers = [];
 	for (const signal of HANDLED_SIGNALS) {
 		const listener = () => {
 			const exitCode = exitCodeForSignal(signal);
 			if (shutdownRequested) {
-				const offerEffect = Queue.offer(commands, {
+				runForkInherited(Queue.offer(commands, {
 					tag: "shutdown.hardKillRequested",
 					signal,
 					exitCode,
 					at: Date.now()
-				}).pipe(Effect.andThen(Effect.sync(() => scheduleExit(exitCode))));
-				Effect.runFork(offerEffect);
+				}).pipe(Effect.andThen(Effect.sync(() => scheduleExit(exitCode)))));
 				return;
 			}
 			shutdownRequested = true;
 			process.exitCode ??= exitCode;
-			const offerEffect = Queue.offer(commands, { tag: "shutdown.requested" });
-			Effect.runFork(offerEffect);
+			runForkInherited(Queue.offer(commands, { tag: "shutdown.requested" }));
 		};
 		process.on(signal, listener);
 		handlers.push({

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

@@ -1 +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"}
+{"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\t// Capture the surrounding fiber's Context so the signal-listener\n\t\t// fork inherits the supervisor's logger Layer, fiber-refs, and\n\t\t// span context. Bare `Effect.runFork` evaluates against an empty\n\t\t// context — warnings/spans from the offered command would\n\t\t// otherwise bypass redaction rules and supervisor instrumentation.\n\t\tconst supervisorContext = yield* Effect.context<never>();\n\t\tconst runForkInherited = Effect.runForkWith(supervisorContext);\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\trunForkInherited(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// captured supervisor Context so the offered command\n\t\t\t\t// inherits logger/fiber-refs/spans. `runFork` returns a\n\t\t\t\t// fiber but we don't track it — the queue is bounded by\n\t\t\t\t// the supervisor's lifetime.\n\t\t\t\trunForkInherited(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;CAM7C,MAAM,oBAAoB,OAAO,OAAO,SAAgB;CACxD,MAAM,mBAAmB,OAAO,YAAY,kBAAkB;CAC9D,IAAI,oBAAoB;CAExB,MAAM,WAGD,EAAE;AAEP,MAAK,MAAM,UAAU,iBAAiB;EACrC,MAAM,iBAAyC;GAC9C,MAAM,WAAW,kBAAkB,OAAO;AAC1C,OAAI,mBAAmB;AAStB,qBARoB,MAAM,MAAM,UAAU;KACzC,KAAK;KACL;KACA;KACA,IAAI,KAAK,KAAK;KACd,CAAyB,CAAC,KAC1B,OAAO,QAAQ,OAAO,WAAW,aAAa,SAAS,CAAC,CAAC,CAE9B,CAAC;AAC7B;;AAED,uBAAoB;AACpB,WAAQ,aAAa;AAYrB,oBARoB,MAAM,MAAM,UAAU,EACzC,KAAK,sBACL,CAM2B,CAAC;;AAE9B,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.mjs

@@ -33,6 +33,6 @@ const assertTransition = (from, to) => isAllowedTransition(from, to) ? Effect.su
 *  in one of these for the stack to surface `running`. */
 const isReadyOrTerminal = (status) => status === "ready" || status === "done";
 //#endregion
-export { assertTransition, isReadyOrTerminal };
+export { InvalidLifecycleTransition, assertTransition, isAllowedTransition, isReadyOrTerminal };
 
 //# sourceMappingURL=state-machine.mjs.map

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

@@ -4,8 +4,26 @@ 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 };
+  export { EnsureManagedContainerOptions, ManagedContainerIdentity, ManagedContainerLabelOptions, PER_APP_SHARED_STACK, ensureManagedContainer, managedContainerLabels };
 }
+/** Sentinel `stack` value for containers / volumes / networks that are
+ *  shared across a single app's stacks but isolated PER APP — the
+ *  resource lives at app-scope, not stack-scope.
+ *
+ *  Current producer: the per-app sui chain-build container
+ *  (`plugins/sui/chain-build-container.ts`) reuses one container
+ *  across multiple stacks of the same app to keep the bind-mounted
+ *  Move dep cache warm.
+ *
+ *  Lifecycle-prune + the prune CLI compare against this sentinel to
+ *  decide whether a resource group is shared (pinned while any
+ *  sibling stack under the same app is live) vs per-stack (pruned
+ *  with its stack).
+ *
+ *  The vocabulary lives here alongside the `{ app, stack, plugin,
+ *  role }` label tuple — managed-container.ts is the canonical
+ *  owner. */
+declare const PER_APP_SHARED_STACK: "_per-app_";
 interface ManagedContainerIdentity {
   readonly app: string;
   readonly stack: string;

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

@@ -3,9 +3,28 @@ import { SpanAttr } from "./observability/spans.mjs";
 import { Effect } from "effect";
 //#region src/substrate/runtime/managed-container.ts
 var managed_container_exports = /* @__PURE__ */ __exportAll({
+	PER_APP_SHARED_STACK: () => PER_APP_SHARED_STACK,
 	ensureManagedContainer: () => ensureManagedContainer,
 	managedContainerLabels: () => managedContainerLabels
 });
+/** Sentinel `stack` value for containers / volumes / networks that are
+*  shared across a single app's stacks but isolated PER APP — the
+*  resource lives at app-scope, not stack-scope.
+*
+*  Current producer: the per-app sui chain-build container
+*  (`plugins/sui/chain-build-container.ts`) reuses one container
+*  across multiple stacks of the same app to keep the bind-mounted
+*  Move dep cache warm.
+*
+*  Lifecycle-prune + the prune CLI compare against this sentinel to
+*  decide whether a resource group is shared (pinned while any
+*  sibling stack under the same app is live) vs per-stack (pruned
+*  with its stack).
+*
+*  The vocabulary lives here alongside the `{ app, stack, plugin,
+*  role }` label tuple — managed-container.ts is the canonical
+*  owner. */
+const PER_APP_SHARED_STACK = "_per-app_";
 const managedContainerLabels = (options) => ({
 	app: options.identity.app,
 	stack: options.identity.stack,
@@ -27,6 +46,6 @@ const ensureManagedContainer = (options) => {
 	} }));
 };
 //#endregion
-export { ensureManagedContainer, managed_container_exports };
+export { PER_APP_SHARED_STACK, ensureManagedContainer, managed_container_exports };
 
 //# sourceMappingURL=managed-container.mjs.map

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

@@ -1 +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"}
+{"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\n/** Sentinel `stack` value for containers / volumes / networks that are\n *  shared across a single app's stacks but isolated PER APP — the\n *  resource lives at app-scope, not stack-scope.\n *\n *  Current producer: the per-app sui chain-build container\n *  (`plugins/sui/chain-build-container.ts`) reuses one container\n *  across multiple stacks of the same app to keep the bind-mounted\n *  Move dep cache warm.\n *\n *  Lifecycle-prune + the prune CLI compare against this sentinel to\n *  decide whether a resource group is shared (pinned while any\n *  sibling stack under the same app is live) vs per-stack (pruned\n *  with its stack).\n *\n *  The vocabulary lives here alongside the `{ app, stack, plugin,\n *  role }` label tuple — managed-container.ts is the canonical\n *  owner. */\nexport const PER_APP_SHARED_STACK = '_per-app_' as const;\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":";;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,MAAa,uBAAuB;AAapC,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"}

package/dist/substrate/runtime/manifest/index.mjs

@@ -0,0 +1,3 @@
+import "../../manifest.mjs";
+import "./manifest.mjs";
+export {};

package/dist/substrate/runtime/manifest/manifest.mjs

@@ -1,4 +1,5 @@
 import { atomicWriteFile } from "../atomic-write.mjs";
+import "../runtime-decode.mjs";
 import "../../manifest.mjs";
 import { Data, Effect } from "effect";
 /** One error class for every manifest IO failure. */
@@ -16,6 +17,15 @@ const buildEnvelope = (input) => Effect.gen(function* () {
 	const services = {};
 	const endpoints = {};
 	const extras = { ...input.extras };
+	const addEndpoint = (ep) => Effect.gen(function* () {
+		const ek = ep.endpointKey;
+		if (ek in endpoints) return yield* Effect.fail(new ManifestError({
+			reason: "duplicate-contribution",
+			path: "(in-memory envelope)",
+			detail: `endpointKey ${ek} contributed twice`
+		}));
+		endpoints[ek] = ep;
+	});
 	for (const contribution of input.contributions) {
 		const key = contribution.pluginKey;
 		if (key in services) return yield* Effect.fail(new ManifestError({
@@ -32,22 +42,16 @@ const buildEnvelope = (input) => Effect.gen(function* () {
 			}));
 			extras[extraKey] = extraValue;
 		}
-		for (const ep of contribution.endpoints) {
-			const ek = ep.endpointKey;
-			if (ek in endpoints) return yield* Effect.fail(new ManifestError({
-				reason: "duplicate-contribution",
-				path: "(in-memory envelope)",
-				detail: `endpointKey ${ek} contributed twice`
-			}));
-			endpoints[ek] = ep;
-		}
+		for (const ep of contribution.endpoints) yield* addEndpoint(ep);
 	}
+	for (const ep of input.endpoints ?? []) yield* addEndpoint(ep);
 	return {
 		identity: input.identity,
 		manifestVersion: 1,
 		services,
 		endpoints,
-		extras
+		extras,
+		...input.codegen !== void 0 ? { codegen: input.codegen } : {}
 	};
 });
 /**
@@ -68,6 +72,6 @@ const writeManifest = (envelope, path) => Effect.gen(function* () {
 }).pipe(Effect.withSpan("Manifest.writeManifest", { attributes: { "devstack.manifest.path": path } }));
 const serializeEnvelope = (envelope) => JSON.stringify(envelope, null, 2);
 //#endregion
-export { buildEnvelope, writeManifest };
+export { ManifestError, buildEnvelope, writeManifest };
 
 //# sourceMappingURL=manifest.mjs.map

package/dist/substrate/runtime/manifest/manifest.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.mjs","names":[],"sources":["../../../../src/substrate/runtime/manifest/manifest.ts"],"sourcesContent":["// Manifest emitter — endpoint-keyed envelope, atomic write.\n//\n// Architecture § Manifest data model. The envelope is L0 (`identity`\n// tuple, `manifestVersion`, `services` slot, `endpoints` lookup,\n// `extras`). The per-service projection lives in each plugin's\n// Codegenable contribution and is consumed by codegen output, not by\n// the manifest envelope itself.\n//\n// The emitter:\n//   - Accepts per-plugin contributions through a `contribute` Effect.\n//   - Walks endpoint contributions to build the flat `endpoints`\n//     lookup keyed by `endpointKey`. Entries still carry the declared\n//     endpoint `name` for build-integration lookup.\n//   - Writes atomically via tempfile + fsync + rename. The atomic-\n//     write primitive lives in L0 (per architecture § Collapsed:\n//     \"Three tempfile+rename impls → one atomic-write primitive\").\n//   - Validates the envelope against `ManifestEnvelopeSchema` on read.\n//   - Pins `manifestVersion` so future-proofing migrations have a\n//     compatibility seam. The pinned version is `1` for the post-\n//     rewrite envelope. (The old devstack used unversioned manifests\n//     plus a hash field; the rewrite's clean break is `version 1`.)\n//\n// Discipline: zero service names. The writer iterates `pluginKey`-\n// indexed contributions and copies the bytes through. The schema\n// validates the envelope shape, not the per-plugin contents (which\n// are `Schema.Unknown`).\n\nimport { Effect } from 'effect';\nimport { Data } from 'effect';\nimport { FileSystem } from 'effect';\n\nimport type { EndpointKey, PluginKey } from '../../brand.ts';\nimport {\n\ttype EndpointEntry,\n\ttype ManifestExtras,\n\ttype ManifestEnvelope,\n\tManifestEnvelopeSchema,\n} from '../../manifest.ts';\nimport { atomicWriteFile } from '../atomic-write.ts';\nimport { decodeJsonText } from '../runtime-decode.ts';\n\n// -----------------------------------------------------------------------------\n// Pinned schema version\n// -----------------------------------------------------------------------------\n\n/**\n * Schema version pinned at the envelope level. Bump only on a\n * breaking shape change to the envelope (NOT to a per-plugin service\n * slice — those carry their own version via Codegenable contribution).\n *\n * Reader policy:\n *   - Equal version: accept.\n *   - Older version: refuse (advise user to re-run `up`).\n *   - Newer version: refuse (build integration is out of date).\n */\nexport const CURRENT_MANIFEST_VERSION = 1 as const;\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** One error class for every manifest IO failure. */\nexport class ManifestError extends Data.TaggedError('ManifestError')<{\n\treadonly reason:\n\t\t| 'write-failed'\n\t\t| 'read-failed'\n\t\t| 'decode-failed'\n\t\t| 'version-mismatch'\n\t\t| 'duplicate-contribution';\n\treadonly path: string;\n\treadonly detail?: string;\n\treadonly cause?: unknown;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Contribution shape\n// -----------------------------------------------------------------------------\n\n/**\n * One plugin's contribution to the manifest. Keyed by `pluginKey`\n * (branded), opaque `services` blob, plus a flat list of endpoint\n * entries the plugin owns.\n *\n * The writer copies `services` through to\n * `envelope.services[pluginKey]`. The renderer of the typed shape\n * lives in the plugin's Codegenable contribution — the manifest\n * doesn't decode it.\n */\nexport interface PluginManifestContribution {\n\treadonly pluginKey: PluginKey;\n\t/** Plugin's structured slice — opaque to the writer. */\n\treadonly services: unknown;\n\t/** Endpoints owned by this plugin. The writer indexes these by\n\t *  `endpointKey` into the flat top-level lookup. */\n\treadonly endpoints: ReadonlyArray<EndpointEntry>;\n\t/** Optional app-facing extras merged into the top-level extras slot. */\n\treadonly extras?: ManifestExtras;\n}\n\n// -----------------------------------------------------------------------------\n// Public writer interface\n// -----------------------------------------------------------------------------\n\nexport interface WriteManifestInput {\n\treadonly identity: ManifestEnvelope['identity'];\n\treadonly contributions: ReadonlyArray<PluginManifestContribution>;\n\treadonly extras?: ManifestExtras;\n}\n\n/**\n * Build the envelope from per-plugin contributions. Pure; the writer\n * calls this and then atomically writes the JSON.\n *\n * `pluginKey` collisions are an error — two contributions for the\n * same plugin would silently overwrite. Endpoint-key collisions also\n * error: every endpoint has a unique `(pluginKey, dispatchId)` digest\n * by construction; a duplicate means a substrate bug.\n */\nexport const buildEnvelope = (\n\tinput: WriteManifestInput,\n): Effect.Effect<ManifestEnvelope, ManifestError> =>\n\tEffect.gen(function* () {\n\t\tconst services: Record<string, unknown> = {};\n\t\tconst endpoints: Record<string, EndpointEntry> = {};\n\t\tconst extras: Record<string, unknown> = { ...input.extras };\n\n\t\tfor (const contribution of input.contributions) {\n\t\t\tconst key = contribution.pluginKey as string;\n\t\t\tif (key in services) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew ManifestError({\n\t\t\t\t\t\treason: 'duplicate-contribution',\n\t\t\t\t\t\tpath: '(in-memory envelope)',\n\t\t\t\t\t\tdetail: `pluginKey ${key} contributed twice`,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t\tservices[key] = contribution.services;\n\t\t\tif (contribution.extras !== undefined) {\n\t\t\t\tfor (const [extraKey, extraValue] of Object.entries(contribution.extras)) {\n\t\t\t\t\tif (extraKey in extras) {\n\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\tnew ManifestError({\n\t\t\t\t\t\t\t\treason: 'duplicate-contribution',\n\t\t\t\t\t\t\t\tpath: '(in-memory envelope)',\n\t\t\t\t\t\t\t\tdetail: `extras key ${extraKey} contributed twice`,\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\textras[extraKey] = extraValue;\n\t\t\t\t}\n\t\t\t}\n\t\t\tfor (const ep of contribution.endpoints) {\n\t\t\t\tconst ek = ep.endpointKey as string;\n\t\t\t\tif (ek in endpoints) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tnew ManifestError({\n\t\t\t\t\t\t\treason: 'duplicate-contribution',\n\t\t\t\t\t\t\tpath: '(in-memory envelope)',\n\t\t\t\t\t\t\tdetail: `endpointKey ${ek} contributed twice`,\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tendpoints[ek] = ep;\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\tidentity: input.identity,\n\t\t\tmanifestVersion: CURRENT_MANIFEST_VERSION,\n\t\t\tservices,\n\t\t\tendpoints,\n\t\t\textras,\n\t\t};\n\t});\n\n// -----------------------------------------------------------------------------\n// Atomic write — delegates to the canonical primitive.\n// -----------------------------------------------------------------------------\n\n/**\n * Serialize and write the envelope at `path` atomically. Routes\n * through the canonical `atomicWriteFile` primitive (mkdir-parent →\n * O_EXCL temp → write → fsync → rename), so the manifest writer\n * shares ONE owner of the tempfile dance with the state-store and\n * cache.\n */\nexport const writeManifest = (\n\tenvelope: ManifestEnvelope,\n\tpath: string,\n): Effect.Effect<void, ManifestError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst json = serializeEnvelope(envelope);\n\t\tconst bytes = new TextEncoder().encode(json);\n\t\tyield* atomicWriteFile(path, bytes).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(cause) =>\n\t\t\t\t\tnew ManifestError({\n\t\t\t\t\t\treason: 'write-failed',\n\t\t\t\t\t\tpath,\n\t\t\t\t\t\tdetail: `atomic write failed at stage ${cause.stage}`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t}).pipe(\n\t\tEffect.withSpan('Manifest.writeManifest', { attributes: { 'devstack.manifest.path': path } }),\n\t);\n\nconst serializeEnvelope = (envelope: ManifestEnvelope): string =>\n\t// Stable key ordering, deterministic re-emit. `JSON.stringify` with\n\t// 2-space indent is reproducible byte-for-byte given the same\n\t// input object.\n\tJSON.stringify(envelope, null, 2);\n\n// -----------------------------------------------------------------------------\n// Read + decode\n// -----------------------------------------------------------------------------\n\n/**\n * Read and decode the manifest at `path`. Validates against\n * `ManifestEnvelopeSchema` and the pinned `CURRENT_MANIFEST_VERSION`.\n *\n * Used by:\n *   - Codegen (architecture §6) — consumes plugin slices off\n *     `envelope.services[pluginKey]`.\n *   - Build integrations (Vitest, Playwright, generated app code) — consumes\n *     `envelope.endpoints` lookup.\n *\n * The reader is read-only; no mutation, no IO beyond the single read.\n */\nexport const readManifest = (\n\tpath: string,\n): Effect.Effect<ManifestEnvelope, ManifestError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst text = yield* fs\n\t\t\t.readFileString(path)\n\t\t\t.pipe(Effect.mapError((cause) => new ManifestError({ reason: 'read-failed', path, cause })));\n\t\tconst decoded = yield* decodeJsonText(ManifestEnvelopeSchema, text, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) =>\n\t\t\t\tnew ManifestError({ reason: 'decode-failed', path, cause: issue.cause ?? issue }),\n\t\t});\n\t\tif (decoded.manifestVersion !== CURRENT_MANIFEST_VERSION) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew ManifestError({\n\t\t\t\t\treason: 'version-mismatch',\n\t\t\t\t\tpath,\n\t\t\t\t\tdetail: `expected ${CURRENT_MANIFEST_VERSION}, got ${decoded.manifestVersion}`,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\treturn decoded as ManifestEnvelope;\n\t}).pipe(\n\t\tEffect.withSpan('Manifest.readManifest', { attributes: { 'devstack.manifest.path': path } }),\n\t);\n\n// -----------------------------------------------------------------------------\n// Re-export the envelope + endpoint types so downstream substrate\n// modules (codegen, build integrations) don't reach into substrate/\n// directly.\n// -----------------------------------------------------------------------------\n\nexport type { EndpointEntry, EndpointKey, ManifestEnvelope, PluginKey };\nexport { ManifestEnvelopeSchema };\n"],"mappings":";;;;AA8DA,IAAa,gBAAb,cAAmC,KAAK,YAAY,gBAAgB,CAUjE;;;;;;;;;;AA8CH,MAAa,iBACZ,UAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAoC,EAAE;CAC5C,MAAM,YAA2C,EAAE;CACnD,MAAM,SAAkC,EAAE,GAAG,MAAM,QAAQ;AAE3D,MAAK,MAAM,gBAAgB,MAAM,eAAe;EAC/C,MAAM,MAAM,aAAa;AACzB,MAAI,OAAO,SACV,QAAO,OAAO,OAAO,KACpB,IAAI,cAAc;GACjB,QAAQ;GACR,MAAM;GACN,QAAQ,aAAa,IAAI;GACzB,CAAC,CACF;AAEF,WAAS,OAAO,aAAa;AAC7B,MAAI,aAAa,WAAW,KAAA,EAC3B,MAAK,MAAM,CAAC,UAAU,eAAe,OAAO,QAAQ,aAAa,OAAO,EAAE;AACzE,OAAI,YAAY,OACf,QAAO,OAAO,OAAO,KACpB,IAAI,cAAc;IACjB,QAAQ;IACR,MAAM;IACN,QAAQ,cAAc,SAAS;IAC/B,CAAC,CACF;AAEF,UAAO,YAAY;;AAGrB,OAAK,MAAM,MAAM,aAAa,WAAW;GACxC,MAAM,KAAK,GAAG;AACd,OAAI,MAAM,UACT,QAAO,OAAO,OAAO,KACpB,IAAI,cAAc;IACjB,QAAQ;IACR,MAAM;IACN,QAAQ,eAAe,GAAG;IAC1B,CAAC,CACF;AAEF,aAAU,MAAM;;;AAIlB,QAAO;EACN,UAAU,MAAM;EAChB,iBAAA;EACA;EACA;EACA;EACA;EACA;;;;;;;;AAaH,MAAa,iBACZ,UACA,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,kBAAkB,SAAS;AAExC,QAAO,gBAAgB,MADT,IAAI,aAAa,CAAC,OAAO,KACL,CAAC,CAAC,KACnC,OAAO,UACL,UACA,IAAI,cAAc;EACjB,QAAQ;EACR;EACA,QAAQ,gCAAgC,MAAM;EAC9C;EACA,CAAC,CACH,CACD;EACA,CAAC,KACF,OAAO,SAAS,0BAA0B,EAAE,YAAY,EAAE,0BAA0B,MAAM,EAAE,CAAC,CAC7F;AAEF,MAAM,qBAAqB,aAI1B,KAAK,UAAU,UAAU,MAAM,EAAE"}
+{"version":3,"file":"manifest.mjs","names":[],"sources":["../../../../src/substrate/runtime/manifest/manifest.ts"],"sourcesContent":["// Manifest emitter — endpoint-keyed envelope, atomic write.\n//\n// Architecture § Manifest data model. The envelope is L0 (`identity`\n// tuple, `manifestVersion`, `services` slot, `endpoints` lookup,\n// `extras`). The per-service projection lives in each plugin's\n// Codegenable contribution and is consumed by codegen output, not by\n// the manifest envelope itself.\n//\n// The emitter:\n//   - Accepts per-plugin contributions through a `contribute` Effect.\n//   - Walks endpoint contributions to build the flat `endpoints`\n//     lookup keyed by `endpointKey`. Entries still carry the declared\n//     endpoint `name` for build-integration lookup.\n//   - Writes atomically via tempfile + fsync + rename. The atomic-\n//     write primitive lives in L0 (per architecture § Collapsed:\n//     \"Three tempfile+rename impls → one atomic-write primitive\").\n//   - Validates the envelope against `ManifestEnvelopeSchema` on read.\n//   - Pins `manifestVersion` so future-proofing migrations have a\n//     compatibility seam. The pinned version is `1` for the post-\n//     rewrite envelope. (The old devstack used unversioned manifests\n//     plus a hash field; the rewrite's clean break is `version 1`.)\n//\n// Discipline: zero service names. The writer iterates `pluginKey`-\n// indexed contributions and copies the bytes through. The schema\n// validates the envelope shape, not the per-plugin contents (which\n// are `Schema.Unknown`).\n\nimport { Effect } from 'effect';\nimport { Data } from 'effect';\nimport { FileSystem } from 'effect';\n\nimport type { EndpointKey, PluginKey } from '../../brand.ts';\nimport {\n\ttype EndpointEntry,\n\ttype ManifestCodegen,\n\ttype ManifestExtras,\n\ttype ManifestEnvelope,\n\tManifestEnvelopeSchema,\n} from '../../manifest.ts';\nimport { atomicWriteFile } from '../atomic-write.ts';\nimport { decodeJsonText } from '../runtime-decode.ts';\n\n// -----------------------------------------------------------------------------\n// Pinned schema version\n// -----------------------------------------------------------------------------\n\n/**\n * Schema version pinned at the envelope level. Bump only on a\n * breaking shape change to the envelope (NOT to a per-plugin service\n * slice — those carry their own version via Codegenable contribution).\n *\n * Reader policy:\n *   - Equal version: accept.\n *   - Older version: refuse (advise user to re-run `up`).\n *   - Newer version: refuse (build integration is out of date).\n */\nexport const CURRENT_MANIFEST_VERSION = 1 as const;\n\n// -----------------------------------------------------------------------------\n// Errors\n// -----------------------------------------------------------------------------\n\n/** One error class for every manifest IO failure. */\nexport class ManifestError extends Data.TaggedError('ManifestError')<{\n\treadonly reason:\n\t\t| 'write-failed'\n\t\t| 'read-failed'\n\t\t| 'decode-failed'\n\t\t| 'version-mismatch'\n\t\t| 'duplicate-contribution';\n\treadonly path: string;\n\treadonly detail?: string;\n\treadonly cause?: unknown;\n}> {}\n\n// -----------------------------------------------------------------------------\n// Contribution shape\n// -----------------------------------------------------------------------------\n\n/**\n * One plugin's contribution to the manifest. Keyed by `pluginKey`\n * (branded), opaque `services` blob, plus a flat list of endpoint\n * entries the plugin owns.\n *\n * The writer copies `services` through to\n * `envelope.services[pluginKey]`. The renderer of the typed shape\n * lives in the plugin's Codegenable contribution — the manifest\n * doesn't decode it.\n */\nexport interface PluginManifestContribution {\n\treadonly pluginKey: PluginKey;\n\t/** Plugin's structured slice — opaque to the writer. */\n\treadonly services: unknown;\n\t/** Endpoints owned by this plugin. The writer indexes these by\n\t *  `endpointKey` into the flat top-level lookup. */\n\treadonly endpoints: ReadonlyArray<EndpointEntry>;\n\t/** Optional app-facing extras merged into the top-level extras slot. */\n\treadonly extras?: ManifestExtras;\n}\n\n// -----------------------------------------------------------------------------\n// Public writer interface\n// -----------------------------------------------------------------------------\n\nexport interface WriteManifestInput {\n\treadonly identity: ManifestEnvelope['identity'];\n\treadonly contributions: ReadonlyArray<PluginManifestContribution>;\n\treadonly endpoints?: ReadonlyArray<EndpointEntry>;\n\treadonly extras?: ManifestExtras;\n\t/** Per-stack codegen metadata (the resolved absolute `generatedDir`).\n\t *  Optional + additive — omitting it produces an envelope without the\n\t *  `codegen` key, identical to a pre-field manifest. */\n\treadonly codegen?: ManifestCodegen;\n}\n\n/**\n * Build the envelope from per-plugin contributions. Pure; the writer\n * calls this and then atomically writes the JSON.\n *\n * `pluginKey` collisions are an error — two contributions for the\n * same plugin would silently overwrite. Endpoint-key collisions also\n * error: every endpoint has a unique `(pluginKey, dispatchId)` digest\n * by construction; a duplicate means a substrate bug.\n */\nexport const buildEnvelope = (\n\tinput: WriteManifestInput,\n): Effect.Effect<ManifestEnvelope, ManifestError> =>\n\tEffect.gen(function* () {\n\t\tconst services: Record<string, unknown> = {};\n\t\tconst endpoints: Record<string, EndpointEntry> = {};\n\t\tconst extras: Record<string, unknown> = { ...input.extras };\n\n\t\tconst addEndpoint = (ep: EndpointEntry): Effect.Effect<void, ManifestError> =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\tconst ek = ep.endpointKey as string;\n\t\t\t\tif (ek in endpoints) {\n\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\tnew ManifestError({\n\t\t\t\t\t\t\treason: 'duplicate-contribution',\n\t\t\t\t\t\t\tpath: '(in-memory envelope)',\n\t\t\t\t\t\t\tdetail: `endpointKey ${ek} contributed twice`,\n\t\t\t\t\t\t}),\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tendpoints[ek] = ep;\n\t\t\t});\n\n\t\tfor (const contribution of input.contributions) {\n\t\t\tconst key = contribution.pluginKey as string;\n\t\t\tif (key in services) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\tnew ManifestError({\n\t\t\t\t\t\treason: 'duplicate-contribution',\n\t\t\t\t\t\tpath: '(in-memory envelope)',\n\t\t\t\t\t\tdetail: `pluginKey ${key} contributed twice`,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t\tservices[key] = contribution.services;\n\t\t\tif (contribution.extras !== undefined) {\n\t\t\t\tfor (const [extraKey, extraValue] of Object.entries(contribution.extras)) {\n\t\t\t\t\tif (extraKey in extras) {\n\t\t\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\t\t\tnew ManifestError({\n\t\t\t\t\t\t\t\treason: 'duplicate-contribution',\n\t\t\t\t\t\t\t\tpath: '(in-memory envelope)',\n\t\t\t\t\t\t\t\tdetail: `extras key ${extraKey} contributed twice`,\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\textras[extraKey] = extraValue;\n\t\t\t\t}\n\t\t\t}\n\t\t\tfor (const ep of contribution.endpoints) {\n\t\t\t\tyield* addEndpoint(ep);\n\t\t\t}\n\t\t}\n\t\tfor (const ep of input.endpoints ?? []) {\n\t\t\tyield* addEndpoint(ep);\n\t\t}\n\n\t\treturn {\n\t\t\tidentity: input.identity,\n\t\t\tmanifestVersion: CURRENT_MANIFEST_VERSION,\n\t\t\tservices,\n\t\t\tendpoints,\n\t\t\textras,\n\t\t\t// Spread only when present so an omitted `codegen` yields the\n\t\t\t// exact same envelope (and serialized bytes) as a pre-field\n\t\t\t// manifest — additive, no churn for stacks that don't record it.\n\t\t\t...(input.codegen !== undefined ? { codegen: input.codegen } : {}),\n\t\t};\n\t});\n\n// -----------------------------------------------------------------------------\n// Atomic write — delegates to the canonical primitive.\n// -----------------------------------------------------------------------------\n\n/**\n * Serialize and write the envelope at `path` atomically. Routes\n * through the canonical `atomicWriteFile` primitive (mkdir-parent →\n * O_EXCL temp → write → fsync → rename), so the manifest writer\n * shares ONE owner of the tempfile dance with the state-store and\n * cache.\n */\nexport const writeManifest = (\n\tenvelope: ManifestEnvelope,\n\tpath: string,\n): Effect.Effect<void, ManifestError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst json = serializeEnvelope(envelope);\n\t\tconst bytes = new TextEncoder().encode(json);\n\t\tyield* atomicWriteFile(path, bytes).pipe(\n\t\t\tEffect.mapError(\n\t\t\t\t(cause) =>\n\t\t\t\t\tnew ManifestError({\n\t\t\t\t\t\treason: 'write-failed',\n\t\t\t\t\t\tpath,\n\t\t\t\t\t\tdetail: `atomic write failed at stage ${cause.stage}`,\n\t\t\t\t\t\tcause,\n\t\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t}).pipe(\n\t\tEffect.withSpan('Manifest.writeManifest', { attributes: { 'devstack.manifest.path': path } }),\n\t);\n\nconst serializeEnvelope = (envelope: ManifestEnvelope): string =>\n\t// Stable key ordering, deterministic re-emit. `JSON.stringify` with\n\t// 2-space indent is reproducible byte-for-byte given the same\n\t// input object.\n\tJSON.stringify(envelope, null, 2);\n\n// -----------------------------------------------------------------------------\n// Read + decode\n// -----------------------------------------------------------------------------\n\n/**\n * Read and decode the manifest at `path`. Validates against\n * `ManifestEnvelopeSchema` and the pinned `CURRENT_MANIFEST_VERSION`.\n *\n * Used by:\n *   - Codegen (architecture §6) — consumes plugin slices off\n *     `envelope.services[pluginKey]`.\n *   - Build integrations (Vitest, Playwright, generated app code) — consumes\n *     `envelope.endpoints` lookup.\n *\n * The reader is read-only; no mutation, no IO beyond the single read.\n */\nexport const readManifest = (\n\tpath: string,\n): Effect.Effect<ManifestEnvelope, ManifestError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tconst fs = yield* FileSystem.FileSystem;\n\t\tconst text = yield* fs\n\t\t\t.readFileString(path)\n\t\t\t.pipe(Effect.mapError((cause) => new ManifestError({ reason: 'read-failed', path, cause })));\n\t\tconst decoded = yield* decodeJsonText(ManifestEnvelopeSchema, text, {\n\t\t\tsource: path,\n\t\t\tmkError: (issue) =>\n\t\t\t\tnew ManifestError({ reason: 'decode-failed', path, cause: issue.cause ?? issue }),\n\t\t});\n\t\tif (decoded.manifestVersion !== CURRENT_MANIFEST_VERSION) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\tnew ManifestError({\n\t\t\t\t\treason: 'version-mismatch',\n\t\t\t\t\tpath,\n\t\t\t\t\tdetail: `expected ${CURRENT_MANIFEST_VERSION}, got ${decoded.manifestVersion}`,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\treturn decoded as ManifestEnvelope;\n\t}).pipe(\n\t\tEffect.withSpan('Manifest.readManifest', { attributes: { 'devstack.manifest.path': path } }),\n\t);\n\n// -----------------------------------------------------------------------------\n// Re-export the envelope + endpoint types so downstream substrate\n// modules (codegen, build integrations) don't reach into substrate/\n// directly.\n// -----------------------------------------------------------------------------\n\nexport type { EndpointEntry, EndpointKey, ManifestCodegen, ManifestEnvelope, PluginKey };\nexport { ManifestEnvelopeSchema };\n"],"mappings":";;;;;AA+DA,IAAa,gBAAb,cAAmC,KAAK,YAAY,gBAAgB,CAUjE;;;;;;;;;;AAmDH,MAAa,iBACZ,UAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAoC,EAAE;CAC5C,MAAM,YAA2C,EAAE;CACnD,MAAM,SAAkC,EAAE,GAAG,MAAM,QAAQ;CAE3D,MAAM,eAAe,OACpB,OAAO,IAAI,aAAa;EACvB,MAAM,KAAK,GAAG;AACd,MAAI,MAAM,UACT,QAAO,OAAO,OAAO,KACpB,IAAI,cAAc;GACjB,QAAQ;GACR,MAAM;GACN,QAAQ,eAAe,GAAG;GAC1B,CAAC,CACF;AAEF,YAAU,MAAM;GACf;AAEH,MAAK,MAAM,gBAAgB,MAAM,eAAe;EAC/C,MAAM,MAAM,aAAa;AACzB,MAAI,OAAO,SACV,QAAO,OAAO,OAAO,KACpB,IAAI,cAAc;GACjB,QAAQ;GACR,MAAM;GACN,QAAQ,aAAa,IAAI;GACzB,CAAC,CACF;AAEF,WAAS,OAAO,aAAa;AAC7B,MAAI,aAAa,WAAW,KAAA,EAC3B,MAAK,MAAM,CAAC,UAAU,eAAe,OAAO,QAAQ,aAAa,OAAO,EAAE;AACzE,OAAI,YAAY,OACf,QAAO,OAAO,OAAO,KACpB,IAAI,cAAc;IACjB,QAAQ;IACR,MAAM;IACN,QAAQ,cAAc,SAAS;IAC/B,CAAC,CACF;AAEF,UAAO,YAAY;;AAGrB,OAAK,MAAM,MAAM,aAAa,UAC7B,QAAO,YAAY,GAAG;;AAGxB,MAAK,MAAM,MAAM,MAAM,aAAa,EAAE,CACrC,QAAO,YAAY,GAAG;AAGvB,QAAO;EACN,UAAU,MAAM;EAChB,iBAAA;EACA;EACA;EACA;EAIA,GAAI,MAAM,YAAY,KAAA,IAAY,EAAE,SAAS,MAAM,SAAS,GAAG,EAAE;EACjE;EACA;;;;;;;;AAaH,MAAa,iBACZ,UACA,SAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,kBAAkB,SAAS;AAExC,QAAO,gBAAgB,MADT,IAAI,aAAa,CAAC,OAAO,KACL,CAAC,CAAC,KACnC,OAAO,UACL,UACA,IAAI,cAAc;EACjB,QAAQ;EACR;EACA,QAAQ,gCAAgC,MAAM;EAC9C;EACA,CAAC,CACH,CACD;EACA,CAAC,KACF,OAAO,SAAS,0BAA0B,EAAE,YAAY,EAAE,0BAA0B,MAAM,EAAE,CAAC,CAC7F;AAEF,MAAM,qBAAqB,aAI1B,KAAK,UAAU,UAAU,MAAM,EAAE"}

package/dist/substrate/runtime/mode-errors.mjs

@@ -0,0 +1,20 @@
+import { Schema } from "effect";
+Schema.TaggedErrorClass()("ForkIncompatibleError", {
+	/** Refusing factory variant — e.g. `'walrusLocalCluster'`,
+	*  `'sealLocalKeygen'`. Lets multiple plugin factories share
+	*  this shape without losing the call-site distinction. */
+	variant: Schema.String,
+	/** Resolved network the composition refused under. */
+	network: Schema.String,
+	/** Imperative one-liner suitable for stderr. */
+	message: Schema.String,
+	/** Actionable next step (the known-deployment alternative). */
+	hint: Schema.optional(Schema.String),
+	/** Optional original cause when the refusal wraps an underlying
+	*  fault (rare — typical use is a pure factory-time refusal). */
+	cause: Schema.optional(Schema.Defect)
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=mode-errors.mjs.map

package/dist/substrate/runtime/mode-errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-errors.mjs","names":[],"sources":["../../../src/substrate/runtime/mode-errors.ts"],"sourcesContent":["// Cross-cutting mode-refusal errors.\n//\n// Reviews finding (cross-cutting.md §\"Error model\"): the\n// `ForkIncompatibleError` tag is defined twice today — once in\n// `plugins/walrus/errors.ts`, once in `plugins/seal/errors.ts` — with\n// conflicting field shapes. Two `_tag` literals with the same name\n// but different shapes violate STYLE_GUIDE §2 (\"One `_tag` literal\n// per logical error type across the whole package\").\n//\n// Lift the canonical shape here. Both plugins import from substrate\n// in PR3; this PR does NOT modify the plugin-side error files (per\n// PR1 scope).\n//\n// Shape decision:\n//   - `variant` carries the refusing factory name (e.g.\n//     `'walrusLocalCluster'`, `'sealLocalKeygen'`). Lets walrus and\n//     seal share the shape without losing the call-site distinction.\n//   - `network` carries the resolved `*-fork` network string the\n//     user passed.\n//   - `message` is the imperative one-liner suitable for stderr.\n//   - `hint` is the actionable next step (the known-deployment\n//     alternative).\n//\n// Substrate is name-blind on the plugin level — these fields are\n// generic (\"which factory variant refused\" + \"which network it\n// refused under\") and do NOT name walrus / seal.\n\nimport { Schema } from 'effect';\n\n/**\n * Synchronous factory-time refusal raised by a plugin factory\n * variant when composed against a network the variant cannot serve\n * (canonically: a `*-fork` chain that doesn't expose the fullnode\n * surface the variant requires).\n *\n * Architecture (Tension 11): primary refusal is TYPE-LEVEL via\n * mode-narrowed factory namespaces — `walrusFor(forkNet).<mode>` only\n * exposes `.known`. This runtime shape is defense-in-depth for\n * callers that bypass the type-level narrowing (env-driven factories,\n * plugin composition through resolved values).\n *\n * Used by walrus (`local-cluster` variant) and seal (`local-keygen`\n * variant) today; future plugin factories refusing on a network\n * predicate share this single shape.\n */\nexport class ForkIncompatibleError extends Schema.TaggedErrorClass<ForkIncompatibleError>()(\n\t'ForkIncompatibleError',\n\t{\n\t\t/** Refusing factory variant — e.g. `'walrusLocalCluster'`,\n\t\t *  `'sealLocalKeygen'`. Lets multiple plugin factories share\n\t\t *  this shape without losing the call-site distinction. */\n\t\tvariant: Schema.String,\n\t\t/** Resolved network the composition refused under. */\n\t\tnetwork: Schema.String,\n\t\t/** Imperative one-liner suitable for stderr. */\n\t\tmessage: Schema.String,\n\t\t/** Actionable next step (the known-deployment alternative). */\n\t\thint: Schema.optional(Schema.String),\n\t\t/** Optional original cause when the refusal wraps an underlying\n\t\t *  fault (rare — typical use is a pure factory-time refusal). */\n\t\tcause: Schema.optional(Schema.Defect),\n\t},\n) {}\n"],"mappings":";AA6C2C,OAAO,kBAAyC,CAC1F,yBACA;;;;CAIC,SAAS,OAAO;;CAEhB,SAAS,OAAO;;CAEhB,SAAS,OAAO;;CAEhB,MAAM,OAAO,SAAS,OAAO,OAAO;;;CAGpC,OAAO,OAAO,SAAS,OAAO,OAAO;CACrC,CACD"}

package/dist/substrate/runtime/observability/cascade-formatter.mjs

@@ -1,4 +1,5 @@
 import { redactText, redactValue } from "./redaction.mjs";
+import { Cause } from "effect";
 //#region src/substrate/runtime/observability/cascade-formatter.ts
 /** Empty registry — the formatter falls back to the default
 *  rendering for every value. */
@@ -6,7 +7,6 @@ const emptyFormatterRegistry = /* @__PURE__ */ new Map();
 const DEFAULT_FIELD_TRUNCATE = 8192;
 const DEFAULT_MAX_DEPTH = 12;
 const isTaggedError = (value) => typeof value === "object" && value !== null && typeof value._tag === "string";
-const isCauseLike = (value) => typeof value === "object" && value !== null && Array.isArray(value.reasons);
 /**
 * Format an Effect `Cause<E>` as a multi-line cascade string. Pure.
 *
@@ -24,9 +24,8 @@ const formatCause = (cause, options) => {
 		redactions: options?.redactions ?? []
 	};
 	const visited = /* @__PURE__ */ new WeakSet();
-	const reasons = cause.reasons;
-	if (reasons.length === 0) return "(empty cause)";
-	return reasons.map((reason) => formatReason(reason, opts, visited, 0)).join("\n--- (also)\n");
+	if (cause.reasons.length === 0) return "(empty cause)";
+	return cause.reasons.map((reason) => formatReason(reason, opts, visited, 0)).join("\n--- (also)\n");
 };
 /**
 * Format an arbitrary value (a `Cause`, a tagged error, a plain
@@ -50,11 +49,9 @@ const truncate = (s, limit, redactions) => {
 };
 const indent = (s, prefix) => s.split("\n").map((line) => `${prefix}${line}`).join("\n");
 const formatReason = (reason, opts, visited, depth) => {
-	switch (reason._tag) {
-		case "Fail": return formatAny(reason.error, opts, visited, depth);
-		case "Die": return `DEFECT:\n${indent(formatAny(reason.defect, opts, visited, depth), "  ")}`;
-		case "Interrupt": return `INTERRUPT[${reason.fiberId ?? "unknown"}]`;
-	}
+	if (Cause.isFailReason(reason)) return formatAny(reason.error, opts, visited, depth);
+	if (Cause.isDieReason(reason)) return `DEFECT:\n${indent(formatAny(reason.defect, opts, visited, depth), "  ")}`;
+	return `INTERRUPT[${reason.fiberId ?? "unknown"}]`;
 };
 const formatAny = (value, opts, visited, depth) => {
 	if (value === void 0 || value === null) return "";
@@ -63,10 +60,9 @@ const formatAny = (value, opts, visited, depth) => {
 		if (visited.has(value)) return "…[cycle]";
 		visited.add(value);
 	}
-	if (isCauseLike(value)) {
-		const rs = value.reasons;
-		if (rs.length === 0) return "(empty cause)";
-		return rs.map((r) => formatReason(r, opts, visited, depth)).join("\n--- (also)\n");
+	if (Cause.isCause(value)) {
+		if (value.reasons.length === 0) return "(empty cause)";
+		return value.reasons.map((r) => formatReason(r, opts, visited, depth)).join("\n--- (also)\n");
 	}
 	if (isTaggedError(value)) return formatTagged(value, opts, visited, depth);
 	if (value instanceof Error) {

package/dist/substrate/runtime/observability/cascade-formatter.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cascade-formatter.mjs","names":[],"sources":["../../../../src/substrate/runtime/observability/cascade-formatter.ts"],"sourcesContent":["// L0 cascade formatter.\n//\n// Architecture § Substrate violations § \"C2 — relocate cause walker\n// from the renderer\". The cascade formatter walks an Effect `Cause`\n// and returns a stringified cascade of taxonomy-aware lines. Called\n// from CLI, TUI, prune — anywhere a failure surfaces.\n//\n// Hard rules:\n//   - PURE. No IO, no Effect, no clocks. Input → string.\n//   - No service names: the formatter inspects `_tag` strings and\n//     structured fields verbatim, never branches on a specific\n//     concrete plugin error class.\n//   - Pluggable per-error-class formatters via a `formatters` map\n//     keyed by `_tag`. The default formatter handles tagged errors,\n//     plain `Error`, defects, and Interrupts.\n//\n// Output shape:\n//\n//   <Tag> (<phase?>): <message>\n//     exitCode: <n>\n//     stderr: <text…[truncated]>\n//     <field>: <value>\n//     caused by:\n//       <recursive render, indented by 2 spaces>\n//\n// Multi-`Fail` causes (parallel failures) render with a `--- (also)`\n// separator. Defects (`Die`) render with `DEFECT (<tag>?)` prefix so\n// the operator can tell programmer errors from typed failures at a\n// glance. Interrupts render as `INTERRUPT[<fiberId>]`.\n\nimport type { Cause } from 'effect';\n\nimport { redactText, redactValue, type RedactionRule } from './redaction.ts';\n\n// `Cause` is a namespace in effect v4; the actual cause type is\n// `Cause.Cause<E>`. We re-alias here so call sites read naturally.\ntype CauseT<E> = Cause.Cause<E>;\n\n// -----------------------------------------------------------------------------\n// Plug-in formatter API\n// -----------------------------------------------------------------------------\n\n/**\n * Per-tag formatter override. Receives the tagged-error-like value\n * and the default formatter (so a plugin formatter can recurse on a\n * nested `cause` field without re-implementing the walk).\n *\n * Return `null` to fall back to the default rendering.\n *\n * Architecture: the formatter registry is keyed by `_tag` string —\n * the substrate never imports a concrete plugin error class. Plugins\n * register their custom renderer via the supervisor harvest loop over\n * `errorContributions` (see `substrate/plugin.ts:PluginErrorContribution`).\n */\nexport type TagFormatter = (\n\tvalue: TaggedErrorLike,\n\trecurse: (inner: unknown) => string,\n) => string | null;\n\n/** Per-tag formatter map. */\nexport type FormatterRegistry = ReadonlyMap<string, TagFormatter>;\n\n/** Empty registry — the formatter falls back to the default\n *  rendering for every value. */\nexport const emptyFormatterRegistry: FormatterRegistry = new Map();\n\n// -----------------------------------------------------------------------------\n// Render budget\n// -----------------------------------------------------------------------------\n\nconst DEFAULT_FIELD_TRUNCATE = 8192;\nconst DEFAULT_MAX_DEPTH = 12;\n\nexport interface FormatOptions {\n\t/** Per-tag override registry. Defaults to the empty registry. */\n\treadonly formatters?: FormatterRegistry;\n\t/** Truncate individual fields (stderr/stdout/detail) past this\n\t *  length. Default 8 KiB. */\n\treadonly fieldTruncate?: number;\n\t/** Hard recursion cap. Cyclic graphs are detected separately by\n\t *  visit-set; this guards against pathological cause chains.\n\t *  Default 12. */\n\treadonly maxDepth?: number;\n\t/** Optional redaction rules applied before rendering string fields. */\n\treadonly redactions?: ReadonlyArray<RedactionRule>;\n}\n\n// -----------------------------------------------------------------------------\n// Type guards (structural — no imports of concrete classes)\n// -----------------------------------------------------------------------------\n\n/** Shape of a `Schema.TaggedError` / `Data.TaggedError` instance.\n *  The cascade formatter never imports a concrete class — it dispatches\n *  on `_tag`. */\nexport interface TaggedErrorLike {\n\treadonly _tag: string;\n\treadonly message?: unknown;\n\treadonly cause?: unknown;\n\treadonly phase?: unknown;\n\treadonly stderr?: unknown;\n\treadonly stdout?: unknown;\n\treadonly exitCode?: unknown;\n\treadonly [key: string]: unknown;\n\treadonly detail?: unknown;\n\treadonly op?: unknown;\n}\n\nexport const isTaggedError = (value: unknown): value is TaggedErrorLike =>\n\ttypeof value === 'object' &&\n\tvalue !== null &&\n\ttypeof (value as { _tag?: unknown })._tag === 'string';\n\ninterface CauseLike {\n\treadonly reasons: ReadonlyArray<ReasonLike>;\n}\n\ninterface FailReasonLike {\n\treadonly _tag: 'Fail';\n\treadonly error: unknown;\n}\ninterface DieReasonLike {\n\treadonly _tag: 'Die';\n\treadonly defect: unknown;\n}\ninterface InterruptReasonLike {\n\treadonly _tag: 'Interrupt';\n\treadonly fiberId: number | undefined;\n}\ntype ReasonLike = FailReasonLike | DieReasonLike | InterruptReasonLike;\n\nconst isCauseLike = (value: unknown): value is CauseLike =>\n\ttypeof value === 'object' &&\n\tvalue !== null &&\n\tArray.isArray((value as { reasons?: unknown }).reasons);\n\n// -----------------------------------------------------------------------------\n// Public entry points\n// -----------------------------------------------------------------------------\n\n/**\n * Format an Effect `Cause<E>` as a multi-line cascade string. Pure.\n *\n * Multiple `Fail` reasons render as separate blocks joined by\n * `--- (also)` so parallel failures are visible. Defects render with\n * a `DEFECT` prefix. Interrupts render with `INTERRUPT[<fiberId>]`.\n *\n * Cyclic `cause` chains are broken with `…[cycle]`.\n */\nexport const formatCause = <E>(cause: CauseT<E>, options?: FormatOptions): string => {\n\tconst opts: Required<FormatOptions> = {\n\t\tformatters: options?.formatters ?? emptyFormatterRegistry,\n\t\tfieldTruncate: options?.fieldTruncate ?? DEFAULT_FIELD_TRUNCATE,\n\t\tmaxDepth: options?.maxDepth ?? DEFAULT_MAX_DEPTH,\n\t\tredactions: options?.redactions ?? [],\n\t};\n\tconst visited = new WeakSet<object>();\n\tconst reasons = (cause as unknown as CauseLike).reasons;\n\tif (reasons.length === 0) return '(empty cause)';\n\tconst rendered = reasons.map((reason) => formatReason(reason, opts, visited, 0));\n\treturn rendered.join('\\n--- (also)\\n');\n};\n\n/**\n * Format an arbitrary value (a `Cause`, a tagged error, a plain\n * `Error`, or anything else) using the cascade rules. Pure.\n *\n * The pretty-error renderer (`pretty-error.ts`) is a thin wrapper\n * over this — it just sets the IO conventions (where to write,\n * what to truncate per-context). The formatting logic lives here.\n */\nexport const formatValue = (value: unknown, options?: FormatOptions): string => {\n\tconst opts: Required<FormatOptions> = {\n\t\tformatters: options?.formatters ?? emptyFormatterRegistry,\n\t\tfieldTruncate: options?.fieldTruncate ?? DEFAULT_FIELD_TRUNCATE,\n\t\tmaxDepth: options?.maxDepth ?? DEFAULT_MAX_DEPTH,\n\t\tredactions: options?.redactions ?? [],\n\t};\n\treturn formatAny(value, opts, new WeakSet(), 0);\n};\n\n// -----------------------------------------------------------------------------\n// Internals\n// -----------------------------------------------------------------------------\n\nconst truncate = (s: string, limit: number, redactions: ReadonlyArray<RedactionRule>): string => {\n\tconst redacted = redactText(s, redactions);\n\treturn redacted.length > limit ? `${redacted.slice(0, limit)}…[truncated]` : redacted;\n};\n\nconst indent = (s: string, prefix: string): string =>\n\ts\n\t\t.split('\\n')\n\t\t.map((line) => `${prefix}${line}`)\n\t\t.join('\\n');\n\nconst formatReason = (\n\treason: ReasonLike,\n\topts: Required<FormatOptions>,\n\tvisited: WeakSet<object>,\n\tdepth: number,\n): string => {\n\tswitch (reason._tag) {\n\t\tcase 'Fail':\n\t\t\treturn formatAny(reason.error, opts, visited, depth);\n\t\tcase 'Die': {\n\t\t\tconst inner = formatAny(reason.defect, opts, visited, depth);\n\t\t\treturn `DEFECT:\\n${indent(inner, '  ')}`;\n\t\t}\n\t\tcase 'Interrupt':\n\t\t\treturn `INTERRUPT[${reason.fiberId ?? 'unknown'}]`;\n\t}\n};\n\nconst formatAny = (\n\tvalue: unknown,\n\topts: Required<FormatOptions>,\n\tvisited: WeakSet<object>,\n\tdepth: number,\n): string => {\n\tif (value === undefined || value === null) return '';\n\tif (depth > opts.maxDepth) return '…[max depth]';\n\tif (typeof value === 'object') {\n\t\tif (visited.has(value as object)) return '…[cycle]';\n\t\tvisited.add(value as object);\n\t}\n\tif (isCauseLike(value)) {\n\t\tconst rs = value.reasons;\n\t\tif (rs.length === 0) return '(empty cause)';\n\t\treturn rs.map((r) => formatReason(r, opts, visited, depth)).join('\\n--- (also)\\n');\n\t}\n\tif (isTaggedError(value)) {\n\t\treturn formatTagged(value, opts, visited, depth);\n\t}\n\tif (value instanceof Error) {\n\t\tconst header = `${value.name}: ${value.message}`;\n\t\tif (value.stack && value.stack !== header) return value.stack;\n\t\treturn header;\n\t}\n\tif (typeof value === 'string') return redactText(value, opts.redactions);\n\ttry {\n\t\treturn JSON.stringify(redactValue(value, opts.redactions));\n\t} catch {\n\t\treturn String(value);\n\t}\n};\n\nconst formatTagged = (\n\tvalue: TaggedErrorLike,\n\topts: Required<FormatOptions>,\n\tvisited: WeakSet<object>,\n\tdepth: number,\n): string => {\n\tconst override = opts.formatters.get(value._tag);\n\tif (override) {\n\t\tconst result = override(value, (inner) => formatAny(inner, opts, visited, depth + 1));\n\t\tif (result !== null) return result;\n\t}\n\n\tconst qualifier =\n\t\ttypeof value.phase === 'string'\n\t\t\t? `(${value.phase})`\n\t\t\t: typeof value.op === 'string'\n\t\t\t\t? `(${value.op})`\n\t\t\t\t: '';\n\tconst message =\n\t\ttypeof value.message === 'string' ? redactText(value.message, opts.redactions) : '';\n\tconst header = qualifier ? `${value._tag} ${qualifier}: ${message}` : `${value._tag}: ${message}`;\n\n\tconst lines: Array<string> = [header];\n\tif (typeof value.exitCode === 'number') lines.push(`  exitCode: ${value.exitCode}`);\n\tif (typeof value.stderr === 'string' && value.stderr.trim().length > 0) {\n\t\tlines.push(`  stderr: ${truncate(value.stderr.trim(), opts.fieldTruncate, opts.redactions)}`);\n\t}\n\tif (typeof value.stdout === 'string' && value.stdout.trim().length > 0) {\n\t\tlines.push(`  stdout: ${truncate(value.stdout.trim(), opts.fieldTruncate, opts.redactions)}`);\n\t}\n\tif (typeof value.detail === 'string' && value.detail.trim().length > 0) {\n\t\tlines.push(`  detail: ${truncate(value.detail.trim(), opts.fieldTruncate, opts.redactions)}`);\n\t}\n\n\t// Surface any extra plain-data fields the tagged error carries.\n\t// We skip the conventional ones already rendered above plus `_tag`,\n\t// `cause`. This makes the formatter discover-by-shape: a plugin\n\t// adding `path` or `kind` to its error gets it rendered for free.\n\tconst conventional = new Set([\n\t\t'_tag',\n\t\t'message',\n\t\t'cause',\n\t\t'phase',\n\t\t'stderr',\n\t\t'stdout',\n\t\t'exitCode',\n\t\t'detail',\n\t\t'op',\n\t]);\n\tfor (const key of Object.keys(value)) {\n\t\tif (conventional.has(key)) continue;\n\t\tconst v = (value as unknown as Record<string, unknown>)[key];\n\t\tif (v === undefined || v === null) continue;\n\t\tconst rendered =\n\t\t\ttypeof v === 'string'\n\t\t\t\t? truncate(v, opts.fieldTruncate, opts.redactions)\n\t\t\t\t: typeof v === 'number' || typeof v === 'boolean'\n\t\t\t\t\t? String(v)\n\t\t\t\t\t: safeJson(v, opts.fieldTruncate, opts.redactions);\n\t\tlines.push(`  ${key}: ${rendered}`);\n\t}\n\n\tif (value.cause !== undefined && value.cause !== null) {\n\t\tconst rendered = formatAny(value.cause, opts, visited, depth + 1);\n\t\tif (rendered.trim().length > 0 && rendered.trim() !== header.trim()) {\n\t\t\tlines.push('  caused by:');\n\t\t\tlines.push(indent(rendered, '    '));\n\t\t}\n\t}\n\treturn lines.join('\\n');\n};\n\nconst safeJson = (\n\tvalue: unknown,\n\tlimit: number,\n\tredactions: ReadonlyArray<RedactionRule>,\n): string => {\n\ttry {\n\t\treturn truncate(JSON.stringify(redactValue(value, redactions)), limit, redactions);\n\t} catch {\n\t\treturn '[unserializable]';\n\t}\n};\n"],"mappings":"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"}
+{"version":3,"file":"cascade-formatter.mjs","names":[],"sources":["../../../../src/substrate/runtime/observability/cascade-formatter.ts"],"sourcesContent":["// L0 cascade formatter.\n//\n// Architecture § Substrate violations § \"C2 — relocate cause walker\n// from the renderer\". The cascade formatter walks an Effect `Cause`\n// and returns a stringified cascade of taxonomy-aware lines. Called\n// from CLI, TUI, prune — anywhere a failure surfaces.\n//\n// Hard rules:\n//   - PURE. No IO, no Effect, no clocks. Input → string.\n//   - No service names: the formatter inspects `_tag` strings and\n//     structured fields verbatim, never branches on a specific\n//     concrete plugin error class.\n//   - Pluggable per-error-class formatters via a `formatters` map\n//     keyed by `_tag`. The default formatter handles tagged errors,\n//     plain `Error`, defects, and Interrupts.\n//\n// Output shape:\n//\n//   <Tag> (<phase?>): <message>\n//     exitCode: <n>\n//     stderr: <text…[truncated]>\n//     <field>: <value>\n//     caused by:\n//       <recursive render, indented by 2 spaces>\n//\n// Multi-`Fail` causes (parallel failures) render with a `--- (also)`\n// separator. Defects (`Die`) render with `DEFECT (<tag>?)` prefix so\n// the operator can tell programmer errors from typed failures at a\n// glance. Interrupts render as `INTERRUPT[<fiberId>]`.\n\nimport { Cause } from 'effect';\n\nimport { redactText, redactValue, type RedactionRule } from './redaction.ts';\n\n// -----------------------------------------------------------------------------\n// Plug-in formatter API\n// -----------------------------------------------------------------------------\n\n/**\n * Per-tag formatter override. Receives the tagged-error-like value\n * and the default formatter (so a plugin formatter can recurse on a\n * nested `cause` field without re-implementing the walk).\n *\n * Return `null` to fall back to the default rendering.\n *\n * Architecture: the formatter registry is keyed by `_tag` string —\n * the substrate never imports a concrete plugin error class. Plugins\n * register their custom renderer via the supervisor harvest loop over\n * `errorContributions` (see `substrate/plugin.ts:PluginErrorContribution`).\n */\nexport type TagFormatter = (\n\tvalue: TaggedErrorLike,\n\trecurse: (inner: unknown) => string,\n) => string | null;\n\n/** Per-tag formatter map. */\nexport type FormatterRegistry = ReadonlyMap<string, TagFormatter>;\n\n/** Empty registry — the formatter falls back to the default\n *  rendering for every value. */\nexport const emptyFormatterRegistry: FormatterRegistry = new Map();\n\n// -----------------------------------------------------------------------------\n// Render budget\n// -----------------------------------------------------------------------------\n\nconst DEFAULT_FIELD_TRUNCATE = 8192;\nconst DEFAULT_MAX_DEPTH = 12;\n\nexport interface FormatOptions {\n\t/** Per-tag override registry. Defaults to the empty registry. */\n\treadonly formatters?: FormatterRegistry;\n\t/** Truncate individual fields (stderr/stdout/detail) past this\n\t *  length. Default 8 KiB. */\n\treadonly fieldTruncate?: number;\n\t/** Hard recursion cap. Cyclic graphs are detected separately by\n\t *  visit-set; this guards against pathological cause chains.\n\t *  Default 12. */\n\treadonly maxDepth?: number;\n\t/** Optional redaction rules applied before rendering string fields. */\n\treadonly redactions?: ReadonlyArray<RedactionRule>;\n}\n\n// -----------------------------------------------------------------------------\n// Type guards (structural — no imports of concrete classes)\n// -----------------------------------------------------------------------------\n\n/** Shape of a `Schema.TaggedError` / `Data.TaggedError` instance.\n *  The cascade formatter never imports a concrete class — it dispatches\n *  on `_tag`. */\nexport interface TaggedErrorLike {\n\treadonly _tag: string;\n\treadonly message?: unknown;\n\treadonly cause?: unknown;\n\treadonly phase?: unknown;\n\treadonly stderr?: unknown;\n\treadonly stdout?: unknown;\n\treadonly exitCode?: unknown;\n\treadonly [key: string]: unknown;\n\treadonly detail?: unknown;\n\treadonly op?: unknown;\n}\n\nexport const isTaggedError = (value: unknown): value is TaggedErrorLike =>\n\ttypeof value === 'object' &&\n\tvalue !== null &&\n\ttypeof (value as { _tag?: unknown })._tag === 'string';\n\n// -----------------------------------------------------------------------------\n// Public entry points\n// -----------------------------------------------------------------------------\n\n/**\n * Format an Effect `Cause<E>` as a multi-line cascade string. Pure.\n *\n * Multiple `Fail` reasons render as separate blocks joined by\n * `--- (also)` so parallel failures are visible. Defects render with\n * a `DEFECT` prefix. Interrupts render with `INTERRUPT[<fiberId>]`.\n *\n * Cyclic `cause` chains are broken with `…[cycle]`.\n */\nexport const formatCause = <E>(cause: Cause.Cause<E>, options?: FormatOptions): string => {\n\tconst opts: Required<FormatOptions> = {\n\t\tformatters: options?.formatters ?? emptyFormatterRegistry,\n\t\tfieldTruncate: options?.fieldTruncate ?? DEFAULT_FIELD_TRUNCATE,\n\t\tmaxDepth: options?.maxDepth ?? DEFAULT_MAX_DEPTH,\n\t\tredactions: options?.redactions ?? [],\n\t};\n\tconst visited = new WeakSet<object>();\n\tif (cause.reasons.length === 0) return '(empty cause)';\n\tconst rendered = cause.reasons.map((reason) => formatReason(reason, opts, visited, 0));\n\treturn rendered.join('\\n--- (also)\\n');\n};\n\n/**\n * Format an arbitrary value (a `Cause`, a tagged error, a plain\n * `Error`, or anything else) using the cascade rules. Pure.\n *\n * The pretty-error renderer (`pretty-error.ts`) is a thin wrapper\n * over this — it just sets the IO conventions (where to write,\n * what to truncate per-context). The formatting logic lives here.\n */\nexport const formatValue = (value: unknown, options?: FormatOptions): string => {\n\tconst opts: Required<FormatOptions> = {\n\t\tformatters: options?.formatters ?? emptyFormatterRegistry,\n\t\tfieldTruncate: options?.fieldTruncate ?? DEFAULT_FIELD_TRUNCATE,\n\t\tmaxDepth: options?.maxDepth ?? DEFAULT_MAX_DEPTH,\n\t\tredactions: options?.redactions ?? [],\n\t};\n\treturn formatAny(value, opts, new WeakSet(), 0);\n};\n\n// -----------------------------------------------------------------------------\n// Internals\n// -----------------------------------------------------------------------------\n\nconst truncate = (s: string, limit: number, redactions: ReadonlyArray<RedactionRule>): string => {\n\tconst redacted = redactText(s, redactions);\n\treturn redacted.length > limit ? `${redacted.slice(0, limit)}…[truncated]` : redacted;\n};\n\nconst indent = (s: string, prefix: string): string =>\n\ts\n\t\t.split('\\n')\n\t\t.map((line) => `${prefix}${line}`)\n\t\t.join('\\n');\n\nconst formatReason = (\n\treason: Cause.Reason<unknown>,\n\topts: Required<FormatOptions>,\n\tvisited: WeakSet<object>,\n\tdepth: number,\n): string => {\n\tif (Cause.isFailReason(reason)) {\n\t\treturn formatAny(reason.error, opts, visited, depth);\n\t}\n\tif (Cause.isDieReason(reason)) {\n\t\tconst inner = formatAny(reason.defect, opts, visited, depth);\n\t\treturn `DEFECT:\\n${indent(inner, '  ')}`;\n\t}\n\t// Cause.isInterruptReason(reason)\n\treturn `INTERRUPT[${reason.fiberId ?? 'unknown'}]`;\n};\n\nconst formatAny = (\n\tvalue: unknown,\n\topts: Required<FormatOptions>,\n\tvisited: WeakSet<object>,\n\tdepth: number,\n): string => {\n\tif (value === undefined || value === null) return '';\n\tif (depth > opts.maxDepth) return '…[max depth]';\n\tif (typeof value === 'object') {\n\t\tif (visited.has(value as object)) return '…[cycle]';\n\t\tvisited.add(value as object);\n\t}\n\tif (Cause.isCause(value)) {\n\t\tif (value.reasons.length === 0) return '(empty cause)';\n\t\treturn value.reasons.map((r) => formatReason(r, opts, visited, depth)).join('\\n--- (also)\\n');\n\t}\n\tif (isTaggedError(value)) {\n\t\treturn formatTagged(value, opts, visited, depth);\n\t}\n\tif (value instanceof Error) {\n\t\tconst header = `${value.name}: ${value.message}`;\n\t\tif (value.stack && value.stack !== header) return value.stack;\n\t\treturn header;\n\t}\n\tif (typeof value === 'string') return redactText(value, opts.redactions);\n\ttry {\n\t\treturn JSON.stringify(redactValue(value, opts.redactions));\n\t} catch {\n\t\treturn String(value);\n\t}\n};\n\nconst formatTagged = (\n\tvalue: TaggedErrorLike,\n\topts: Required<FormatOptions>,\n\tvisited: WeakSet<object>,\n\tdepth: number,\n): string => {\n\tconst override = opts.formatters.get(value._tag);\n\tif (override) {\n\t\tconst result = override(value, (inner) => formatAny(inner, opts, visited, depth + 1));\n\t\tif (result !== null) return result;\n\t}\n\n\tconst qualifier =\n\t\ttypeof value.phase === 'string'\n\t\t\t? `(${value.phase})`\n\t\t\t: typeof value.op === 'string'\n\t\t\t\t? `(${value.op})`\n\t\t\t\t: '';\n\tconst message =\n\t\ttypeof value.message === 'string' ? redactText(value.message, opts.redactions) : '';\n\tconst header = qualifier ? `${value._tag} ${qualifier}: ${message}` : `${value._tag}: ${message}`;\n\n\tconst lines: Array<string> = [header];\n\tif (typeof value.exitCode === 'number') lines.push(`  exitCode: ${value.exitCode}`);\n\tif (typeof value.stderr === 'string' && value.stderr.trim().length > 0) {\n\t\tlines.push(`  stderr: ${truncate(value.stderr.trim(), opts.fieldTruncate, opts.redactions)}`);\n\t}\n\tif (typeof value.stdout === 'string' && value.stdout.trim().length > 0) {\n\t\tlines.push(`  stdout: ${truncate(value.stdout.trim(), opts.fieldTruncate, opts.redactions)}`);\n\t}\n\tif (typeof value.detail === 'string' && value.detail.trim().length > 0) {\n\t\tlines.push(`  detail: ${truncate(value.detail.trim(), opts.fieldTruncate, opts.redactions)}`);\n\t}\n\n\t// Surface any extra plain-data fields the tagged error carries.\n\t// We skip the conventional ones already rendered above plus `_tag`,\n\t// `cause`. This makes the formatter discover-by-shape: a plugin\n\t// adding `path` or `kind` to its error gets it rendered for free.\n\tconst conventional = new Set([\n\t\t'_tag',\n\t\t'message',\n\t\t'cause',\n\t\t'phase',\n\t\t'stderr',\n\t\t'stdout',\n\t\t'exitCode',\n\t\t'detail',\n\t\t'op',\n\t]);\n\tfor (const key of Object.keys(value)) {\n\t\tif (conventional.has(key)) continue;\n\t\tconst v = (value as unknown as Record<string, unknown>)[key];\n\t\tif (v === undefined || v === null) continue;\n\t\tconst rendered =\n\t\t\ttypeof v === 'string'\n\t\t\t\t? truncate(v, opts.fieldTruncate, opts.redactions)\n\t\t\t\t: typeof v === 'number' || typeof v === 'boolean'\n\t\t\t\t\t? String(v)\n\t\t\t\t\t: safeJson(v, opts.fieldTruncate, opts.redactions);\n\t\tlines.push(`  ${key}: ${rendered}`);\n\t}\n\n\tif (value.cause !== undefined && value.cause !== null) {\n\t\tconst rendered = formatAny(value.cause, opts, visited, depth + 1);\n\t\tif (rendered.trim().length > 0 && rendered.trim() !== header.trim()) {\n\t\t\tlines.push('  caused by:');\n\t\t\tlines.push(indent(rendered, '    '));\n\t\t}\n\t}\n\treturn lines.join('\\n');\n};\n\nconst safeJson = (\n\tvalue: unknown,\n\tlimit: number,\n\tredactions: ReadonlyArray<RedactionRule>,\n): string => {\n\ttry {\n\t\treturn truncate(JSON.stringify(redactValue(value, redactions)), limit, redactions);\n\t} catch {\n\t\treturn '[unserializable]';\n\t}\n};\n"],"mappings":"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"}

package/dist/substrate/runtime/observability/formatter-registry.mjs

@@ -1,58 +1,41 @@
+import { makeScopedMultimap } from "../scoped-multimap/service.mjs";
+import "../scoped-multimap/index.mjs";
 import { emptyFormatterRegistry } from "./cascade-formatter.mjs";
-import { Context, Effect, Layer, Ref } from "effect";
+import { Context, Effect, Layer } from "effect";
 //#region src/substrate/runtime/observability/formatter-registry.ts
-var FormatterRegistryService = class extends Context.Service()("@devstack-rewrite/substrate/FormatterRegistry") {};
+var FormatterRegistryService = class extends Context.Service()("@devstack/substrate/FormatterRegistry") {};
 /** Layer constructing the per-stack formatter registry. Stateful;
-*  the substrate provides one per supervisor scope. */
+*  the substrate provides one per supervisor scope.
+*
+*  Storage is the shared scoped-multimap keyed by tag. The per-entry
+*  value is the (optional) formatter — the registry may track a tag
+*  with NO formatter (default rendering is enough), so `null` is a
+*  legitimate value and the seq still tracks the registration. */
 const layerFormatterRegistry = Layer.effect(FormatterRegistryService, Effect.gen(function* () {
-	const state = yield* Ref.make(/* @__PURE__ */ new Map());
-	const seqRef = yield* Ref.make(0);
+	const store = yield* makeScopedMultimap();
 	const register = (contribution) => Effect.gen(function* () {
-		const baseSeq = yield* Ref.updateAndGet(seqRef, (n) => n + 1);
 		const fmt = contribution.formatter !== void 0 ? (value, recurse) => contribution.formatter(value, recurse) : null;
-		const newEntries = contribution.errorTags.map((tag) => ({
-			tag,
-			formatter: fmt,
-			seq: baseSeq
-		}));
-		yield* Ref.update(state, (current) => {
-			const next = new Map(current);
-			for (const e of newEntries) {
-				const existing = next.get(e.tag) ?? [];
-				next.set(e.tag, [...existing, e]);
-			}
-			return next;
-		});
-		yield* Effect.addFinalizer((_exit) => Ref.update(state, (current) => {
-			const next = new Map(current);
-			for (const e of newEntries) {
-				const existing = next.get(e.tag);
-				if (!existing) continue;
-				const filtered = existing.filter((x) => x.seq !== e.seq);
-				if (filtered.length === 0) next.delete(e.tag);
-				else next.set(e.tag, filtered);
-			}
-			return next;
-		}));
+		yield* store.register(contribution.errorTags.map((tag) => ({
+			key: tag,
+			value: fmt
+		})));
 	}).pipe(Effect.withSpan("substrate.formatterRegistry.register"));
 	const snapshot = Effect.gen(function* () {
-		const current = yield* Ref.get(state);
+		const current = yield* store.snapshot;
 		if (current.size === 0) return emptyFormatterRegistry;
 		const out = /* @__PURE__ */ new Map();
 		for (const [tag, entries] of current) {
 			let chosen = null;
 			let chosenSeq = -1;
-			for (const e of entries) if (e.formatter !== null && e.seq > chosenSeq) {
-				chosen = e.formatter;
+			for (const e of entries) if (e.value !== null && e.seq > chosenSeq) {
+				chosen = e.value;
 				chosenSeq = e.seq;
 			}
 			if (chosen !== null) out.set(tag, chosen);
 		}
 		return out;
 	});
-	const tags = Effect.gen(function* () {
-		return [...(yield* Ref.get(state)).keys()];
-	});
+	const tags = store.keys;
 	return FormatterRegistryService.of({
 		register,
 		snapshot,