@playfast/reform 0.1.0 → 1.1.1

package/src/runtime/instrumentation.test.ts

@@ -0,0 +1,324 @@
+import { expect, it } from "@effect/vitest";
+import { Duration, Effect, Layer, Schema as S } from "effect";
+import {
+  AsyncCalc,
+  Calc,
+  Channel,
+  Composition,
+  CurrentInstrumentation,
+  Engine,
+  Event,
+  type Instrumentation,
+  mount,
+  noopInstrumentation,
+  type Priority,
+  Procedure,
+  profiledScene,
+  provide,
+  publish,
+  Reducer,
+  scene,
+  sceneInstrumentation,
+  State,
+  StateGroup,
+  Ui,
+  ui,
+} from "../index";
+
+const tick = (ms = 20) => Effect.sleep(Duration.millis(ms));
+
+const makeRecorder = () => {
+  const events: Array<{ readonly tag: string; readonly priority: Priority }> =
+    [];
+  const reducers: Array<{ readonly name: string; readonly eventTag: string }> =
+    [];
+  const states: Array<string> = [];
+  const calcs: Array<string> = [];
+  const queries: Array<string> = [];
+  const procedures: Array<{
+    readonly name: string;
+    readonly channel: string;
+    readonly eventTag: string;
+  }> = [];
+  const frames: Array<number> = [];
+  const ends = { reducer: 0, calc: 0, query: 0, procedure: 0, frame: 0 };
+  const instrumentation: Instrumentation = {
+    eventDispatched: (tag, priority) => {
+      events.push({ tag, priority });
+    },
+    reducerRun: (name, eventTag) => {
+      reducers.push({ name, eventTag });
+      return () => {
+        ends.reducer += 1;
+      };
+    },
+    stateUpdated: (name) => {
+      states.push(name);
+    },
+    calcRecomputed: (name) => {
+      calcs.push(name);
+      return () => {
+        ends.calc += 1;
+      };
+    },
+    queryRun: (name) => {
+      queries.push(name);
+      return () => {
+        ends.query += 1;
+      };
+    },
+    procedureRun: (name, channel, eventTag) => {
+      procedures.push({ name, channel, eventTag });
+      return () => {
+        ends.procedure += 1;
+      };
+    },
+    uiRendered: () => () => {},
+    frame: (eventCount) => {
+      frames.push(eventCount);
+      return () => {
+        ends.frame += 1;
+      };
+    },
+  };
+  return {
+    instrumentation,
+    events,
+    reducers,
+    states,
+    calcs,
+    queries,
+    procedures,
+    frames,
+    ends,
+  };
+};
+
+it.live(
+  "the engine reports frames, events, reducer spans, and state updates",
+  () => {
+    const recorder = makeRecorder();
+    class Counter extends State.make("instr-counter", S.Number) {}
+    class Bumped extends Event.make(
+      "InstrBumped",
+      S.Struct({ to: S.Number }),
+    ) {}
+    class Fold extends Reducer.make("InstrFold", {
+      states: [Counter],
+      events: [Bumped],
+    }) {}
+    const FoldLive = Reducer.live(Fold, (_, event) => event.to);
+
+    const TestLayer = FoldLive.pipe(
+      Layer.provideMerge(Layer.mergeAll(State.live(Counter, 0), Engine)),
+      Layer.locally(CurrentInstrumentation, recorder.instrumentation),
+    );
+
+    return Effect.gen(function* () {
+      yield* publish("High", Event.construct(Bumped, { to: 1 }));
+      yield* publish("Normal", Event.construct(Bumped, { to: 2 }));
+      yield* tick();
+
+      expect(recorder.frames).toEqual([2]);
+      expect(recorder.ends.frame).toBe(1);
+      expect(recorder.events).toEqual([
+        { tag: "InstrBumped", priority: "High" },
+        { tag: "InstrBumped", priority: "Normal" },
+      ]);
+      expect(recorder.reducers).toEqual([
+        { name: "InstrFold", eventTag: "InstrBumped" },
+        { name: "InstrFold", eventTag: "InstrBumped" },
+      ]);
+      expect(recorder.ends.reducer).toBe(2);
+      expect(recorder.states).toEqual(["instr-counter", "instr-counter"]);
+    }).pipe(Effect.provide(TestLayer));
+  },
+);
+
+it.live("an equal-value write is not reported as a state update", () => {
+  const recorder = makeRecorder();
+  class Cell extends State.make("instr-cell", S.Number) {}
+  class Wrote extends Event.make("InstrWrote", S.Struct({ to: S.Number })) {}
+  class Write extends Reducer.make("InstrWrite", {
+    states: [Cell],
+    events: [Wrote],
+  }) {}
+  const WriteLive = Reducer.live(Write, (_, event) => event.to);
+
+  const TestLayer = WriteLive.pipe(
+    Layer.provideMerge(Layer.mergeAll(State.live(Cell, 7), Engine)),
+    Layer.locally(CurrentInstrumentation, recorder.instrumentation),
+  );
+
+  return Effect.gen(function* () {
+    yield* publish("High", Event.construct(Wrote, { to: 7 }));
+    yield* tick();
+    expect(recorder.reducers.length).toBe(1);
+    expect(recorder.states).toEqual([]);
+  }).pipe(Effect.provide(TestLayer));
+});
+
+it.live("calc recomputes are spanned; memo hits are not counted", () => {
+  const recorder = makeRecorder();
+  class Count extends State.make("instr-calc-count", S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Doubled extends Calc.make("InstrDoubled", {
+    inputs: [StateGroup.select(Inputs, "instr-calc-count")],
+    output: S.Number,
+  }) {}
+  const DoubledLive = Calc.live(
+    Doubled,
+    (inputs) => inputs["instr-calc-count"] * 2,
+  );
+
+  const TestLayer = DoubledLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { "instr-calc-count": 5 })),
+    Layer.locally(CurrentInstrumentation, recorder.instrumentation),
+  );
+
+  return Effect.gen(function* () {
+    const derived = yield* Doubled.store;
+    const builds = recorder.calcs.length;
+    expect(derived.get()).toBe(10);
+    expect(derived.get()).toBe(10);
+    expect(recorder.calcs.length).toBe(builds);
+
+    const source = yield* StateGroup.select(Inputs, "instr-calc-count").store;
+    source.set(6);
+    yield* tick();
+    expect(derived.get()).toBe(12);
+    expect(recorder.calcs.length).toBe(builds + 1);
+    expect(recorder.calcs.every((name) => name === "InstrDoubled")).toBe(true);
+    expect(recorder.ends.calc).toBe(recorder.calcs.length);
+    expect(recorder.states).toContain("InstrDoubled");
+  }).pipe(Effect.provide(TestLayer));
+});
+
+it.live("async calc query runs are spanned start-to-settle", () => {
+  const recorder = makeRecorder();
+  class Count extends State.make("instr-query-count", S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Fetched extends AsyncCalc.make("InstrFetched", {
+    inputs: [StateGroup.select(Inputs, "instr-query-count")],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const FetchedLive = AsyncCalc.live(Fetched, {
+    query: (inputs) =>
+      Effect.succeed(inputs["instr-query-count"] * 2).pipe(
+        Effect.delay(Duration.millis(5)),
+      ),
+  });
+
+  const TestLayer = FetchedLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { "instr-query-count": 3 })),
+    Layer.locally(CurrentInstrumentation, recorder.instrumentation),
+  );
+
+  return Effect.gen(function* () {
+    const store = yield* Fetched.store;
+    yield* tick(40);
+    expect(store.get()._tag).toBe("Success");
+    expect(recorder.queries).toEqual(["InstrFetched"]);
+    expect(recorder.ends.query).toBe(1);
+  }).pipe(Effect.provide(TestLayer));
+});
+
+it.live("procedure runs are spanned with their channel and trigger tag", () => {
+  const recorder = makeRecorder();
+  class Kicked extends Event.make("InstrKicked", S.Struct({})) {}
+  class Lane extends Channel.make("InstrLane", { policy: { _tag: "merge" } }) {}
+  class Work extends Procedure.make("InstrWork", {
+    events: [Kicked],
+    channel: Lane,
+  }) {}
+  const WorkLive = Procedure.live(Work, function* () {
+    yield* tick(5);
+  });
+
+  const TestLayer = Layer.mergeAll(Channel.live(Lane), WorkLive).pipe(
+    Layer.provideMerge(Engine),
+    Layer.locally(CurrentInstrumentation, recorder.instrumentation),
+  );
+
+  return Effect.gen(function* () {
+    yield* publish("Normal", Event.construct(Kicked, {}));
+    yield* tick(40);
+    expect(recorder.procedures).toEqual([
+      { name: "InstrWork", channel: "InstrLane", eventTag: "InstrKicked" },
+    ]);
+    expect(recorder.ends.procedure).toBe(1);
+  }).pipe(Effect.provide(TestLayer));
+});
+
+class SceneCount extends State.make("instr-scene-count", S.Number) {}
+class SceneStates extends StateGroup.make(SceneCount) {}
+class SceneBumped extends Event.make("InstrSceneBumped", S.Struct({})) {}
+class SceneBump extends Reducer.make("InstrSceneBump", {
+  states: [SceneCount],
+  events: [SceneBumped],
+}) {}
+const SceneBumpLive = Reducer.live(SceneBump, (n) => n + 1);
+
+class SceneUi extends ui("InstrScene")<{ props: { count: number } }>() {}
+class SceneRoot extends Composition.make("InstrScene", {
+  title: "InstrScene",
+  states: [SceneStates],
+  events: [SceneBumped],
+  ui: SceneUi,
+}) {}
+const SceneRootLive = Composition.live(SceneRoot, function* () {
+  const count = yield* StateGroup.select(SceneStates, "instr-scene-count");
+  return mount({ props: { count }, slots: {} });
+});
+
+const SceneApp = SceneRootLive.pipe(
+  Layer.provideMerge(
+    provide(
+      SceneUi,
+      Ui.make(SceneUi, () => null),
+    ),
+  ),
+  Layer.provideMerge(
+    Layer.mergeAll(SceneBumpLive).pipe(
+      Layer.provideMerge(
+        Layer.mergeAll(
+          Engine,
+          StateGroup.live(SceneStates, { "instr-scene-count": 0 }),
+        ),
+      ),
+    ),
+  ),
+);
+const InstrScene = scene(SceneRoot, { provide: [SceneApp] });
+
+const runScene = (target: typeof InstrScene) => {
+  const layer = target.provide.reduce((a, b) => Layer.merge(a, b));
+  const drive = Effect.gen(function* () {
+    yield* publish("High", Event.construct(SceneBumped, {}));
+    yield* tick();
+  });
+  return { layer, drive };
+};
+
+it.scopedLive(
+  "profiledScene reaches nested layers and carries the handle",
+  () =>
+    Effect.gen(function* () {
+      const recorder = makeRecorder();
+      const profiled = profiledScene(InstrScene, recorder.instrumentation);
+      expect(sceneInstrumentation(profiled)).toBe(recorder.instrumentation);
+
+      const profiledHarness = runScene(profiled);
+      yield* profiledHarness.drive.pipe(Effect.provide(profiledHarness.layer));
+      expect(recorder.reducers).toEqual([
+        { name: "InstrSceneBump", eventTag: "InstrSceneBumped" },
+      ]);
+      expect(recorder.states).toEqual(["instr-scene-count"]);
+      const before = recorder.reducers.length;
+      expect(sceneInstrumentation(InstrScene)).toBe(noopInstrumentation);
+      const original = runScene(InstrScene);
+      yield* original.drive.pipe(Effect.provide(original.layer));
+      expect(recorder.reducers.length).toBe(before);
+    }),
+);

