@playfast/reform 1.0.1 → 1.1.1

package/src/runtime/loop.ts

@@ -1,4 +1,4 @@
-import { Array as Arr, Chunk, Context, Effect, Layer, Option, PubSub, Queue } from 'effect'
+import { Array as Arr, Cause, Chunk, Context, Effect, Layer, Option, PubSub, Queue } from 'effect'
 import {
   Channels,
   channelsLayer,
@@ -7,37 +7,20 @@ import {
 } from '../channel/channel'
 import { notificationsLayer } from '../internal/scheduler'
 import { Bus, busLayer, type Envelope, type Tagged } from './bus'
+import { enforceBudget, makeTickCounter, resolveCurrentEventBudget } from './eventBudget'
 import { type Instrumentation, resolveInstrumentation } from './instrumentation'
 import { Queries, queriesLayer } from './queries'
 
-/**
- * A registered reducer, with its target store(s) already captured at
- * registration. `apply` is a pure synchronous write, so the loop needs no
- * state services in its own context — it just routes events to writers.
- */
 export interface ReducerEntry {
-  /** The reducer's name — used only to warn on duplicate registration. */
   readonly name: string
   readonly handles: ReadonlySet<string>
   readonly apply: (event: Tagged) => void
 }
 
-/**
- * Mutable collector the central loop drains; reducer `.live` layers register
- * here. `byTag` indexes entries by the event tags they handle, so dispatch is
- * O(matching reducers) per event rather than O(all reducers) — the difference
- * that matters once an app has hundreds of reducers.
- */
 export interface ReducerRegistry {
   readonly entries: Array<ReducerEntry>
   readonly byTag: Map<string, Array<ReducerEntry>>
   readonly register: (entry: ReducerEntry) => void
-  /**
-   * Remove a previously-registered entry. Eager reducers (built on the root scope)
-   * never call this; a lazy feature's `Reducer.live` registers on mount and
-   * unregisters on unmount (scope close), so an unmounted feature stops folding and
-   * its entry is reclaimed instead of leaking + writing to an orphaned store.
-   */
   readonly unregister: (entry: ReducerEntry) => void
 }
 
@@ -45,7 +28,6 @@ const ReducersBase: Context.TagClass<Reducers, 'reform/Reducers', ReducerRegistr
   Context.Tag('reform/Reducers')<Reducers, ReducerRegistry>()
 export class Reducers extends ReducersBase {}
 
-/** Drop a target from a `Map<string, Array>` bucket, pruning the key when it empties. */
 const dropFromBuckets = <T>(map: Map<string, Array<T>>, key: string, target: T): void => {
   const bucket = map.get(key)
   if (bucket === undefined) {
@@ -61,8 +43,6 @@ const dropFromBuckets = <T>(map: Map<string, Array<T>>, key: string, target: T):
 
 const makeReducerRegistry = (): ReducerRegistry => {
   const byTag = new Map<string, Array<ReducerEntry>>()
-  // Single live array reference, replaced immutably on register/unregister and
-  // exposed through the `entries` getter so consumers always read the current set.
   const state: { entries: Array<ReducerEntry> } = { entries: [] }
   return {
     get entries() {
@@ -87,11 +67,9 @@ const makeReducerRegistry = (): ReducerRegistry => {
   }
 }
 
-/** Read a bucket array, defaulting to empty without a falsy fallback. */
 const bucketOf = <V>(map: Map<string, Array<V>>, tag: string): Array<V> =>
   Option.getOrElse(Option.fromNullable(map.get(tag)), (): Array<V> => [])
 
-/** Run one reducer in isolation; a synchronous throw becomes a collected failure. */
 const isolateApply = (
   reducer: ReducerEntry,
   event: Tagged,
@@ -113,57 +91,47 @@ const isolateApply = (
 
 export const reducersLayer: Layer.Layer<Reducers> = Layer.sync(Reducers, makeReducerRegistry)
 
-/** High before Normal; within a priority class, dispatch order is preserved. */
+// High before Normal; partition preserves intra-priority dispatch order
 const rank = (priority: Envelope['priority']): number => (priority === 'High' ? 0 : 1)
 
-// The single drain loop: one fiber that frame-batches the bus. Each tick it
-// harvests every event dispatched in that microtask, runs all matching reducers
-// in ONE synchronous pass (so the store notifier flushes once for the batch),
-// then routes each event to the channels its procedures run on.
 const drain = Effect.gen(function* () {
   const bus = yield* Bus
   const reducers = yield* Reducers
   const { byName: channels } = yield* Channels
   const procedures = yield* Procedures
-  // Captured once at engine build; the noop instance costs nothing per frame.
   const instrumentation = yield* resolveInstrumentation
+  // One counter per engine: feature child runtimes share the app budget
+  const budget = yield* resolveCurrentEventBudget
+  const counter = makeTickCounter(budget)
   const subscription = yield* PubSub.subscribe(bus)
 
   yield* Effect.forkScoped(
     Effect.forever(
       Effect.gen(function* () {
-        // Block until the first event, then drain the rest of this tick.
         const first = yield* Queue.take(subscription)
         const rest = yield* Queue.takeAll(subscription)
         const frame = [first, ...Chunk.toArray(rest)]
 
-        // Stable priority order: High-dispatched (UI) events fold before
-        // Normal-dispatched (procedure follow-up) events in the same frame. A
-        // two-bucket partition does this in O(m) with no comparator — partition
-        // preserves intra-priority dispatch order — instead of sorting the frame.
         const [high, normal] = Arr.partition(frame, (envelope) => rank(envelope.priority) !== 0)
         const ordered = [...high, ...normal]
 
-        // One synchronous block: every reducer write for the frame coalesces into
-        // a single notification flush. Routing to channels happens here too, so
-        // procedure bodies (run later, off their channel fibers) see post-batch
-        // state. No `yield*` in between, or the flush could fire early.
+        // Budget before folding — EventLoopOverflow is this tick's only typed failure
+        const sample = yield* Effect.sync(() => counter.add(ordered.length))
+        yield* enforceBudget(budget, sample)
+
+        // Sync block: coalesce reducer writes into one flush; no yield* mid-frame
         const failures = yield* Effect.sync(() => {
           const endFrame = instrumentation.frame(ordered.length)
           ordered.forEach((envelope) =>
             instrumentation.eventDispatched(envelope.event._tag, envelope.priority),
           )
-          // Isolate each fold: a synchronous throw in one reducer must not abandon
-          // the rest of the frame nor (via the `forever` below) kill the drain fiber
-          // and freeze the whole app. Collect failures here, log after the block.
+          // Isolate folds so one throw cannot kill the drain fiber
           const collected = Arr.flatMap(ordered, (envelope) =>
             Arr.filterMap(bucketOf(reducers.byTag, envelope.event._tag), (reducer) =>
               isolateApply(reducer, envelope.event, instrumentation),
             ),
           )
-          // Offer to each DISTINCT channel once. Routing per-procedure would offer a
-          // shared channel multiple times for one event, and each offer re-runs every
-          // procedure on it — duplicate execution.
+          // Offer each distinct channel once (per-procedure would double-run shared channels)
           ordered.forEach((envelope) => {
             bucketOf(procedures.channelsByTag, envelope.event._tag).forEach((channelName) => {
               channels.get(channelName)?.offer(envelope.event)
@@ -182,21 +150,23 @@ const drain = Effect.gen(function* () {
           { discard: true },
         )
       }).pipe(
-        // Belt-and-suspenders: even a defect outside the isolated fold (a bug in
-        // the loop itself) is logged and the tick restarts, so the bus never goes
-        // permanently deaf.
-        Effect.catchAllCause((cause) => Effect.logError('reform: drain tick crashed', cause)),
+        // Only typed failures (overflow) escape; defects restart the tick so the bus never goes deaf
+        Effect.catchAllCause((cause) =>
+          Option.match(Cause.failureOption(cause), {
+            onSome: () => Effect.failCause(cause),
+            onNone: () => Effect.logError('reform: drain tick crashed', cause),
+          }),
+        ),
+      ),
+    ).pipe(
+      Effect.tapErrorCause((cause) =>
+        Effect.logError('reform: event budget exceeded — the drain loop has been halted', cause),
       ),
+      Effect.tapError((overflow) => Effect.sync(() => budget.onOverflow(overflow))),
     ),
   )
 })
 
-/**
- * The reform engine: provides the bus + reducer/channel/procedure registries +
- * the per-runtime notification scheduler to the application and forks the single
- * drain loop. Registration mutates the live collections, so reducers/procedures/
- * channels merged alongside are picked up before the first dispatch (boot).
- */
 export const Engine: Layer.Layer<Bus | Reducers | Channels | Procedures | Queries> =
   Layer.scopedDiscard(drain).pipe(
     Layer.provideMerge(

package/src/runtime/queries.ts

@@ -1,25 +1,11 @@
 import { Context, Layer } from 'effect'
 import { type QueryState } from '../calc/queryState'
 
-// The `Queries` registry: the runtime-wide index of live query handles, the same
-// shape as `Reducers`/`Channels`/`Procedures` (`loop.ts`, `channel.ts`). Each
-// `AsyncCalc.live` driver registers its handle here scoped — so `AsyncCalc.invalidate`
-// / `AsyncCalc.refetch` (and any provider layer) can act on a calc by name without
-// holding its store tag. A base in-memory registry ships in `Engine`; provider
-// layers (persistence, focus/online managers) build on top by calling the handles.
-//
-// The per-calc generics are erased through function signatures (reads are
-// covariant; `subscribe` is uniform), so the heterogeneous registry needs no cast.
-
 export interface QueryHandle {
   readonly name: string
-  /** Mark the query's value stale (`isStale := true`). Does not fetch. */
   readonly invalidate: () => void
-  /** Force a run of the current key, bypassing the no-op-key guard. */
   readonly refetch: () => void
-  /** Read the current state (erased to the open value type). */
   readonly snapshot: () => QueryState<unknown, unknown>
-  /** Subscribe to state changes; returns an unsubscribe thunk. */
   readonly subscribe: (listener: () => void) => () => void
 }
 
@@ -41,9 +27,6 @@ const makeQueryRegistry = (): QueryRegistry => {
     register: (handle) => {
       byName.set(handle.name, handle)
     },
-    // Only drop the entry if it is still the one we registered: a same-named
-    // re-registration (re-mount before the old scope's finalizer runs) must not
-    // be clobbered by the stale handle's unregister.
     unregister: (handle) => {
       if (byName.get(handle.name) === handle) {
         byName.delete(handle.name)

package/src/scene/featureScene.test.ts

@@ -0,0 +1,59 @@
+import { Context, Effect, Layer, Schema as S } from 'effect'
+import { expect, test } from 'vitest'
+import * as Composition from '../compose/composition'
+import { mount } from '../compose/structure'
+import { ui } from '../compose/ui'
+import * as Event from '../event/event'
+import * as Feature from '../feature/feature'
+import { featureModule } from '../feature/feature'
+import { makeAppRuntime } from '../runtime/appRuntime'
+import { Engine } from '../runtime/loop'
+import { featureScene } from './scene'
+
+interface GreetingService {
+  readonly value: string
+}
+
+const GreetingBase: Context.TagClass<Greeting, 'featureScene.Greeting', GreetingService> =
+  Context.Tag('featureScene.Greeting')<Greeting, GreetingService>()
+class Greeting extends GreetingBase {}
+
+class Started extends Event.make('featureScene.Started', S.Struct({})) {}
+class RootUi extends ui('featureScene.RootUi')<{ props: { readonly greeting: string } }>() {}
+class RootComp extends Composition.make('featureScene.RootComp', {
+  title: 'Feature root',
+  ui: RootUi,
+}) {}
+
+const RootLive = Composition.live(RootComp, function* () {
+  const greeting = yield* Greeting
+  return mount({ props: { greeting: greeting.value }, slots: {} })
+})
+
+class RootFeature extends Feature.make('featureScene.root', {
+  composition: RootComp,
+  module: featureModule([Greeting], RootLive),
+  boot: [Event.construct(Started, {})],
+}) {}
+
+test('featureScene closes an eager root Feature with its typed requirements and boot', () => {
+  const root = featureScene(RootFeature, {
+    provide: Layer.mergeAll(Engine, Layer.succeed(Greeting, { value: 'hello' })),
+  })
+  const app = makeAppRuntime(root)
+
+  try {
+    const rendered = Effect.runSync(
+      Composition.render(app.read(RootComp.tag), {
+        props: {},
+        tracker: { add: () => {} },
+      }),
+    )
+
+    expect(root.composition).toBe(RootComp)
+    expect(root.boot).toEqual([Event.construct(Started, {})])
+    expect(rendered.props).toEqual({ greeting: 'hello' })
+  } finally {
+    app.dispose()
+  }
+})

package/src/scene/scene.ts

@@ -2,6 +2,12 @@ import { Layer, Struct } from 'effect'
 import type { CompositionClass, CompositionService } from '../compose/composition'
 import type { UiContract } from '../compose/ui'
 import type { EventOf } from '../event/event'
+import type {
+  EagerFeatureClass,
+  EngineServices,
+  FeatureRequirement,
+  ProvidedBy,
+} from '../feature/feature'
 import { CurrentSeedOverrides } from '../internal/seeds'
 import type { SeedsOf } from '../state/stateGroup'
 import type { Bus } from '../runtime/bus'
@@ -11,29 +17,8 @@ import {
   noopInstrumentation,
 } from '../runtime/instrumentation'
 
-// A scene is a VALUE — a composition plus the closed wiring that runs it: the
-// layers that supply its logic/views (each seeding its own live state) and the
-// boot events to dispatch once the runtime is live. Nothing self-registers on
-// import. A scene is the single handle every consumer takes instead of a bare
-// composition: the react host renders it, a proof runs against it, and the dev
-// tool previews it — all from the same closed `provide`.
-//
-// There is no seeded-`state` dict: variation (Default/Empty/Errored) comes from
-// providing different closed layers, exactly as production wiring does. The
-// composition's contract `C` is preserved (not erased to `unknown`) so a proof's
-// facade stays fully typed from `scene.composition`.
-
-/**
- * The services a built reform runtime exposes to its host: every composition's
- * logic and the event `Bus`. A scene's `provide` must close to these (a fully
- * wired app layer provides far more; this is the subset hosts read directly).
- */
 export type MountedServices = CompositionService | Bus
 
-// A scene's boot list holds CONSTRUCTED events (`Event.construct(E, payload)`),
-// not bare tagged objects — a lightweight nudge toward the real builder. It is
-// not a guarantee the event is handled by the wiring (reform carries no
-// type-level union of handled tags), only that it came from an event definition.
 type BootEvent = EventOf<string, unknown>
 
 export interface Scene<
@@ -41,35 +26,21 @@ export interface Scene<
   S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
 > {
   readonly kind: 'Scene'
-  /** The composition to run, with its contract + states preserved for typed consumers. */
   readonly composition: CompositionClass<unknown, C, S>
-  /** Closed wiring (logic + views), each layer seeding its own live state. */
   readonly provide: ReadonlyArray<Layer.Layer<MountedServices, never, never>>
-  /** Events dispatched once the runtime is live (e.g. `RequestedTodos`). */
   // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional boot read as `scene.boot ?? []` across non-batch hosts (drive/proof/remote/react/editor); Option would break them
   readonly boot?: ReadonlyArray<BootEvent>
-  /**
-   * The profiler hooks this scene records into, when profiled (`profiledScene`).
-   * Hosts read it via {@link sceneInstrumentation} to time renders — kept on the
-   * scene (not only inside the layers) because render spans live in the HOST
-   * (React `Compose`, the proof engine), outside the runtime's layer context.
-   */
+  // instrumentation on the scene (not only layers): host render spans live outside layer context
   // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional carrier like `boot`; absent on every unprofiled scene, so Option would tax all authoring call sites
   readonly instrumentation?: Instrumentation
 }
 
-/** Closed wiring + optional boot events handed to {@link scene}. */
 export interface SceneConfig {
   readonly provide: ReadonlyArray<Layer.Layer<MountedServices, never, never>>
   // oxlint-disable-next-line reform-rules/no-optional-fields -- mirrors Scene.boot; presence-optional to keep the authoring call site terse and back-compatible
   readonly boot?: ReadonlyArray<BootEvent>
 }
 
-/**
- * Define a scene — `scene(TodoApp, { provide: [makeTestApp(client, seeds)] })`.
- * The composition's contract `C` and state tuple `S` flow through, so consumers
- * (the facade, `seedScene`) stay typed.
- */
 export const scene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
   composition: CompositionClass<unknown, C, S>,
   config: SceneConfig,
@@ -80,19 +51,31 @@ export const scene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
   ...(config.boot !== undefined ? { boot: config.boot } : {}),
 })
 
-/**
- * Overlay seed values onto a CLOSED scene — the tooling/test seam (dev-tool
- * inspector overrides, proofs). Scenes stay closed for authors: this does not
- * reopen `provide`, it wraps each layer with `Layer.locally(CurrentSeedOverrides,
- * seeds)` so `State.live` boots matching stores from the override instead of
- * the authored seed.
- *
- * Keys are state MEMBER NAMES as reflected in `manifest.states` (e.g. `count`),
- * not group names. If two groups in one scene share a member name, both receive
- * the override (documented limitation). Values are schema-validated at build:
- * an invalid value silently falls back to the authored seed. `StateFamily`
- * entries are not covered.
- */
+export interface FeatureSceneConfig<
+  Requires extends ReadonlyArray<FeatureRequirement>,
+> {
+  readonly provide: Layer.Layer<EngineServices | ProvidedBy<Requires>, never, never>
+}
+
+export const featureScene = <
+  P,
+  C extends UiContract,
+  ROut,
+  Requires extends ReadonlyArray<FeatureRequirement>,
+>(
+  feature: EagerFeatureClass<P, C, ROut, Requires>,
+  config: FeatureSceneConfig<Requires>,
+): Scene<C> => {
+  const app = feature.eagerModule.layer.pipe(Layer.provideMerge(config.provide))
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- close the generic root module's erased output to the host-readable Scene subset
+  const closed = app as Layer.Layer<MountedServices, never, never>
+  return scene(feature.composition, {
+    provide: [closed],
+    boot: feature.binding.boot,
+  })
+}
+
+// Tooling seam: wrap closed layers with seed overrides; keys are member names (not group names)
 export const seedScene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
   base: Scene<C, S>,
   seeds: SeedsOf<S>,
@@ -101,14 +84,6 @@ export const seedScene = <C extends UiContract, S extends ReadonlyArray<unknown>
     ? base
     : { ...base, provide: base.provide.map(Layer.locally(CurrentSeedOverrides, seeds)) }
 
-/**
- * Overlay profiler hooks onto a CLOSED scene — the profiling analog of
- * {@link seedScene}. Wraps each provided layer with
- * `Layer.locally(CurrentInstrumentation, instr)` so engine/state/calc layers
- * capture `instr` at build time, and carries `instr` on the scene so hosts can
- * time renders. Scenes stay closed; production wiring never calls this —
- * `@playfast/reform-profiler`'s `profileScene` is the intended caller.
- */
 export const profiledScene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
   base: Scene<C, S>,
   instrumentation: Instrumentation,
@@ -118,11 +93,9 @@ export const profiledScene = <C extends UiContract, S extends ReadonlyArray<unkn
   provide: base.provide.map(Layer.locally(CurrentInstrumentation, instrumentation)),
 })
 
-/** The instrumentation a host records render spans into — noop when unprofiled. */
 export const sceneInstrumentation = (candidate: Scene): Instrumentation =>
   candidate.instrumentation ?? noopInstrumentation
 
-/** Reflection guard: is this exported value a scene? */
 export const isScene = (candidate: unknown): candidate is Scene =>
   typeof candidate === 'object' &&
   candidate !== null &&