@playfast/reform 1.0.1 → 1.2.0

package/src/runtime/appRuntime.ts

@@ -1,140 +1,417 @@
-import { Cause, Context, Effect, Exit, Layer, ManagedRuntime, Option, Scope } from 'effect'
+import { Cause, Context, Effect, Exit, Fiber, Layer, ManagedRuntime, Option, Scope } from 'effect'
+import type {
+  CompositionActivation,
+  CompositionId,
+  RequiredSlotIdentities,
+} from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import {
+  type AnyFeatureBinding,
+  type CapturedFeatureBinding,
+  type FeatureBinding,
+  FeatureInput,
+  type FeatureRequirement,
+} from '../feature/feature'
+import type {
+  AnyFeatureGraphSummary,
+  FeatureSummaryCompositionIdentity,
+  FeatureSummaryContract,
+  FeatureSummaryInput,
+  FeatureSummaryMountProps,
+  FeatureSummaryName,
+  FeatureSummaryOpenServices,
+  FeatureSummaryUsesInput,
+} from '../graph/closure'
 import { FeatureLoadFailed, forceSync } from '../internal/errors'
-import { type FeatureBinding, mountFeature } from '../feature/feature'
 import { type Node } from '../ui/node'
-import { type MountedServices, type Scene, sceneInstrumentation } from '../scene/scene'
-import { publish, type Priority, type Tagged } from './bus'
+import { type AnyScene, type CapturedScene, type Scene, sceneInstrumentation } from '../scene/scene'
+import { Bus, publish, type Priority, type Tagged } from './bus'
+import { CurrentEventBudget, type ReformOptions, resolveEventBudget } from './eventBudget'
 import { type Instrumentation } from './instrumentation'
+import { EngineRequirements, type EngineServices } from './loop'
 
-// The renderer-neutral scene runtime: one `ManagedRuntime` over a scene's closed
-// layers, with the read/render/dispatch/feature-mount surface every host shares.
-// `@playfast/reform-react` builds its React lifecycle (StrictMode-deferred
-// dispose, providers) ON TOP of this; headless tests, proofs, and drive scripts
-// consume it directly — the "testing runtime" with no React and no harness.
+export const UnspecifiedRuntimeServicesTypeId: unique symbol = Symbol.for(
+  'reform/UnspecifiedRuntimeServices',
+)
+export type UnspecifiedRuntimeServicesTypeId = typeof UnspecifiedRuntimeServicesTypeId
+export interface UnspecifiedRuntimeServices {
+  readonly [UnspecifiedRuntimeServicesTypeId]: UnspecifiedRuntimeServicesTypeId
+}
+
+export type FeatureMountHandlersExternalApi<UsesInput extends boolean, Input, Services> = {
+  readonly onLive: (runtime: RuntimeHandle<Services>) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+} & (UsesInput extends true ? { readonly props: Input } : { readonly props?: never })
+
+export type FeatureMountHandlers<
+  UsesInput extends boolean,
+  Input,
+  Services,
+> = FeatureMountHandlersExternalApi<UsesInput, Input, Services>
 