package/src/runtime/instrumentation.ts

@@ -0,0 +1,44 @@
+import { Effect, FiberRef, GlobalValue } from 'effect'
+import type { Priority } from './bus'
+
+export type SpanEnd = () => void
+
+export interface Instrumentation {
+  eventDispatched(tag: string, priority: Priority): void
+  reducerRun(name: string, eventTag: string): SpanEnd
+  stateUpdated(name: string): void
+  calcRecomputed(name: string): SpanEnd
+  queryRun(name: string): SpanEnd
+  procedureRun(name: string, channel: string, eventTag: string): SpanEnd
+  uiRendered(composition: string): SpanEnd
+  frame(eventCount: number): SpanEnd
+}
+
+const noopSpanEnd: SpanEnd = () => {}
+
+export const noopInstrumentation: Instrumentation = {
+  eventDispatched: () => {},
+  reducerRun: () => noopSpanEnd,
+  stateUpdated: () => {},
+  calcRecomputed: () => noopSpanEnd,
+  queryRun: () => noopSpanEnd,
+  procedureRun: () => noopSpanEnd,
+  uiRendered: () => noopSpanEnd,
+  frame: () => noopSpanEnd,
+}
+
+export const CurrentInstrumentation: FiberRef.FiberRef<Instrumentation> =
+  GlobalValue.globalValue(Symbol.for('reform/CurrentInstrumentation'), () =>
+    FiberRef.unsafeMake<Instrumentation>(noopInstrumentation),
+  )
+
+export const resolveInstrumentation: Effect.Effect<Instrumentation> =
+  FiberRef.get(CurrentInstrumentation)
+
+export const stateUpdateHook = (
+  instrumentation: Instrumentation,
+  name: string,
+): (() => void) =>
+  instrumentation === noopInstrumentation
+    ? noopSpanEnd
+    : () => instrumentation.stateUpdated(name)

