@playfast/reform 1.0.1 → 1.1.1

package/src/runtime/instrumentation.test.ts

@@ -1,6 +1,5 @@
-import { expect, it } from '@effect/vitest'
-import { test } from 'vitest'
-import { Duration, Effect, Layer, ManagedRuntime, Schema as S } from 'effect'
+import { expect, it } from "@effect/vitest";
+import { Duration, Effect, Layer, Schema as S } from "effect";
 import {
   AsyncCalc,
   Calc,
@@ -24,280 +23,302 @@ import {
   StateGroup,
   Ui,
   ui,
-} from '../index'
+} from "../index";
 
-// The profiler SPI: every engine hot path consults `CurrentInstrumentation` once
-// at layer build time. These tests inject a recording instance the same way
-// `profileScene` will — `Layer.locally` on the wiring — and assert each hook
-// fires with the right names/counts, that spans end, and that the seam does not
-// leak into unprofiled wiring.
-
-const tick = (ms = 20) => Effect.sleep(Duration.millis(ms))
+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 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 }
+    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 })
+      events.push({ tag, priority });
     },
     reducerRun: (name, eventTag) => {
-      reducers.push({ name, eventTag })
+      reducers.push({ name, eventTag });
       return () => {
-        ends.reducer += 1
-      }
+        ends.reducer += 1;
+      };
     },
     stateUpdated: (name) => {
-      states.push(name)
+      states.push(name);
     },
     calcRecomputed: (name) => {
-      calcs.push(name)
+      calcs.push(name);
       return () => {
-        ends.calc += 1
-      }
+        ends.calc += 1;
+      };
     },
     queryRun: (name) => {
-      queries.push(name)
+      queries.push(name);
       return () => {
-        ends.query += 1
-      }
+        ends.query += 1;
+      };
     },
     procedureRun: (name, channel, eventTag) => {
-      procedures.push({ name, channel, eventTag })
+      procedures.push({ name, channel, eventTag });
       return () => {
-        ends.procedure += 1
-      }
+        ends.procedure += 1;
+      };
     },
     uiRendered: () => () => {},
     frame: (eventCount) => {
-      frames.push(eventCount)
+      frames.push(eventCount);
       return () => {
-        ends.frame += 1
-      }
+        ends.frame += 1;
+      };
     },
-  }
-  return { instrumentation, events, reducers, states, calcs, queries, procedures, frames, ends }
-}
+  };
+  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)
+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),
-  )
+    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()
+    return Effect.gen(function* () {
+      yield* publish("High", Event.construct(Bumped, { to: 1 }));
+      yield* publish("Normal", Event.construct(Bumped, { to: 2 }));
+      yield* tick();
 
-    // Both events landed in one frame; High folds before Normal.
-    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)
-    // Two genuinely new values (0 -> 1 -> 2), one update per fold.
-    expect(recorder.states).toEqual(['instr-counter', 'instr-counter'])
-  }).pipe(Effect.provide(TestLayer))
-})
+      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)
+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()
-    // The reducer ran, but the store's Equal gate suppressed the write.
-    expect(recorder.reducers.length).toBe(1)
-    expect(recorder.states).toEqual([])
-  }).pipe(Effect.provide(TestLayer))
-})
+    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) {}
+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')],
+  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 DoubledLive = Calc.live(
+    Doubled,
+    (inputs) => inputs["instr-calc-count"] * 2,
+  );
 
   const TestLayer = DoubledLive.pipe(
-    Layer.provideMerge(StateGroup.live(Inputs, { 'instr-calc-count': 5 })),
+    Layer.provideMerge(StateGroup.live(Inputs, { "instr-calc-count": 5 })),
     Layer.locally(CurrentInstrumentation, recorder.instrumentation),
-  )
+  );
 
   return Effect.gen(function* () {
-    const derived = yield* Doubled.store
-    // The derived store computes once at build; repeated reads hit the memo.
-    const builds = recorder.calcs.length
-    expect(derived.get()).toBe(10)
-    expect(derived.get()).toBe(10)
-    expect(recorder.calcs.length).toBe(builds)
+    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)
-    // The calc's output moved twice (build seeds silently; 10 -> 12 notifies once).
-    expect(recorder.states).toContain('InstrDoubled')
-  }).pipe(Effect.provide(TestLayer))
-})
+    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) {}
+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')],
+  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))),
-  })
+    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.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)
-    // The run fiber picked the request, started the span, and ended it on settle.
-    expect(store.get()._tag).toBe('Success')
-    expect(recorder.queries).toEqual(['InstrFetched'])
-    expect(recorder.ends.query).toBe(1)
-  }).pipe(Effect.provide(TestLayer))
-})
+    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 }) {}
+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)
-  })
+    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)
+    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))
-})
+      { name: "InstrWork", channel: "InstrLane", eventTag: "InstrKicked" },
+    ]);
+    expect(recorder.ends.procedure).toBe(1);
+  }).pipe(Effect.provide(TestLayer));
+});
 