-/** The lazy-feature lifecycle callbacks a host hands to `mountFeature`. */
-export interface FeatureMountHandlers {
-  readonly onLive: (runtime: RuntimeHandle) => void
+export type RuntimeFeatureAvailability<Services, OpenServices> = [
+  EngineServices | OpenServices,
+] extends [Services]
+  ? object
+  : {
+      readonly missingFeatureServices: Exclude<EngineServices | OpenServices, Services>
+    }
+
+export interface AnyFeatureMountHandlers {
+  readonly props: unknown
+  readonly onLive: <Services>(runtime: RuntimeHandle<Services>) => void
   readonly onFailed: (error: FeatureLoadFailed) => void
 }
 
-/**
- * The capabilities a host needs from a built reform runtime — what `Compose`
- * (React) and the proof facade depend on. A feature mount yields a child handle
- * over the feature's merged context, sharing the parent's render/dispatch.
- */
-export interface RuntimeHandle {
-  /**
-   * Resolve any reform DI tag (a composition's mounted logic, a slot's wired
-   * child) from the app context. The mounted runtime provides every reform
-   * service, so this never fails for tags from the same app.
-   */
-  read<A>(tag: Context.Tag<A, A>): A
-  /** Run a fully-provided, synchronous render to its node (D2). */
+export interface CapturedFeatureMountHandlers<
+  Props,
+  HostServices,
+  FeatureServices,
+  C extends UiContract,
+  N extends string,
+  Identity,
+> {
+  readonly props: Props
+  readonly onLive: (
+    runtime: RuntimeHandle<
+      HostServices | FeatureServices | CompositionId<N, Identity, RequiredSlotIdentities<C>>
+    >,
+  ) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+}
+
+const isObjectLike = (candidate: unknown): candidate is object =>
+  (typeof candidate === 'object' || typeof candidate === 'function') && candidate !== null
+
+const isContextTag = (candidate: unknown): candidate is Context.Tag<unknown, unknown> =>
+  isObjectLike(candidate) &&
+  Context.TagTypeId in candidate &&
+  'key' in candidate &&
+  typeof candidate.key === 'string'
+
+const isUnknownArray = (candidate: unknown): candidate is ReadonlyArray<unknown> =>
+  Array.isArray(candidate)
+
+const requirementAvailable = <Services>(
+  context: Context.Context<Services>,
+  requirement: unknown,
+): boolean => {
+  if (isContextTag(requirement)) {
+    return Option.isSome(Context.getOption(context, requirement))
+  }
+  if (!isObjectLike(requirement)) {
+    return false
+  }
+  if ('store' in requirement) {
+    return requirementAvailable(context, requirement.store)
+  }
+  if ('members' in requirement && isUnknownArray(requirement.members)) {
+    return requirement.members.every((member) => requirementAvailable(context, member))
+  }
+  return false
+}
+
+const hasFeatureRequirements = <
+  Services,
+  OpenServices,
+  const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+>(
+  context: Context.Context<Services>,
+  requires: DirectRequires,
+): context is Context.Context<Services | EngineServices | OpenServices> =>
+  EngineRequirements.every((tag) => requirementAvailable(context, tag)) &&
+  requires.every((requirement) => requirementAvailable(context, requirement))
+
+const featureMountFailure = (message: string): FeatureLoadFailed =>
+  new FeatureLoadFailed({ cause: message })
+
+export interface RuntimeHandle<Services = UnspecifiedRuntimeServices> {
+  read<Identifier extends Services, Service>(tag: Context.Tag<Identifier, Service>): Service
+  readOption<Identifier, Service>(tag: Context.Tag<Identifier, Service>): Option.Option<Service>
   runRender(effect: Effect.Effect<Node, never, never>): Node
-  /** Dispatch a runtime/boot event onto the bus. */
   dispatch(priority: Priority, event: Tagged): void
-  /**
-   * Mount a feature against this runtime: load its module (lazy = dynamic import),
-   * build its `.live` layer on a fresh scope sharing this runtime's engine, and
-   * call `onLive` with a child runtime that reads the feature's composition/stores
-   * (and the shared services), or `onFailed` with a typed `FeatureLoadFailed`.
-   * Returns a disposer that closes the feature's scope — stopping its fibers and
-   * reclaiming its reducers/stores.
-   */
-  mountFeature(binding: FeatureBinding, handlers: FeatureMountHandlers): () => void
-  /**
-   * The scene's profiling hooks (`noopInstrumentation` unless `profileScene`d).
-   * On the handle (not only the app runtime) because render spans are recorded
-   * by whatever holds the handle — React `Compose`, the proof engine — and a
-   * feature's child handle must record into the same profiler as its parent.
-   */
+  mountScoped(activation: CompositionActivation): () => void
+  mountFeature<
+    Summary extends AnyFeatureGraphSummary,
+    ROut,
+    const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  >(
+    binding: [EngineServices | FeatureSummaryOpenServices<Summary>] extends [Services]
+      ? FeatureBinding<Summary, ROut, DirectRequires>
+      : never,
+    handlers: FeatureMountHandlers<
+      FeatureSummaryUsesInput<Summary>,
+      FeatureSummaryInput<Summary>,
+      Services | ROut
+    >,
+  ): () => void
+  mountCapturedFeature<
+    Summary extends AnyFeatureGraphSummary,
+    ROut,
+    const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  >(
+    binding: CapturedFeatureBinding<Summary, ROut, DirectRequires> &
+      RuntimeFeatureAvailability<Services, FeatureSummaryOpenServices<Summary>>,
+    handlers: CapturedFeatureMountHandlers<
+      FeatureSummaryMountProps<Summary>,
+      Services,
+      ROut,
+      FeatureSummaryContract<Summary>,
+      FeatureSummaryName<Summary>,
+      FeatureSummaryCompositionIdentity<Summary>
+    >,
+  ): () => void
+  mountAnyFeature(binding: AnyFeatureBinding, handlers: AnyFeatureMountHandlers): () => void
   readonly instrumentation: Instrumentation
 }
 
-/** A built scene runtime: the handle plus its boot/dispose lifecycle. */
-export interface AppRuntime extends RuntimeHandle {
-  /** Dispatch the scene's boot events, once — later calls are no-ops. */
+export interface AppRuntime<Services = UnspecifiedRuntimeServices> extends RuntimeHandle<Services> {
   boot(): void
-  /** Interrupt the runtime and latch the handle inert. Immediate and idempotent. */
   dispose(): void
-  /** True once disposed, so a host can rebuild rather than reuse a dead runtime. */
   isDisposed(): boolean
 }
 
-/**
- * Build the concrete runtime over a `ManagedRuntime` made from a scene's closed
- * layers. The mounted runtime provides every reform tag, so reading any one
- * needs no further context; we erase the requirement the generic tag carries.
- */
-export const makeAppRuntime = (scene: Scene): AppRuntime => {
+const makeCapturedAppRuntime = <
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+  options: ReformOptions = {},
+): AppRuntime<Services | CompositionId<N, Identity, RequiredSlotIdentities<C>>> => {
   const instrumentation = sceneInstrumentation(scene)
-  // A scene always provides at least one layer; merge them into the app layer.
-  const layer = scene.provide.reduce((accLayer, nextLayer) => Layer.merge(accLayer, nextLayer))
+  const provide = scene.provide.map(Layer.locally(CurrentEventBudget, resolveEventBudget(options)))
+  const layer = provide.reduce((accLayer, nextLayer) => Layer.merge(accLayer, nextLayer))
   const runtime = ManagedRuntime.make(layer)
-  // The full app context (all services), captured once. A feature's `.live` layer
-  // is built against this so it shares the one engine (bus + registries). Typed as
-  // the host's `MountedServices` subset; at runtime it carries every service.
-  const rootContext = forceSync(() => runtime.runSync(Effect.context<MountedServices>()))
-
-  // Past actual dispose the `ManagedRuntime` is interrupted and every `runSync` /
-  // `runFork` against it throws `ManagedRuntime disposed`. A host can still render
-  // a tearing-down tree, and forked fibers (a RemoteState load, a boot dispatch)
-  // outlive the host cleanup — so the runtime is made inert past dispose instead
-  // of throwing into a render. A `const` latch mutated in place.
+  const capturedContext = forceSync(() => runtime.runSync(Effect.context<Services>()))
+  const rootCompositionService = Option.getOrThrow(
+    Context.getOption(capturedContext, scene.composition.tag),
+  )
+  // Re-add the exact tag so the captured context retains the root's nominal identity.
+  const rootContext = Context.add(capturedContext, scene.composition.tag, rootCompositionService)
+  const rootBus = Context.getOption(rootContext, Bus)
+
+  // Hosts can still render tearing-down trees after the managed runtime is disposed.
   const status = { disposed: false, booted: false }
+  const activationDisposers = new Set<() => void>()
 
-  // A render is a self-contained `Effect<Node, never, never>` (no service needs),
-  // so once the managed runtime is gone it still runs on the default runtime —
-  // yielding a real node from the current store values, never a throw mid-render.
+  // A closed render Effect remains safe on the default runtime after disposal.
   const runRender = (effect: Effect.Effect<Node, never, never>): Node =>
     status.disposed ? Effect.runSync(effect) : runtime.runSync(effect)
 
-  // A dispatch past dispose has no live bus to reach; drop it.
   const dispatch = (priority: Priority, event: Tagged): void => {
-    if (status.disposed) {
+    if (status.disposed || Option.isNone(rootBus)) {
       return
     }
-    runtime.runFork(publish(priority, event))
+    runtime.runFork(publish(priority, event).pipe(Effect.provideService(Bus, rootBus.value)))
   }
 
-  // A child runtime over a feature's merged context (feature services + the shared
-  // engine). Reads resolve from that context; renders/dispatch share the
-  // inert-past-dispose helpers above.
-  const makeChildRuntime = (context: Context.Context<unknown>): RuntimeHandle => ({
-    read: <A>(tag: Context.Tag<A, A>): A => Context.unsafeGet(context, tag),
+  const mountScoped = (activation: CompositionActivation): (() => void) => {
+    if (status.disposed) {
+      return () => {}
+    }
+    const scope = Effect.runSync(Scope.make())
+    const liveness = { active: true }
+    const fiber = runtime.runFork(
+      Layer.build(activation).pipe(Effect.provideService(Scope.Scope, scope)),
+    )
+    const dispose = (): void => {
+      if (!liveness.active) {
+        return
+      }
+      liveness.active = false
+      fiber.unsafeInterruptAsFork(fiber.id())
+      const close = Fiber.await(fiber).pipe(
+        Effect.zipRight(Scope.close(scope, Exit.succeed(undefined))),
+        Effect.ensuring(Effect.sync(() => activationDisposers.delete(dispose))),
+      )
+      Effect.runFork(close)
+    }
+    activationDisposers.add(dispose)
+    return dispose
+  }
+
+  const makeChildRuntime = <ChildServices>(
+    context: Context.Context<ChildServices>,
+  ): RuntimeHandle<ChildServices> => ({
+    read: <Identifier extends ChildServices, Service>(
+      tag: Context.Tag<Identifier, Service>,
+    ): Service => Context.get(context, tag),
+    readOption: <Identifier, Service>(
+      tag: Context.Tag<Identifier, Service>,
+    ): Option.Option<Service> => Context.getOption(context, tag),
     runRender,
     dispatch,
-    mountFeature: (binding, handlers) => mountFeatureOnto(binding, handlers),
+    mountScoped,
+    mountFeature: (binding, handlers) => mountFeatureOnto(context, binding, handlers),
+    mountCapturedFeature: (binding, handlers) =>
+      mountCapturedFeatureOnto(context, binding, handlers),
+    mountAnyFeature: (binding, handlers) => mountAnyFeatureOnto(context, binding, handlers),
     instrumentation,
   })
 
-  const mountFeatureOnto = (
-    binding: FeatureBinding,
-    handlers: FeatureMountHandlers,
+  const mountFeatureOnto = <
+    HostServices,
+    Summary extends AnyFeatureGraphSummary,
+    ROut,
+    const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  >(
+    hostContext: Context.Context<HostServices>,
+    binding: FeatureBinding<Summary, ROut, DirectRequires>,
+    handlers: FeatureMountHandlers<
+      FeatureSummaryUsesInput<Summary>,
+      FeatureSummaryInput<Summary>,
+      HostServices | ROut
+    >,
+  ): (() => void) => {
+    if (status.disposed) {
+      return () => {}
+    }
+    const scope = Effect.runSync(Scope.make())
+    const mount = Effect.flatMap(binding.load, (loaded) => {
+      if (
+        !hasFeatureRequirements<HostServices, FeatureSummaryOpenServices<Summary>, DirectRequires>(
+          hostContext,
+          loaded.requires,
+        )
+      ) {
+        return Effect.fail(
+          featureMountFailure(
+            `Feature ${binding.manifest.name} requires services missing from the host runtime`,
+          ),
+        )
+      }
+      return Effect.gen(function* () {
+        const bus = Context.get(hostContext, Bus)
+        const featureContext = Context.add(hostContext, FeatureInput, handlers.props)
+        const context = yield* Layer.build(
+          Layer.provide(loaded.layer, Layer.succeedContext(featureContext)),
+        )
+        yield* Effect.forEach(binding.boot, (event) => publish('High', event), {
+          discard: true,
+        }).pipe(Effect.provideService(Bus, bus))
+        const merged = Context.merge(hostContext, context)
+        yield* Effect.sync(() => handlers.onLive(makeChildRuntime<HostServices | ROut>(merged)))
+      })
+    })
+    const fiber = runtime.runFork(
+      mount.pipe(
+        Effect.provideService(Scope.Scope, scope),
+        Effect.matchCause({
+          onFailure: (cause) => {
+            // Disposer interruption is cancellation, not a failed feature.
+            if (!Cause.isInterruptedOnly(cause)) {
+              handlers.onFailed(
+                Option.getOrElse(
+                  Cause.failureOption(cause),
+                  () => new FeatureLoadFailed({ cause }),
+                ),
+              )
+            }
+          },
+          onSuccess: () => undefined,
+        }),
+      ),
+    )
+    return () => {
+      // Interrupt first, then await finalizer registration before closing the scope.
+      fiber.unsafeInterruptAsFork(fiber.id())
+      const close = Fiber.await(fiber).pipe(
+        Effect.zipRight(Scope.close(scope, Exit.succeed(undefined))),
+      )
+      if (status.disposed) {
+        Effect.runFork(close)
+      } else {
+        runtime.runFork(close)
+      }
+    }
+  }
+
+  const mountCapturedFeatureOnto = <
+    HostServices,
+    Summary extends AnyFeatureGraphSummary,
+    ROut,
+    const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  >(
+    hostContext: Context.Context<HostServices>,
+    binding: CapturedFeatureBinding<Summary, ROut, DirectRequires>,
+    handlers: CapturedFeatureMountHandlers<
+      FeatureSummaryMountProps<Summary>,
+      HostServices,
+      ROut,
+      FeatureSummaryContract<Summary>,
+      FeatureSummaryName<Summary>,
+      FeatureSummaryCompositionIdentity<Summary>
+    >,
   ): (() => void) => {
-    // Don't mount onto a runtime that's already torn down — the tree is unmounting.
     if (status.disposed) {
       return () => {}
     }
     const scope = Effect.runSync(Scope.make())
-    runtime.runFork(
-      mountFeature(binding, rootContext).pipe(
+    const mount = Effect.flatMap(binding.load, (loaded) => {
+      if (
+        !hasFeatureRequirements<HostServices, FeatureSummaryOpenServices<Summary>, DirectRequires>(
+          hostContext,
+          loaded.requires,
+        )
+      ) {
+        return Effect.fail(
+          featureMountFailure(
+            `Feature ${binding.manifest.name} requires services missing from the host runtime`,
+          ),
+        )
+      }
+      const input = loaded.usesInput ? binding.parseInput(handlers.props) : Option.some(undefined)
+      return Option.match(input, {
+        onNone: () =>
+          Effect.fail(
+            featureMountFailure(`Feature ${binding.manifest.name} received invalid props`),
+          ),
+        onSome: (props) =>
+          Effect.gen(function* () {
+            const bus = Context.get(hostContext, Bus)
+            const featureContext = Context.add(hostContext, FeatureInput, props)
+            const context = yield* Layer.build(
+              Layer.provide(loaded.layer, Layer.succeedContext(featureContext)),
+            )
+            yield* Effect.forEach(binding.boot, (event) => publish('High', event), {
+              discard: true,
+            }).pipe(Effect.provideService(Bus, bus))
+            const merged = Context.merge(hostContext, context)
+            const compositionService = Option.getOrThrow(
+              Context.getOption(merged, binding.composition.tag),
+            )
+            const rooted = Context.add(merged, binding.composition.tag, compositionService)
+            yield* Effect.sync(() => handlers.onLive(makeChildRuntime(rooted)))
+          }),
+      })
+    })
+    const fiber = runtime.runFork(
+      mount.pipe(
         Effect.provideService(Scope.Scope, scope),
         Effect.matchCause({
-          onFailure: (cause) =>
-            handlers.onFailed(
-              Option.getOrElse(Cause.failureOption(cause), () => new FeatureLoadFailed({ cause })),
-            ),
-          onSuccess: (context) => handlers.onLive(makeChildRuntime(context)),
+          onFailure: (cause) => {
+            if (!Cause.isInterruptedOnly(cause)) {
+              handlers.onFailed(
+                Option.getOrElse(
+                  Cause.failureOption(cause),
+                  () => new FeatureLoadFailed({ cause }),
+                ),
+              )
+            }
+          },
+          onSuccess: () => undefined,
         }),
       ),
     )
     return () => {
-      // The scope's finalizers (reducer/store reclaim) are self-contained, so when
-      // the managed runtime is already disposed they close on the default runtime
-      // rather than throwing through a dead `runFork`.
-      const close = Scope.close(scope, Exit.succeed(undefined))
+      fiber.unsafeInterruptAsFork(fiber.id())
+      const close = Fiber.await(fiber).pipe(
+        Effect.zipRight(Scope.close(scope, Exit.succeed(undefined))),
+      )
       if (status.disposed) {
         Effect.runFork(close)
       } else {
@@ -143,14 +420,35 @@ export const makeAppRuntime = (scene: Scene): AppRuntime => {
     }
   }
 
-  const app: AppRuntime = {
-    // Read from the captured context (it carries every service), not
-    // `runtime.runSync(tag)`, so a read from a tearing-down tree can't throw
-    // `ManagedRuntime disposed` — and it drops the cast the runSync form needed.
-    read: <A>(tag: Context.Tag<A, A>): A => Context.unsafeGet(rootContext, tag),
+  const mountAnyFeatureOnto = <HostServices>(
+    hostContext: Context.Context<HostServices>,
+    binding: AnyFeatureBinding,
+    handlers: AnyFeatureMountHandlers,
+  ): (() => void) =>
+    binding.capture((exactBinding) =>
+      mountCapturedFeatureOnto(hostContext, exactBinding, {
+        props: handlers.props,
+        onLive: (childRuntime) => handlers.onLive(childRuntime),
+        onFailed: handlers.onFailed,
+      }),
+    )
+
+  type RootServices = Services | CompositionId<N, Identity, RequiredSlotIdentities<C>>
+  const app: AppRuntime<RootServices> = {
+    // Captured reads stay available while the managed runtime is tearing down.
+    read: <Identifier extends RootServices, Service>(
+      tag: Context.Tag<Identifier, Service>,
+    ): Service => Context.get(rootContext, tag),
+    readOption: <Identifier, Service>(
+      tag: Context.Tag<Identifier, Service>,
+    ): Option.Option<Service> => Context.getOption(rootContext, tag),
     runRender,
     dispatch,
-    mountFeature: (binding, handlers) => mountFeatureOnto(binding, handlers),
+    mountScoped,
+    mountFeature: (binding, handlers) => mountFeatureOnto(rootContext, binding, handlers),
+    mountCapturedFeature: (binding, handlers) =>
+      mountCapturedFeatureOnto(rootContext, binding, handlers),
+    mountAnyFeature: (binding, handlers) => mountAnyFeatureOnto(rootContext, binding, handlers),
     boot: () => {
       if (status.disposed || status.booted) {
         return
@@ -165,6 +463,7 @@ export const makeAppRuntime = (scene: Scene): AppRuntime => {
         return
       }
       status.disposed = true
+      activationDisposers.forEach((dispose) => dispose())
       void runtime.dispose()
     },
     isDisposed: () => status.disposed,
@@ -172,3 +471,22 @@ export const makeAppRuntime = (scene: Scene): AppRuntime => {
   }
   return app
 }
+
+export function makeAppRuntime<
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+  options?: ReformOptions,
+): AppRuntime<Services | CompositionId<N, Identity, RequiredSlotIdentities<C>>>
+export function makeAppRuntime<C extends UiContract, S extends ReadonlyArray<unknown>>(
+  scene: Scene<C, S>,
+  options?: ReformOptions,
+): AppRuntime<UnspecifiedRuntimeServices>
+export function makeAppRuntime(scene: AnyScene, options: ReformOptions = {}): unknown {
+  return scene.captureAny<unknown>((exactScene) => makeCapturedAppRuntime(exactScene, options))
+}

package/src/runtime/bus.ts

@@ -1,22 +1,14 @@
 import { Context, Effect, Layer, PubSub } from 'effect'
 
-/** A dispatched event: a tagged data record (`{ _tag, ...payload }`). */
 export interface Tagged {
   readonly _tag: string
 }
 
-/**
- * Re-narrow an erased `Tagged` envelope to a handler's declared event union. The
- * loop and channels only route events whose tag is in a handler's `handles`, so
- * at runtime the envelope IS one of those events; the registries store it as the
- * generic `Tagged`, and this restores the typed view. The one documented home
- * for that boundary cast, shared by `Reducer.live` and `Procedure.live`.
- */
+// Re-narrow routed Tagged to handler event union (handles set guarantees membership)
 export const narrowHandled = <E>(event: Tagged): E =>
   // oxlint-disable-next-line reform-rules/no-type-assertion -- documented runtime re-narrow of a routed Tagged envelope to its handler's declared event union (see jsdoc above)
   event as never
 
-/** UI-originated events are High; procedure-emitted follow-ups are Normal (DESIGN #46). */
 export type Priority = 'High' | 'Normal'
 
 export interface Envelope {
@@ -28,14 +20,9 @@ const BusBase: Context.TagClass<Bus, 'reform/Bus', PubSub.PubSub<Envelope>> = Co
   'reform/Bus',
 )<Bus, PubSub.PubSub<Envelope>>()
 
-/** The single dispatch bus: an unbounded PubSub fanned out to the loop and procedures. */
 export class Bus extends BusBase {}
 
-// Unbounded so `publish` never suspends: UI triggers dispatch synchronously
-// (`Runtime.runSync`, no fiber fork per event), and an event storm can't apply
-// backpressure to the UI thread. The single drain loop empties the bus every
-// microtask, so it does not accumulate. Swap to `PubSub.dropping(N)` if bounded
-// memory is preferred over never dropping (publish stays synchronous either way).
+// Unbounded so publish never suspends (UI runSync); drain empties every microtask
 export const busLayer: Layer.Layer<Bus> = Layer.scoped(Bus, PubSub.unbounded<Envelope>())
 
 export const publish = (priority: Priority, event: Tagged): Effect.Effect<void, never, Bus> =>