@playfast/reform 0.0.7 → 0.0.8

package/src/remote/remoteState.typecheck.ts

@@ -0,0 +1,195 @@
+// Type-level proofs enforced by `tsc --noEmit` over `src` (not a vitest file).
+// These guard the cast-free seam: if a guarantee regresses, a `@ts-expect-error`
+// goes unused or an assignment fails, and `tsc` breaks.
+
+import { Context, Effect, Layer, Match, Schema as S } from 'effect'
+import * as Boundary from '../boundary/boundary'
+import type { AsyncData } from '../calc/asyncData'
+import { type Channels, type Procedures } from '../channel/channel'
+import * as Event from '../event/event'
+import type { Store } from '../internal/store'
+import * as Reducer from '../reducer/reducer'
+import type { Bus } from '../runtime/bus'
+import { type Reducers } from '../runtime/loop'
+import * as State from '../state/state'
+import * as StateGroup from '../state/stateGroup'
+import { type AnySource, type Source } from '../state/token'
+import * as RemoteState from './remoteState'
+
+const AddIntentBase: Event.EventClass<'TAddIntent', { readonly id: string; readonly name: string }> =
+  Event.make('TAddIntent', S.Struct({ id: S.String, name: S.String }))
+class AddIntent extends AddIntentBase {}
+const RenameIntentBase: Event.EventClass<
+  'TRenameIntent',
+  { readonly id: string; readonly name: string }
+> = Event.make('TRenameIntent', S.Struct({ id: S.String, name: S.String }))
+class RenameIntent extends RenameIntentBase {}
+type Intent = Event.EventType<typeof AddIntent> | Event.EventType<typeof RenameIntent>
+
+const PageBase: State.StateClass<'tcPage', number> = State.make('tcPage', S.Number)
+class Page extends PageBase {}
+const InputsBase: StateGroup.StateGroupClass<readonly [typeof Page]> = StateGroup.make(Page)
+class Inputs extends InputsBase {}
+const page: Source<'tcPage', number> = StateGroup.select(Inputs, 'tcPage')
+
+const Row: S.Struct<{ id: typeof S.String; name: typeof S.String }> = S.Struct({
+  id: S.String,
+  name: S.String,
+})
+type Row = typeof Row.Type
+
+const SendDepBase: Context.TagClass<
+  SendDep,
+  'typecheck/SendDep',
+  { readonly go: Effect.Effect<void> }
+> = Context.Tag('typecheck/SendDep')<SendDep, { readonly go: Effect.Effect<void> }>()
+class SendDep extends SendDepBase {}
+
+const ItemsBase: RemoteState.RemoteStateClass<
+  'TItems',
+  readonly [typeof page],
+  readonly [typeof AddIntent, typeof RenameIntent],
+  ReadonlyArray<Row>,
+  string,
+  true
+> = RemoteState.make('TItems', {
+  inputs: [page],
+  output: S.Array(Row),
+  error: S.String,
+  intents: [AddIntent, RenameIntent],
+})
+class Items extends ItemsBase {}
+
+// --- intent-union inference: apply/send receive exactly the declared union ---
+
+// POSITIVE: a Match.exhaustive fold over the declared intents compiles, `send`'s
+// R2 flows from its body, and gated `disabled` is accepted.
+export const okLive: Layer.Layer<
+  | Store<AsyncData<ReadonlyArray<Row>, string, true>>
+  | Store<ReadonlyArray<RemoteState.PendingIntent<Intent>>>,
+  never,
+  Store<number> | SendDep | Reducers | Procedures | Channels | Bus
+> = RemoteState.live(Items, {
+  query: ({ tcPage }) =>
+    tcPage > 0 ? Effect.succeed<ReadonlyArray<Row>>([]) : Effect.fail('empty page'),
+  send: () => Effect.flatMap(SendDep, (dep) => dep.go),
+  apply: (rows, intent) =>
+    Match.value(intent).pipe(
+      Match.tag('TAddIntent', ({ id, name }) => [...rows, { id, name }]),
+      Match.tag('TRenameIntent', ({ id, name }) =>
+        rows.map((row) => (row.id === id ? { ...row, name } : row)),
+      ),
+      Match.exhaustive,
+    ),
+  disabled: ({ tcPage }) => tcPage < 0,
+})
+
+// NEGATIVE: a handler typed for an undeclared tag does not fit the union.
+export const badIntent: Layer.Layer<
+  | Store<AsyncData<ReadonlyArray<Row>, string, true>>
+  | Store<ReadonlyArray<RemoteState.PendingIntent<Intent>>>,
+  never,
+  Store<number> | Reducers | Procedures | Channels | Bus
+> = RemoteState.live(Items, {
+  query: () => Effect.succeed<ReadonlyArray<Row>>([]),
+  send: () => Effect.void,
+  // @ts-expect-error 'TDeleteIntent' is not in the declared intent union
+  apply: (rows: ReadonlyArray<Row>, intent: { readonly _tag: 'TDeleteIntent' }) => rows,
+})
+
+// --- layer requirement honesty: RIn is complete and exact ---
+
+// POSITIVE: the layer's RIn is exactly the input stores, the query/send context,
+// and the engine registries — and its ROut names the overlay + pending stores.
+export const okLayer: Layer.Layer<
+  Store<AsyncData<ReadonlyArray<Row>, string, true>> | Store<ReadonlyArray<RemoteState.PendingIntent<Intent>>>,
+  never,
+  Store<number> | SendDep | Reducers | Procedures | Channels | Bus
+> = okLive
+
+// NEGATIVE: dropping the send dependency (R2) from the annotation fails —
+// requirements cannot be silently widened away.
+// @ts-expect-error the send body's R2 must appear in the layer's requirements
+export const badLayer: Layer.Layer<
+  Store<AsyncData<ReadonlyArray<Row>, string, true>> | Store<ReadonlyArray<RemoteState.PendingIntent<Intent>>>,
+  never,
+  Store<number> | Reducers | Procedures | Channels | Bus
+> = okLive
+
+// --- alwaysOn / error narrowing: the read carries exactly the possible arms ---
+
+const AlwaysItemsBase: RemoteState.RemoteStateClass<
+  'TAlwaysItems',
+  readonly [typeof page],
+  readonly [typeof AddIntent],
+  ReadonlyArray<Row>,
+  never,
+  false
+> = RemoteState.make('TAlwaysItems', {
+  inputs: [page],
+  output: S.Array(Row),
+  intents: [AddIntent],
+  alwaysOn: true,
+})
+class AlwaysItems extends AlwaysItemsBase {}
+
+// NEGATIVE: an alwaysOn remote state rejects `disabled` (erased to never).
+export const badDisabled: Layer.Layer<
+  | Store<AsyncData<ReadonlyArray<Row>, never, false>>
+  | Store<ReadonlyArray<RemoteState.PendingIntent<Event.EventType<typeof AddIntent>>>>,
+  never,
+  Store<number> | Reducers | Procedures | Channels | Bus
+> = RemoteState.live(AlwaysItems, {
+  query: () => Effect.succeed<ReadonlyArray<Row>>([]),
+  send: () => Effect.void,
+  apply: (rows) => rows,
+  // @ts-expect-error an alwaysOn remote state cannot be disabled
+  disabled: () => false,
+})
+
+declare const alwaysArms: Effect.Effect.Success<typeof AlwaysItems>['_tag']
+declare const gatedArms: Effect.Effect.Success<typeof Items>['_tag']
+declare const idleArm: 'Idle'
+declare const errorArm: 'Error'
+declare const fourArms: 'Idle' | 'Loading' | 'Success' | 'Error'
+
+// POSITIVE: alwaysOn + no `error` schema ⇒ at most Loading | Success…
+export const alwaysExact: 'Loading' | 'Success' = alwaysArms
+// …and gated + `error` schema ⇒ exactly all four arms (both directions).
+export const gatedSubset: 'Idle' | 'Loading' | 'Success' | 'Error' = gatedArms
+export const gatedAll: Effect.Effect.Success<typeof Items>['_tag'] = fourArms
+
+// NEGATIVE: the excluded arms really are gone from the read type.
+// @ts-expect-error an alwaysOn remote state has no Idle arm
+export const noIdle: Effect.Effect.Success<typeof AlwaysItems>['_tag'] = idleArm
+// @ts-expect-error no `error` schema ⇒ no Error arm
+export const noError: Effect.Effect.Success<typeof AlwaysItems>['_tag'] = errorArm
+
+// --- surface shape: Sources where expected, never a reducer target ---
+
+// POSITIVE: the class itself is a `Source` (a calc input / boundary coverage),
+// valued at the overlaid lifecycle.
+export const classAsSource: Source<'TItems', AsyncData<ReadonlyArray<Row>, string, true>> = Items
+export const classAsAnySource: AnySource = Items
+
+// POSITIVE: `pending` is an ordinary read-only `Source` (badges, "saving…" chrome).
+export const pendingAsSource: Source<'TItems/pending', ReadonlyArray<RemoteState.PendingIntent<Intent>>> =
+  Items.pending
+
+// POSITIVE: `truth` is the un-overlaid lifecycle under the same arms.
+export const truthAsSource: Source<'TItems/truth', AsyncData<ReadonlyArray<Row>, string, true>> =
+  Items.truth
+
+// POSITIVE: a boundary covers the remote state like any lifecycle source.
+export const covered: Boundary.BoundaryClass<'TItemsBoundary', readonly [typeof Items]> =
+  Boundary.make('TItemsBoundary', { over: [Items] })
+
+// NEGATIVE: the pending queue is NOT user state — `Reducer.make` cannot target
+// it (it is a `StateToken`, not a `StateClass`; the hidden queue reducer is the
+// sole writer).
+export const badReducerTarget: Reducer.StateReducerClass<State.AnyState, readonly [typeof AddIntent]> =
+  // @ts-expect-error the pending queue is not a reducible state
+  Reducer.make('TBadReducer', {
+    states: [Items.pending],
+    events: [AddIntent],
+  })

