@playfast/reform 0.1.0 → 1.1.1

package/src/runtime/appRuntime.ts

@@ -0,0 +1,131 @@
+import { Cause, Context, Effect, Exit, Fiber, Layer, ManagedRuntime, Option, Scope } from 'effect'
+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 { CurrentEventBudget, type ReformOptions, resolveEventBudget } from './eventBudget'
+import { type Instrumentation } from './instrumentation'
+
+export interface FeatureMountHandlersExternalApi {
+  readonly props?: unknown
+  readonly onLive: (runtime: RuntimeHandle) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+}
+export type FeatureMountHandlers = FeatureMountHandlersExternalApi
+
+export interface RuntimeHandle {
+  read<Identifier, Service>(tag: Context.Tag<Identifier, Service>): Service
+  runRender(effect: Effect.Effect<Node, never, never>): Node
+  dispatch(priority: Priority, event: Tagged): void
+  mountFeature(binding: FeatureBinding, handlers: FeatureMountHandlers): () => void
+  readonly instrumentation: Instrumentation
+}
+
+export interface AppRuntime extends RuntimeHandle {
+  boot(): void
+  dispose(): void
+  isDisposed(): boolean
+}
+
+export const makeAppRuntime = (scene: Scene, options: ReformOptions = {}): AppRuntime => {
+  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 rootContext = forceSync(() => runtime.runSync(Effect.context<MountedServices>()))
+
+  // Inert past dispose: host may still render tearing-down trees; forked fibers outlive cleanup
+  const status = { disposed: false, booted: false }
+
+  // Self-contained Effect runs on default runtime after dispose (never throw mid-render)
+  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) {
+      return
+    }
+    runtime.runFork(publish(priority, event))
+  }
+
+  const makeChildRuntime = <R>(context: Context.Context<R>): RuntimeHandle => ({
+    read: <Identifier, Service>(tag: Context.Tag<Identifier, Service>): Service =>
+      Context.unsafeGet(context, tag),
+    runRender,
+    dispatch,
+    mountFeature: (binding, handlers) => mountFeatureOnto(context, binding, handlers),
+    instrumentation,
+  })
+
+  const mountFeatureOnto = <R>(
+    hostContext: Context.Context<R>,
+    binding: FeatureBinding,
+    handlers: FeatureMountHandlers,
+  ): (() => void) => {
+    if (status.disposed) {
+      return () => {}
+    }
+    const scope = Effect.runSync(Scope.make())
+    const fiber = runtime.runFork(
+      mountFeature(binding, hostContext, handlers.props).pipe(
+        Effect.provideService(Scope.Scope, scope),
+        Effect.matchCause({
+          onFailure: (cause) => {
+            // Disposer-cancelled mounts are not failures
+            if (!Cause.isInterruptedOnly(cause)) {
+              handlers.onFailed(
+                Option.getOrElse(
+                  Cause.failureOption(cause),
+                  () => new FeatureLoadFailed({ cause }),
+                ),
+              )
+            }
+          },
+          onSuccess: (context) => handlers.onLive(makeChildRuntime(context)),
+        }),
+      ),
+    )
+    return () => {
+      // Interrupt sync before scheduler: Scope.close alone does not interrupt (StrictMode)
+      fiber.unsafeInterruptAsFork(fiber.id())
+      // Await mount so mid-build finalizers register before scope reclaim; close on default runtime if disposed
+      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 app: AppRuntime = {
+    // Read captured context so tearing-down trees never hit ManagedRuntime disposed
+    read: <Identifier, Service>(tag: Context.Tag<Identifier, Service>): Service =>
+      Context.unsafeGet(rootContext, tag),
+    runRender,
+    dispatch,
+    mountFeature: (binding, handlers) => mountFeatureOnto(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
+      void runtime.dispose()
+    },
+    isDisposed: () => status.disposed,
+    instrumentation,
+  }
+  return app
+}

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> =>

package/src/runtime/eventBudget.test.ts

@@ -0,0 +1,155 @@
+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 type { EventLoopOverflow } from '../internal/errors'
+import {
+  CurrentEventBudget,
+  type EventBudget,
+  makeDefaultBudget,
+  makeTickCounter,
+  resolveEventBudget,
+} from './eventBudget'
+
+it('defaults resolve to errorAt 10_000, with the warning gated on dev', () => {
+  expect(makeDefaultBudget(true).errorAt).toBe(10_000)
+  expect(makeDefaultBudget(true).warningAt).toEqual(Option.some(500))
+  expect(makeDefaultBudget(false).warningAt).toEqual(Option.none())
+
+  const resolved = resolveEventBudget({})
+  expect(resolved.errorAt).toBe(10_000)
+
+  expect(resolveEventBudget({ maxEventsPerJsTick: { errorAt: 42 } }).errorAt).toBe(42)
+  expect(resolveEventBudget({ maxEventsPerJsTick: { warningAt: 7 } }).errorAt).toBe(10_000)
+  expect(resolveEventBudget({ maxEventsPerJsTick: { warningAt: 7 } }).warningAt).toEqual(
+    Option.some(7),
+  )
+})
+
+it('the tick counter accumulates across frames and warns exactly once', () => {
+  const budget: EventBudget = {
+    errorAt: 1_000,
+    warningAt: Option.some(5),
+    onOverflow: () => {},
+  }
+  const counter = makeTickCounter(budget)
+  expect(counter.add(3)).toEqual({ total: 3, warnNow: false })
+  expect(counter.add(3)).toEqual({ total: 6, warnNow: true })
+  expect(counter.add(3)).toEqual({ total: 9, warnNow: false })
+})
+
+it.live('crossing the soft limit logs one warning; the frame still folds', () => {
+  class Counter extends State.make('counter', S.Number) {}
+  class Bumped extends Event.make('Bumped', S.Struct({ to: S.Number })) {}
+  class BumpReducer extends Reducer.make('BumpReducer', { states: [Counter], events: [Bumped] }) {}
+  const BumpReducerLive = Reducer.live(BumpReducer, (_, event) => event.to)
+
+  const budget: EventBudget = {
+    errorAt: 1_000,
+    warningAt: Option.some(5),
+    onOverflow: () => {},
+  }
+  const TestLayer = BumpReducerLive.pipe(
+    Layer.provideMerge(Layer.mergeAll(State.live(Counter, 0), Engine)),
+    Layer.locally(CurrentEventBudget, budget),
+  )
+
+  const warnings: Array<string> = []
+  const recordingLogger = Logger.replace(
+    Logger.defaultLogger,
+    Logger.make(({ logLevel, message }) => {
+      if (logLevel._tag === 'Warning') {
+        warnings.push(String(message))
+      }
+    }),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Counter.store
+    yield* Effect.forEach(
+      Array.from({ length: 10 }, (_, index) => index + 1),
+      (to) => publish('Normal', Event.construct(Bumped, { to })),
+      { discard: true },
+    )
+    yield* Effect.sleep(Duration.millis(20))
+
+    expect(store.get()).toBe(10)
+    const budgetWarnings = warnings.filter((message) => message.includes('reform:'))
+    expect(budgetWarnings).toHaveLength(1)
+  }).pipe(Effect.provide(TestLayer), Effect.provide(recordingLogger))
+})
+
+it.live('crossing the hard limit halts the runtime with EventLoopOverflow', () => {
+  class Counter extends State.make('counter', S.Number) {}
+  class Bumped extends Event.make('Bumped', S.Struct({ to: S.Number })) {}
+  class BumpReducer extends Reducer.make('BumpReducer', { states: [Counter], events: [Bumped] }) {}
+  const BumpReducerLive = Reducer.live(BumpReducer, (_, event) => event.to)
+
+  const captured: Array<EventLoopOverflow> = []
+  const budget: EventBudget = {
+    errorAt: 50,
+    warningAt: Option.none(),
+    onOverflow: (error) => captured.push(error),
+  }
+  const TestLayer = BumpReducerLive.pipe(
+    Layer.provideMerge(Layer.mergeAll(State.live(Counter, 0), Engine)),
+    Layer.locally(CurrentEventBudget, budget),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Counter.store
+    yield* Effect.forEach(
+      Array.from({ length: 60 }, (_, index) => index + 1),
+      (to) => publish('Normal', Event.construct(Bumped, { to })),
+      { discard: true },
+    )
+    yield* Effect.sleep(Duration.millis(20))
+
+    expect(captured).toHaveLength(1)
+    expect(captured[0]?._tag).toBe('reform/EventLoopOverflow')
+    expect(captured[0]!.count).toBeGreaterThan(captured[0]!.limit)
+
+    const before = store.get()
+    yield* publish('Normal', Event.construct(Bumped, { to: 9_999 }))
+    yield* Effect.sleep(Duration.millis(20))
+    expect(store.get()).toBe(before)
+  }).pipe(
+    Effect.provide(TestLayer),
+    Logger.withMinimumLogLevel(LogLevel.None),
+  )
+})
+
+it.live('the window resets when the event loop yields — bursty traffic never trips', () => {
+  class Counter extends State.make('counter', S.Number) {}
+  class Bumped extends Event.make('Bumped', S.Struct({ to: S.Number })) {}
+  class BumpReducer extends Reducer.make('BumpReducer', { states: [Counter], events: [Bumped] }) {}
+  const BumpReducerLive = Reducer.live(BumpReducer, (_, event) => event.to)
+
+  const captured: Array<EventLoopOverflow> = []
+  const budget: EventBudget = {
+    errorAt: 50,
+    warningAt: Option.none(),
+    onOverflow: (error) => captured.push(error),
+  }
+  const TestLayer = BumpReducerLive.pipe(
+    Layer.provideMerge(Layer.mergeAll(State.live(Counter, 0), Engine)),
+    Layer.locally(CurrentEventBudget, budget),
+  )
+
+  const burst = (from: number) =>
+    Effect.forEach(
+      Array.from({ length: 40 }, (_, index) => from + index),
+      (to) => publish('Normal', Event.construct(Bumped, { to })),
+      { discard: true },
+    )
+
+  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))
+
+    expect(captured).toHaveLength(0)
+    expect(store.get()).toBe(80)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/runtime/eventBudget.ts

