@playfast/reform 1.1.1 → 1.2.1

package/src/runtime/capturedAppRuntime.ts

@@ -0,0 +1,274 @@
+import { 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 { forceSync } from '../internal/errors'
+import { type Node } from '../ui/node'
+import { type CapturedScene, sceneInstrumentation } from '../scene/scene'
+import { Bus, publish, type Priority, type Tagged } from './bus'
+import { CurrentEventBudget, type ReformOptions, resolveEventBudget } from './eventBudget'
+import { featureMountFailure, forkFeatureMount, hasFeatureRequirements } from './featureMount'
+import type {
+  AnyFeatureMountHandlers,
+  AppRuntime,
+  CapturedFeatureMountHandlers,
+  FeatureMountHandlers,
+  RuntimeHandle,
+} from './runtimeHandle'
+
+export 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)
+  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)
+  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>()
+  const mountHost = {
+    runFork: (effect: Effect.Effect<void, never, never>) => runtime.runFork(effect),
+    isDisposed: () => status.disposed,
+  }
+
+  // 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)
+
+  const dispatch = (priority: Priority, event: Tagged): void => {
+    if (status.disposed || Option.isNone(rootBus)) {
+      return
+    }
+    runtime.runFork(publish(priority, event).pipe(Effect.provideService(Bus, rootBus.value)))
+  }
+
+  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,
+    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 = <
+    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)))
+      })
+    })
+    return forkFeatureMount(mountHost, scope, mount, handlers.onFailed)
+  }
+
+  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) => {
+    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`,
+          ),
+        )
+      }
+      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)))
+          }),
+      })
+    })
+    return forkFeatureMount(mountHost, scope, mount, handlers.onFailed)
+  }
+
+  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,
+    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
+      }
+      status.booted = true
+      Option.fromNullable(scene.boot)
+        .pipe(Option.getOrElse((): ReadonlyArray<Tagged> => []))
+        .forEach((event) => dispatch('High', event))
+    },
+    dispose: () => {
+      if (status.disposed) {
+        return
+      }
+      status.disposed = true
+      activationDisposers.forEach((dispose) => dispose())
+      void runtime.dispose()
+    },
+    isDisposed: () => status.disposed,
+    instrumentation,
+  }
+  return app
+}

package/src/runtime/eventBudget.test.ts

@@ -1,7 +1,8 @@
 import { expect, it } from '@effect/vitest'
 import { Duration, Effect, Layer, LogLevel, Logger, Option, Schema as S } from 'effect'
-import { Engine, Event, publish, Reducer, State } from '../index'
+import { Channel, Engine, Event, Procedure, publish, Reducer, State } from '../index'
 import type { EventLoopOverflow } from '../internal/errors'
+import { flush, until } from '../testkit/flight.testkit'
 import {
   CurrentEventBudget,
   type EventBudget,
@@ -70,7 +71,11 @@ it.live('crossing the soft limit logs one warning; the frame still folds', () =>
       (to) => publish('Normal', Event.construct(Bumped, { to })),
       { discard: true },
     )
-    yield* Effect.sleep(Duration.millis(20))
+    // The budget is enforced ahead of the fold, so a folded frame has been sampled.
+    yield* until(
+      () => store.get(),
+      (n) => n === 10,
+    )
 
     expect(store.get()).toBe(10)
     const budgetWarnings = warnings.filter((message) => message.includes('reform:'))
@@ -102,7 +107,12 @@ it.live('crossing the hard limit halts the runtime with EventLoopOverflow', () =
       (to) => publish('Normal', Event.construct(Bumped, { to })),
       { discard: true },
     )
-    yield* Effect.sleep(Duration.millis(20))
+    // onOverflow runs off the loop's error channel: seeing it means the drain
+    // fiber has already exited, so nothing published after can ever fold.
+    yield* until(
+      () => captured.length,
+      (n) => n >= 1,
+    )
 
     expect(captured).toHaveLength(1)
     expect(captured[0]?._tag).toBe('reform/EventLoopOverflow')
@@ -110,12 +120,9 @@ it.live('crossing the hard limit halts the runtime with EventLoopOverflow', () =
 
     const before = store.get()
     yield* publish('Normal', Event.construct(Bumped, { to: 9_999 }))
-    yield* Effect.sleep(Duration.millis(20))
+    yield* flush()
     expect(store.get()).toBe(before)
-  }).pipe(
-    Effect.provide(TestLayer),
-    Logger.withMinimumLogLevel(LogLevel.None),
-  )
+  }).pipe(Effect.provide(TestLayer), Logger.withMinimumLogLevel(LogLevel.None))
 })
 
 it.live('the window resets when the event loop yields — bursty traffic never trips', () => {
@@ -124,13 +131,26 @@ it.live('the window resets when the event loop yields — bursty traffic never t
   class BumpReducer extends Reducer.make('BumpReducer', { states: [Counter], events: [Bumped] }) {}
   const BumpReducerLive = Reducer.live(BumpReducer, (_, event) => event.to)
 
+  // The reset rides a `setTimeout(0)` armed inside the frame, and no TestClock
+  // drives it. A debounced lane is the probe: its timer starts from that same
+  // frame's offer, so its run can only land behind the reset.
+  class Yielded extends Event.make('Yielded', S.Struct({})) {}
+  class Turn extends Channel.make('Turn', {
+    policy: { _tag: 'debounce', duration: Duration.millis(1) },
+  }) {}
+  class Waited extends Procedure.make('Waited', { events: [Yielded], channel: Turn }) {}
+  const turns = { n: 0 }
+  const WaitedLive = Procedure.live(Waited, function* () {
+    turns.n += 1
+  })
+
   const captured: Array<EventLoopOverflow> = []
   const budget: EventBudget = {
     errorAt: 50,
     warningAt: Option.none(),
     onOverflow: (error) => captured.push(error),
   }
-  const TestLayer = BumpReducerLive.pipe(
+  const TestLayer = Layer.mergeAll(BumpReducerLive, Channel.live(Turn), WaitedLive).pipe(
     Layer.provideMerge(Layer.mergeAll(State.live(Counter, 0), Engine)),
     Layer.locally(CurrentEventBudget, budget),
   )
@@ -145,10 +165,17 @@ it.live('the window resets when the event loop yields — bursty traffic never t
   return Effect.gen(function* () {
     const store = yield* Counter.store
     yield* burst(1)
-    yield* Effect.sleep(Duration.millis(10))
-    yield* burst(41)
-    yield* Effect.sleep(Duration.millis(10))
+    yield* publish('Normal', Event.construct(Yielded, {}))
+    yield* until(
+      () => turns.n,
+      (n) => n >= 1,
+    )
 
+    yield* burst(41)
+    yield* until(
+      () => ({ count: store.get(), overflows: captured.length }),
+      ({ count, overflows }) => count === 80 || overflows > 0,
+    )
     expect(captured).toHaveLength(0)
     expect(store.get()).toBe(80)
   }).pipe(Effect.provide(TestLayer))

package/src/runtime/eventBudget.ts

@@ -2,16 +2,17 @@ import { Boolean as Bool, Effect, FiberRef, GlobalValue, MutableRef, Option } fr
 import { isDev } from '../internal/env'
 import { EventLoopOverflow } from '../internal/errors'
 
-export interface ReformOptions {
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional public config; absent fields fall back to the built-in defaults
-  readonly maxEventsPerJsTick?: {
-    // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional public config; absent fields fall back to the built-in defaults
-    readonly errorAt?: number
-    // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional public config; absent fields fall back to the built-in defaults
-    readonly warningAt?: number
-  }
+interface EventLimitFields {
+  readonly errorAt: number
+  readonly warningAt: number
 }
 
+interface ReformOptionFields {
+  readonly maxEventsPerJsTick: Partial<EventLimitFields>
+}
+
+export interface ReformOptions extends Partial<ReformOptionFields> {}
+
 export interface EventBudget {
   readonly errorAt: number
   readonly warningAt: Option.Option<number>

package/src/runtime/featureMount.ts

@@ -0,0 +1,94 @@
+import { Cause, Context, Effect, Exit, Fiber, Option, Scope } from 'effect'
+import type { FeatureRequirement } from '../feature/feature'
+import { FeatureLoadFailed } from '../internal/errors'
+import { EngineRequirements, type EngineServices } from './loop'
+
+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
+}
+
+export 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))
+
+export const featureMountFailure = (message: string): FeatureLoadFailed =>
+  new FeatureLoadFailed({ cause: message })
+
+export interface FeatureMountHost {
+  readonly runFork: (effect: Effect.Effect<void, never, never>) => Fiber.RuntimeFiber<void, never>
+  readonly isDisposed: () => boolean
+}
+
+/**
+ * Fork a feature mount onto the host runtime and hand back its disposer. Both
+ * the typed and captured mount paths settle failures and tear down identically.
+ */
+export const forkFeatureMount = (
+  host: FeatureMountHost,
+  scope: Scope.CloseableScope,
+  mount: Effect.Effect<void, FeatureLoadFailed, Scope.Scope>,
+  onFailed: (error: FeatureLoadFailed) => void,
+): (() => void) => {
+  const fiber = host.runFork(
+    mount.pipe(
+      Effect.provideService(Scope.Scope, scope),
+      Effect.matchCause({
+        onFailure: (cause) => {
+          // Disposer interruption is cancellation, not a failed feature.
+          if (!Cause.isInterruptedOnly(cause)) {
+            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 (host.isDisposed()) {
+      Effect.runFork(close)
+    } else {
+      host.runFork(close)
+    }
+  }
+}

package/src/runtime/hardening.test.ts

@@ -1,6 +1,8 @@
 import { expect, it } from '@effect/vitest'
-import { Cause, Duration, Effect, Exit, Layer, LogLevel, Logger, Schema as S, Scope } from 'effect'
-import { Channel, Channels, Engine, Event, Procedure, publish, Reducer, State } from '../index'
+import { Cause, Effect, Exit, Layer, LogLevel, Logger, Schema as S, Scope } from 'effect'
+import { Channel, Engine, Event, Procedure, publish, Reducer, State } from '../index'
+import { Channels } from '../channel/channel'
+import { until } from '../testkit/flight.testkit'
 
 it.live('a reducer that throws is isolated; the loop keeps draining', () => {
   class Counter extends State.make('counter', S.Number) {}
@@ -9,7 +11,9 @@ it.live('a reducer that throws is isolated; the loop keeps draining', () => {
   class GoodReducer extends Reducer.make('GoodReducer', { states: [Counter], events: [Good] }) {}
   class BadReducer extends Reducer.make('BadReducer', { states: [Counter], events: [Bad] }) {}
   const GoodLive = Reducer.live(GoodReducer, (n) => n + 1)
+  const badRuns = { n: 0 }
   const BadLive = Reducer.live(BadReducer, () => {
+    badRuns.n += 1
     throw new Error('boom')
   })
 
@@ -21,16 +25,20 @@ it.live('a reducer that throws is isolated; the loop keeps draining', () => {
     const store = yield* Counter.store
 
     yield* publish('Normal', Event.construct(Bad, {}))
-    yield* Effect.sleep(Duration.millis(10))
+    // The throwing fold ran and was isolated; its frame wrote nothing.
+    yield* until(
+      () => badRuns.n,
+      (n) => n === 1,
+    )
     expect(store.get()).toBe(0)
 
     yield* publish('Normal', Event.construct(Good, {}))
-    yield* Effect.sleep(Duration.millis(10))
+    yield* until(
+      () => store.get(),
+      (n) => n === 1,
+    )
     expect(store.get()).toBe(1)
-  }).pipe(
-    Effect.provide(TestLayer),
-    Logger.withMinimumLogLevel(LogLevel.None),
-  )
+  }).pipe(Effect.provide(TestLayer), Logger.withMinimumLogLevel(LogLevel.None))
 })
 
 it.effect('two different channels registered under one name are rejected', () => {
@@ -91,14 +99,15 @@ it.live('remount overlap keeps the channel alive', () => {
     const secondScope = yield* Scope.make()
 
     yield* Layer.buildWithScope(Channel.live(FirstLane), firstScope)
-    yield* Layer.buildWithScope(
-      Layer.mergeAll(Channel.live(SecondLane), WorkLive),
-      secondScope,
-    )
+    yield* Layer.buildWithScope(Layer.mergeAll(Channel.live(SecondLane), WorkLive), secondScope)
     yield* Scope.close(firstScope, Exit.void)
 
     yield* publish('Normal', Event.construct(Fired, {}))
-    yield* Effect.sleep(Duration.millis(20))
+    // One surviving lane under the shared name: a second would double the run.
+    yield* until(
+      () => runs.n,
+      (n) => n >= 1,
+    )
     expect(runs.n).toBe(1)
 
     yield* Scope.close(secondScope, Exit.void)