-// ── The scene seam: `profiledScene` must reach layers inside a CLOSED scene and
-// carry the handle for hosts, without leaking into the original scene. ─────────
-
-class SceneCount extends State.make('instr-scene-count', S.Number) {}
+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', {
+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)
+const SceneBumpLive = Reducer.live(SceneBump, (n) => n + 1);
 
-class SceneUi extends ui('InstrScene')<{ props: { count: number } }>() {}
-class SceneRoot extends Composition.make('InstrScene', {
-  title: 'InstrScene',
+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 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(
+    provide(
+      SceneUi,
+      Ui.make(SceneUi, () => null),
+    ),
+  ),
   Layer.provideMerge(
     Layer.mergeAll(SceneBumpLive).pipe(
-      Layer.provideMerge(Layer.mergeAll(Engine, StateGroup.live(SceneStates, { 'instr-scene-count': 0 }))),
+      Layer.provideMerge(
+        Layer.mergeAll(
+          Engine,
+          StateGroup.live(SceneStates, { "instr-scene-count": 0 }),
+        ),
+      ),
     ),
   ),
-)
-const InstrScene = scene(SceneRoot, { provide: [SceneApp] })
+);
+const InstrScene = scene(SceneRoot, { provide: [SceneApp] });
 
 const runScene = (target: typeof InstrScene) => {
-  const layer = target.provide.reduce((a, b) => Layer.merge(a, b))
-  const runtime = ManagedRuntime.make(layer)
+  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 { runtime, drive }
-}
-
-test('profiledScene reaches nested layers and carries the handle', async () => {
-  const recorder = makeRecorder()
-  const profiled = profiledScene(InstrScene, recorder.instrumentation)
-  expect(sceneInstrumentation(profiled)).toBe(recorder.instrumentation)
+    yield* publish("High", Event.construct(SceneBumped, {}));
+    yield* tick();
+  });
+  return { layer, drive };
+};
 
-  const { runtime, drive } = runScene(profiled)
-  try {
-    await runtime.runPromise(drive)
-    expect(recorder.reducers).toEqual([{ name: 'InstrSceneBump', eventTag: 'InstrSceneBumped' }])
-    expect(recorder.states).toEqual(['instr-scene-count'])
-  } finally {
-    await runtime.dispose()
-  }
+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);
 
-  // Building the ORIGINAL scene again records nothing — the overlay lives only
-  // on the profiled variant's wrapped layers.
-  const before = recorder.reducers.length
-  expect(sceneInstrumentation(InstrScene)).toBe(noopInstrumentation)
-  const original = runScene(InstrScene)
-  try {
-    await original.runtime.runPromise(original.drive)
-    expect(recorder.reducers.length).toBe(before)
-  } finally {
-    await original.runtime.dispose()
-  }
-})
+      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

@@ -1,48 +1,21 @@
 import { Effect, FiberRef, GlobalValue } from 'effect'
 import type { Priority } from './bus'
 