@@ -0,0 +1,119 @@
+import { Boolean as Bool, Effect, FiberRef, GlobalValue, MutableRef, Option } from 'effect'
+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
+  }
+}
+
+export interface EventBudget {
+  readonly errorAt: number
+  readonly warningAt: Option.Option<number>
+  readonly onOverflow: (error: EventLoopOverflow) => void
+}
+
+const rethrowOverflow = (error: EventLoopOverflow): void =>
+  queueMicrotask(() => {
+    // oxlint-disable-next-line reform-rules/no-throw -- only way to surface the halt to the host's global error handler
+    throw error
+  })
+
+const DEFAULT_ERROR_AT = 10_000
+const DEFAULT_WARNING_AT = 500
+
+export const makeDefaultBudget = (dev: boolean): EventBudget => ({
+  errorAt: DEFAULT_ERROR_AT,
+  warningAt: Bool.match(dev, {
+    onTrue: () => Option.some(DEFAULT_WARNING_AT),
+    onFalse: () => Option.none<number>(),
+  }),
+  onOverflow: rethrowOverflow,
+})
+
+export const defaultEventBudget: EventBudget = makeDefaultBudget(isDev)
+
+export const resolveEventBudget = (options: ReformOptions): EventBudget => {
+  const limits = Option.fromNullable(options.maxEventsPerJsTick)
+  return {
+    errorAt: Option.getOrElse(
+      Option.flatMapNullable(limits, (limit) => limit.errorAt),
+      () => defaultEventBudget.errorAt,
+    ),
+    warningAt: Option.orElse(
+      Option.flatMapNullable(limits, (limit) => limit.warningAt),
+      () => defaultEventBudget.warningAt,
+    ),
+    onOverflow: defaultEventBudget.onOverflow,
+  }
+}
+
+export const CurrentEventBudget: FiberRef.FiberRef<EventBudget> = GlobalValue.globalValue(
+  Symbol.for('reform/CurrentEventBudget'),
+  () => FiberRef.unsafeMake<EventBudget>(defaultEventBudget),
+)
+
+export const resolveCurrentEventBudget: Effect.Effect<EventBudget> =
+  FiberRef.get(CurrentEventBudget)
+
+export interface TickSample {
+  readonly total: number
+  readonly warnNow: boolean
+}
+
+export interface TickCounter {
+  readonly add: (eventCount: number) => TickSample
+}
+
+export const makeTickCounter = (budget: EventBudget): TickCounter => {
+  const count = MutableRef.make(0)
+  const armed = MutableRef.make(false)
+  const warned = MutableRef.make(false)
+  const reset = (): void => {
+    MutableRef.set(count, 0)
+    MutableRef.set(armed, false)
+    MutableRef.set(warned, false)
+  }
+  return {
+    add: (eventCount) => {
+      if (!MutableRef.get(armed)) {
+        MutableRef.set(armed, true)
+        // oxlint-disable-next-line reform-rules/no-set-timeout-interval -- the macrotask boundary IS the tick window; only a real timer can observe "the event loop yielded" from this synchronous hot path
+        setTimeout(reset, 0)
+      }
+      const total = MutableRef.get(count) + eventCount
+      MutableRef.set(count, total)
+      const crossed = Option.match(budget.warningAt, {
+        onNone: () => false,
+        onSome: (warningAt) => total >= warningAt,
+      })
+      const warnNow = crossed && !MutableRef.get(warned)
+      if (warnNow) {
+        MutableRef.set(warned, true)
+      }
+      return { total, warnNow }
+    },
+  }
+}
+
+export const enforceBudget: (
+  budget: EventBudget,
+  sample: TickSample,
+) => Effect.Effect<void, EventLoopOverflow> = Effect.fn('enforceBudget')(function* (
+  budget: EventBudget,
+  sample: TickSample,
+): Effect.fn.Return<void, EventLoopOverflow> {
+  if (sample.total > budget.errorAt) {
+    return yield* Effect.fail(new EventLoopOverflow({ count: sample.total, limit: budget.errorAt }))
+  }
+  if (sample.warnNow) {
+    yield* Effect.logWarning(
+      `reform: ${sample.total} events processed without yielding to the event loop — possible event feedback loop`,
+    )
+  }
+})