package/src/runtime/bus.ts

@@ -0,0 +1,40 @@
+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`.
+ */
+export const narrowHandled = <E>(event: Tagged): E => event as never
+
+/** UI-originated events are High; procedure-emitted follow-ups are Normal (DESIGN #46). */
+export type Priority = 'High' | 'Normal'
+
+export interface Envelope {
+  readonly priority: Priority
+  readonly event: Tagged
+}
+
+const BusBase: Context.TagClass<Bus, 'reform/Bus', PubSub.PubSub<Envelope>> = Context.Tag(
+  '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).
+export const busLayer: Layer.Layer<Bus> = Layer.scoped(Bus, PubSub.unbounded<Envelope>())
+
+export const publish = (priority: Priority, event: Tagged): Effect.Effect<void, never, Bus> =>
+  Effect.flatMap(Bus, (bus) => PubSub.publish(bus, { priority, event }))

package/src/runtime/hardening.test.ts

@@ -0,0 +1,69 @@
+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.
+
+it.live('a reducer that throws is isolated; the loop keeps draining', () => {
+  class Counter extends State.make('counter', S.Number) {}
+  class Good extends Event.make('Good', S.Struct({})) {}
+  class Bad extends Event.make('Bad', S.Struct({})) {}
+  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 BadLive = Reducer.live(BadReducer, () => {
+    throw new Error('boom')
+  })
+
+  const TestLayer = Layer.mergeAll(GoodLive, BadLive).pipe(
+    Layer.provideMerge(Layer.mergeAll(State.live(Counter, 0), Engine)),
+  )
+
+  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),
+  )
+})
+
+it.effect('two different channels registered under one name are rejected', () => {
+  class Merge extends Channel.make('Dup', { policy: { _tag: 'merge' } }) {}
+  class Latest extends Channel.make('Dup', { policy: { _tag: 'latest' } }) {}
+  const layer = Layer.mergeAll(Channel.live(Merge), Channel.live(Latest)).pipe(
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const exit = yield* Effect.scoped(Layer.build(layer)).pipe(Effect.exit)
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      expect(Cause.pretty(exit.cause)).toContain('duplicate Channel')
+    }
+  })
+})
+
+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(
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const exit = yield* Effect.scoped(Layer.build(layer)).pipe(Effect.exit)
+    expect(Exit.isSuccess(exit)).toBe(true)
+  })
+})

package/src/runtime/loop.test.ts

@@ -0,0 +1,178 @@
+import { expect, it } from '@effect/vitest'
+import { Duration, Effect, Layer, Schema as S, TestClock } from 'effect'
+import { Channel, Engine, Event, Procedure, publish, Reducer, State } from '../index'
+
+// Headless tests for the single frame-batched drain loop and channels, written
+// with `@effect/vitest`: `it.live` for cases that lean on the real microtask
+// queue (the store notifier), `it.effect` + `TestClock` for time-based channels.
+
+it.live('a frame of events drains in one pass with a single notification flush', () => {
+  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 TestLayer = BumpReducerLive.pipe(
+    Layer.provideMerge(Layer.mergeAll(State.live(Counter, 0), Engine)),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Counter.store
+    const notifications = { n: 0 }
+    store.subscribe(() => {
+      notifications.n += 1
+    })
+
+    // Three events in one tick batch into one frame, fold in order, and the
+    // coalesced store notifier wakes the subscriber exactly once.
+    yield* publish('Normal', Event.construct(Bumped, { to: 1 }))
+    yield* publish('Normal', Event.construct(Bumped, { to: 2 }))
+    yield* publish('Normal', Event.construct(Bumped, { to: 3 }))
+    yield* Effect.sleep(Duration.millis(20))
+
+    expect(store.get()).toBe(3)
+    expect(notifications.n).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('an exclusive channel serializes procedures that share it', () => {
+  class StartA extends Event.make('StartA', S.Struct({})) {}
+  class StartB extends Event.make('StartB', S.Struct({})) {}
+  class Exclusive extends Channel.make('Exclusive', { policy: { _tag: 'exclusive' } }) {}
+
+  const concurrency = { active: 0, max: 0 }
+  const guarded = function* () {
+    concurrency.active += 1
+    concurrency.max = Math.max(concurrency.max, concurrency.active)
+    yield* Effect.sleep(Duration.millis(15))
+    concurrency.active -= 1
+  }
+
+  class ProcA extends Procedure.make('ProcA', { events: [StartA], channel: Exclusive }) {}
+  class ProcB extends Procedure.make('ProcB', { events: [StartB], channel: Exclusive }) {}
+  const ProcALive = Procedure.live(ProcA, guarded)
+  const ProcBLive = Procedure.live(ProcB, guarded)
+
+  const TestLayer = Layer.mergeAll(Channel.live(Exclusive), ProcALive, ProcBLive).pipe(
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    yield* publish('Normal', Event.construct(StartA, {}))
+    yield* publish('Normal', Event.construct(StartB, {}))
+    yield* Effect.sleep(Duration.millis(60))
+    // Without exclusivity both would run concurrently (max === 2).
+    expect(concurrency.max).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('two procedures sharing a channel each run once for one shared event', () => {
+  // Both procedures handle the SAME event on the SAME channel. The loop must
+  // offer the event to the channel once, so each procedure runs exactly once —
+  // not once per matching procedure (which would double every run).
+  class Shared extends Event.make('Shared', S.Struct({})) {}
+  class Lane extends Channel.make('Lane', { policy: { _tag: 'merge' } }) {}
+
+  const runs = { a: 0, b: 0 }
+  class ProcA extends Procedure.make('ProcA', { events: [Shared], channel: Lane }) {}
+  class ProcB extends Procedure.make('ProcB', { events: [Shared], channel: Lane }) {}
+  const ProcALive = Procedure.live(ProcA, function* () {
+    runs.a += 1
+  })
+  const ProcBLive = Procedure.live(ProcB, function* () {
+    runs.b += 1
+  })
+
+  const TestLayer = Layer.mergeAll(Channel.live(Lane), ProcALive, ProcBLive).pipe(
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    yield* publish('High', Event.construct(Shared, {}))
+    yield* Effect.sleep(Duration.millis(20))
+    expect(runs.a).toBe(1)
+    expect(runs.b).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.effect('a debounce channel collapses a burst into a single run', () => {
+  class Typed extends Event.make('Typed', S.Struct({})) {}
+  class Debounced extends Channel.make('Debounced', {
+    policy: { _tag: 'debounce', duration: Duration.millis(30) },
+  }) {}
+
+  const runs = { n: 0 }
+  class Search extends Procedure.make('Search', { events: [Typed], channel: Debounced }) {}
+  const SearchLive = Procedure.live(Search, function* () {
+    runs.n += 1
+  })
+
+  const TestLayer = Layer.mergeAll(Channel.live(Debounced), SearchLive).pipe(
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    yield* publish('Normal', Event.construct(Typed, {}))
+    yield* publish('Normal', Event.construct(Typed, {}))
+    yield* publish('Normal', Event.construct(Typed, {}))
+    // Let the loop route the frame into the channel and arm the debounce window.
+    yield* Effect.yieldNow().pipe(Effect.repeatN(20))
+    // Advance the simulated clock past the window: the burst emits once.
+    yield* TestClock.adjust(Duration.millis(31))
+    yield* Effect.yieldNow().pipe(Effect.repeatN(20))
+    expect(runs.n).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a reducer ignores events outside its declared set (no-op)', () => {
+  class Counter extends State.make('counter', S.Number) {}
+  class Bump extends Event.make('Bump', S.Struct({})) {}
+  class Unrelated extends Event.make('Unrelated', S.Struct({})) {}
+  class BumpReducer extends Reducer.make('BumpReducer', { states: [Counter], events: [Bump] }) {}
+  const BumpReducerLive = Reducer.live(BumpReducer, (n) => n + 1)
+
+  const TestLayer = BumpReducerLive.pipe(
+    Layer.provideMerge(Layer.mergeAll(State.live(Counter, 0), Engine)),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Counter.store
+    // An event the reducer doesn't declare never reaches its fold.
+    yield* publish('Normal', Event.construct(Unrelated, {}))
+    yield* Effect.sleep(Duration.millis(10))
+    expect(store.get()).toBe(0)
+    // A declared event does.
+    yield* publish('Normal', Event.construct(Bump, {}))
+    yield* Effect.sleep(Duration.millis(10))
+    expect(store.get()).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.effect('a latest channel cancels the in-flight run when a new event arrives', () => {
+  class Tick extends Event.make('Tick', S.Struct({})) {}
+  class Latest extends Channel.make('Latest', { policy: { _tag: 'latest' } }) {}
+
+  const counts = { started: 0, completed: 0 }
+  class Work extends Procedure.make('Work', { events: [Tick], channel: Latest }) {}
+  const WorkLive = Procedure.live(Work, function* () {
+    counts.started += 1
+    yield* Effect.sleep(Duration.millis(50))
+    counts.completed += 1
+  })
+
+  const TestLayer = Layer.mergeAll(Channel.live(Latest), WorkLive).pipe(Layer.provideMerge(Engine))
+
+  return Effect.gen(function* () {
+    // First tick starts a run that parks on its 50ms sleep.
+    yield* publish('Normal', Event.construct(Tick, {}))
+    yield* Effect.yieldNow().pipe(Effect.repeatN(20))
+    // Second tick switches the channel, interrupting the first run mid-sleep.
+    yield* publish('Normal', Event.construct(Tick, {}))
+    yield* Effect.yieldNow().pipe(Effect.repeatN(20))
+    yield* TestClock.adjust(Duration.millis(60))
+    yield* Effect.yieldNow().pipe(Effect.repeatN(20))
+    // Both runs began, but only the latest survived to completion.
+    expect(counts.started).toBe(2)
+    expect(counts.completed).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/runtime/loop.ts

@@ -0,0 +1,171 @@
+import { Chunk, Context, Effect, Layer, PubSub, Queue } from 'effect'
+import {
+  Channels,
+  channelsLayer,
+  Procedures,
+  proceduresLayer,
+} from '../channel/channel'
+import { notificationsLayer } from '../internal/scheduler'
+import { Bus, busLayer, type Envelope, type Tagged } from './bus'
+
+/**
+ * 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
+}
+
+const ReducersBase: Context.TagClass<Reducers, 'reform/Reducers', ReducerRegistry> =
+  Context.Tag('reform/Reducers')<Reducers, ReducerRegistry>()
+export class Reducers extends ReducersBase {}
+
+/** Drop an item from a `Map<string, Array>` bucket, pruning the key when it empties. */
+const dropFromBuckets = <T>(map: Map<string, Array<T>>, key: string, item: T): void => {
+  const bucket = map.get(key)
+  if (bucket === undefined) return
+  const next = bucket.filter((entry) => entry !== item)
+  if (next.length === 0) map.delete(key)
+  else map.set(key, next)
+}
+
+const makeReducerRegistry = (): ReducerRegistry => {
+  const entries: Array<ReducerEntry> = []
+  const byTag = new Map<string, Array<ReducerEntry>>()
+  return {
+    entries,
+    byTag,
+    register: (entry) => {
+      entries.push(entry)
+      for (const tag of entry.handles) {
+        const bucket = byTag.get(tag)
+        if (bucket === undefined) byTag.set(tag, [entry])
+        else bucket.push(entry)
+      }
+    },
+    unregister: (entry) => {
+      const index = entries.indexOf(entry)
+      if (index >= 0) entries.splice(index, 1)
+      for (const tag of entry.handles) dropFromBuckets(byTag, tag, entry)
+    },
+  }
+}
+
+export const reducersLayer: Layer.Layer<Reducers> = Layer.sync(Reducers, makeReducerRegistry)
+
+/** High before Normal; within a priority class, dispatch order is preserved. */
+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
+  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 — push order
+        // preserves intra-priority dispatch order — instead of sorting the frame.
+        const high: Array<Envelope> = []
+        const normal: Array<Envelope> = []
+        for (const envelope of frame) {
+          if (rank(envelope.priority) === 0) high.push(envelope)
+          else normal.push(envelope)
+        }
+        const ordered = high.concat(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.
+        const failures: Array<{ readonly event: Tagged; readonly error: unknown }> = []
+        yield* Effect.sync(() => {
+          for (const envelope of ordered) {
+            for (const reducer of reducers.byTag.get(envelope.event._tag) ?? []) {
+              // 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 and log after.
+              try {
+                reducer.apply(envelope.event)
+              } catch (error) {
+                failures.push({ event: envelope.event, error })
+              }
+            }
+          }
+          for (const envelope of ordered) {
+            // 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.
+            for (const channelName of procedures.channelsByTag.get(envelope.event._tag) ?? []) {
+              channels.get(channelName)?.offer(envelope.event)
+            }
+          }
+        })
+        yield* Effect.forEach(
+          failures,
+          (failure) =>
+            Effect.logError(
+              `reform: reducer threw handling '${failure.event._tag}'`,
+              failure.error,
+            ),
+          { 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)),
+      ),
+    ),
+  )
+})
+
+/**
+ * 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> = Layer.scopedDiscard(
+  drain,
+).pipe(
+  Layer.provideMerge(
+    Layer.mergeAll(busLayer, reducersLayer, channelsLayer, proceduresLayer, notificationsLayer),
+  ),
+)