-/**
- * The profiler SPI — a synchronous, Effect-free hook surface the engine calls on
- * its hot paths (the drain loop, store writes, calc recomputes, renders). It is
- * Effect-free for the same reason `Store`/`Scheduler` are: these sites run
- * synchronously inside a reduce frame or a React render, where forking or even
- * building an Effect per call would dominate the very costs being measured.
- *
- * Span-shaped hooks return a {@link SpanEnd} thunk: call it when the measured
- * work completes. The default implementation is {@link noopInstrumentation};
- * every hook site captures its instance ONCE at layer build time (see
- * `resolveInstrumentation`) and may skip name plumbing entirely when the
- * captured instance IS the noop (identity check), so an unprofiled runtime pays
- * nothing per operation.
- */
 export type SpanEnd = () => void
 
 export interface Instrumentation {
-  /** An event entered the drain frame (one call per envelope, per frame). */
   eventDispatched(tag: string, priority: Priority): void
-  /** A reducer is folding one event; ends when its synchronous `apply` returns. */
   reducerRun(name: string, eventTag: string): SpanEnd
-  /** A store accepted a genuinely new value (post-`Equal` gate). */
   stateUpdated(name: string): void
-  /** A calc's projection actually ran (memo hits are not counted). */
   calcRecomputed(name: string): SpanEnd
-  /** An async calc's query effect started; ends when it resolves/fails/cancels. */
   queryRun(name: string): SpanEnd
-  /** A procedure body started on its channel; ends when the fiber completes. */
   procedureRun(name: string, channel: string, eventTag: string): SpanEnd
-  /** A composition rendered one frame (host-injected: React `Compose` / proof engine). */
   uiRendered(composition: string): SpanEnd
-  /** One drain tick: folds + routing for `eventCount` envelopes. */
   frame(eventCount: number): SpanEnd
 }
 
 const noopSpanEnd: SpanEnd = () => {}
 
-/**
- * The shared do-nothing instrumentation. A single instance (and a single shared
- * `SpanEnd`), so hook sites can detect "profiling off" by identity and skip
- * their argument construction entirely.
- */
 export const noopInstrumentation: Instrumentation = {
   eventDispatched: () => {},
   reducerRun: () => noopSpanEnd,
@@ -54,36 +27,14 @@ export const noopInstrumentation: Instrumentation = {
   frame: () => noopSpanEnd,
 }
 
-/**
- * The sanctioned profiling seam for CLOSED scenes — the same mechanism as
- * `CurrentSeedOverrides` (`internal/seeds.ts`): a scene's layers are
- * pre-composed, but a FiberRef set via `Layer.locally(ref, value)(layer)` IS
- * visible inside the construction effects of nested layers. Engine/state/calc
- * layers consult this ref once at build time and capture the resolved instance
- * into their hot-path closures.
- *
- * Defaults to {@link noopInstrumentation} — production wiring never touches it.
- * `profileScene` (in `@playfast/reform-profiler`) is the intended writer.
- * `globalValue` keeps a single ref instance even if the module is loaded twice
- * (duplicated bundles, HMR), so the writer and the reader always agree.
- */
 export const CurrentInstrumentation: FiberRef.FiberRef<Instrumentation> =
   GlobalValue.globalValue(Symbol.for('reform/CurrentInstrumentation'), () =>
     FiberRef.unsafeMake<Instrumentation>(noopInstrumentation),
   )
 
-/**
- * Resolve the ambient instrumentation at layer build time. Layers capture the
- * result into their closures; they must not re-read it per operation.
- */
 export const resolveInstrumentation: Effect.Effect<Instrumentation> =
   FiberRef.get(CurrentInstrumentation)
 
-/**
- * The store `onChange` hook for one named state/calc: a bound
- * `stateUpdated(name)` closure when profiled, the shared no-op otherwise — so
- * an unprofiled store's write path never constructs the name-carrying call.
- */
 export const stateUpdateHook = (
   instrumentation: Instrumentation,
   name: string,

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