package/src/runtime/hardening.test.ts

@@ -1,10 +1,6 @@
 import { expect, it } from '@effect/vitest'
-import { Cause, Duration, Effect, Exit, Layer, LogLevel, Logger, Schema as S } from 'effect'
-import { Channel, Engine, Event, publish, Reducer, State } from '../index'
-
-// Robustness guards for the drain loop and registries: a buggy reducer must not
-// take down the bus, and a name clash that would silently drop a registration
-// must be rejected.
+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'
 
 it.live('a reducer that throws is isolated; the loop keeps draining', () => {
   class Counter extends State.make('counter', S.Number) {}
@@ -24,18 +20,15 @@ it.live('a reducer that throws is isolated; the loop keeps draining', () => {
   return Effect.gen(function* () {
     const store = yield* Counter.store
 
-    // A fold that throws is caught and logged — the drain fiber survives.
     yield* publish('Normal', Event.construct(Bad, {}))
     yield* Effect.sleep(Duration.millis(10))
     expect(store.get()).toBe(0)
 
-    // A later, healthy event still processes: the bus did not go deaf.
     yield* publish('Normal', Event.construct(Good, {}))
     yield* Effect.sleep(Duration.millis(10))
     expect(store.get()).toBe(1)
   }).pipe(
     Effect.provide(TestLayer),
-    // The isolated failure logs an error; silence it so the passing test is quiet.
     Logger.withMinimumLogLevel(LogLevel.None),
   )
 })
@@ -56,6 +49,19 @@ it.effect('two different channels registered under one name are rejected', () =>
   })
 })
 