package/src/runtime/loop.test.ts

@@ -2,10 +2,6 @@ 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 })) {}
@@ -23,8 +19,6 @@ it.live('a frame of events drains in one pass with a single notification flush',
       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 }))
@@ -61,15 +55,11 @@ it.live('an exclusive channel serializes procedures that share it', () => {
     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' } }) {}
 
@@ -115,9 +105,7 @@ it.effect('a debounce channel collapses a burst into a single run', () => {
     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)
@@ -137,11 +125,9 @@ it.live('a reducer ignores events outside its declared set (no-op)', () => {
 
   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)
@@ -163,15 +149,12 @@ it.effect('a latest channel cancels the in-flight run when a new event arrives',
   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

@@ -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,36 +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
 }
 
@@ -44,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) {
@@ -60,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() {
@@ -86,77 +67,77 @@ 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,
-): Option.Option<{ readonly event: Tagged; readonly error: unknown }> =>
-  Effect.runSync(
+  instrumentation: Instrumentation,
+): Option.Option<{ readonly event: Tagged; readonly error: unknown }> => {
+  const end = instrumentation.reducerRun(reducer.name, event._tag)
+  return Effect.runSync(
     Effect.match(
-      Effect.try({ try: () => reducer.apply(event), catch: (error) => error }),
+      Effect.try({ try: () => reducer.apply(event), catch: (error) => error }).pipe(
+        Effect.ensuring(Effect.sync(end)),
+      ),
       {
         onFailure: (error) => Option.some({ event, error }),
         onSuccess: () => Option.none(),
       },
     ),
   )
+}
 
 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
+  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(() => {
-          // 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.
+          const endFrame = instrumentation.frame(ordered.length)
+          ordered.forEach((envelope) =>
+            instrumentation.eventDispatched(envelope.event._tag, envelope.priority),
+          )
+          // 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),
+              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)
             })
           })
+          endFrame()
           return collected
         })
         yield* Effect.forEach(
@@ -169,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)