+it.effect('structurally identical channel policies do not die', () => {
+  class LatestA extends Channel.make('SamePolicy', { policy: { _tag: 'latest' } }) {}
+  class LatestB extends Channel.make('SamePolicy', { policy: { _tag: 'latest' } }) {}
+  const layer = Layer.mergeAll(Channel.live(LatestA), Channel.live(LatestB)).pipe(
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const exit = yield* Effect.scoped(Layer.build(layer)).pipe(Effect.exit)
+    expect(Exit.isSuccess(exit)).toBe(true)
+  })
+})
+
 it.effect('the same channel registered twice is idempotent (shared lane)', () => {
   class Lane extends Channel.make('Lane', { policy: { _tag: 'exclusive' } }) {}
   const layer = Layer.mergeAll(Channel.live(Lane), Channel.live(Lane)).pipe(
@@ -67,3 +73,62 @@ it.effect('the same channel registered twice is idempotent (shared lane)', () =>
     expect(Exit.isSuccess(exit)).toBe(true)
   })
 })
+
+it.live('remount overlap keeps the channel alive', () => {
+  class Fired extends Event.make('OverlapFired', S.Struct({})) {}
+  class FirstLane extends Channel.make('OverlapLane', { policy: { _tag: 'latest' } }) {}
+  class SecondLane extends Channel.make('OverlapLane', { policy: { _tag: 'latest' } }) {}
+  class Work extends Procedure.make('OverlapWork', { events: [Fired], channel: SecondLane }) {}
+
+  const runs = { n: 0 }
+  const WorkLive = Procedure.live(Work, function* () {
+    runs.n += 1
+  })
+
+  return Effect.gen(function* () {
+    const channels = yield* Channels
+    const firstScope = yield* Scope.make()
+    const secondScope = yield* Scope.make()
+
+    yield* Layer.buildWithScope(Channel.live(FirstLane), firstScope)
+    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))
+    expect(runs.n).toBe(1)
+
+    yield* Scope.close(secondScope, Exit.void)
+    expect(channels.byName.has('OverlapLane')).toBe(false)
+  }).pipe(Effect.provide(Engine))
+})
+
+it.effect('last-release cleanup allows a fresh channel registration', () => {
+  class FirstLane extends Channel.make('CleanupLane', { policy: { _tag: 'merge' } }) {}
+  class SecondLane extends Channel.make('CleanupLane', { policy: { _tag: 'merge' } }) {}
+  class FreshLane extends Channel.make('CleanupLane', { policy: { _tag: 'merge' } }) {}
+
+  return Effect.gen(function* () {
+    const channels = yield* Channels
+    const firstScope = yield* Scope.make()
+    const secondScope = yield* Scope.make()
+    const freshScope = yield* Scope.make()
+
+    yield* Layer.buildWithScope(Channel.live(FirstLane), firstScope)
+    yield* Layer.buildWithScope(Channel.live(SecondLane), secondScope)
+    yield* Scope.close(firstScope, Exit.void)
+    expect(channels.byName.has('CleanupLane')).toBe(true)
+
+    yield* Scope.close(secondScope, Exit.void)
+    expect(channels.byName.has('CleanupLane')).toBe(false)
+
+    yield* Layer.buildWithScope(Channel.live(FreshLane), freshScope)
+    expect(channels.byName.has('CleanupLane')).toBe(true)
+
+    yield* Scope.close(freshScope, Exit.void)
+    expect(channels.byName.has('CleanupLane')).toBe(false)
+  }).pipe(Effect.provide(Engine))
+})