@playfast/reform 1.1.1 → 1.2.1

package/src/runtime/instrumentation.test.ts

@@ -1,16 +1,13 @@
-import { expect, it } from "@effect/vitest";
-import { Duration, Effect, Layer, Schema as S } from "effect";
+import { expect, it } from '@effect/vitest'
+import { Effect, Layer, Schema as S } from 'effect'
 import {
   AsyncCalc,
   Calc,
   Channel,
   Composition,
-  CurrentInstrumentation,
   Engine,
   Event,
-  type Instrumentation,
   mount,
-  noopInstrumentation,
   type Priority,
   Procedure,
   profiledScene,
@@ -23,64 +20,66 @@ import {
   StateGroup,
   Ui,
   ui,
-} from "../index";
-
-const tick = (ms = 20) => Effect.sleep(Duration.millis(ms));
+} from '../index'
+import { makeFlightGate, until } from '../testkit/flight.testkit'
+import {
+  CurrentInstrumentation,
+  type Instrumentation,
+  noopInstrumentation,
+} from './instrumentation'
 
 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,
@@ -91,186 +90,207 @@ const makeRecorder = () => {
     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* until(
+      () => recorder.ends.frame,
+      (n) => n >= 1,
+    )
 
-      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));
-  },
-);
+    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", {
+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 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));
-});
+    yield* publish('High', Event.construct(Wrote, { to: 7 }))
+    // The state update, if any, is reported inside the reducer's span.
+    yield* until(
+      () => recorder.ends.reducer,
+      (n) => n >= 1,
+    )
+    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;
-    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);
-    expect(recorder.states).toContain("InstrDoubled");
-  }).pipe(Effect.provide(TestLayer));
-});
+    const source = yield* StateGroup.select(Inputs, 'instr-calc-count').store
+    source.set(6)
+    // Wait on the recompute itself — pulling `get()` would recompute under the
+    // poller and hide the propagation that reports the derived state update.
+    yield* until(
+      () => recorder.calcs.length,
+      (n) => n === builds + 1,
+    )
+    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 gate = makeFlightGate()
   const FetchedLive = AsyncCalc.live(Fetched, {
-    query: (inputs) =>
-      Effect.succeed(inputs["instr-query-count"] * 2).pipe(
-        Effect.delay(Duration.millis(5)),
-      ),
-  });
+    query: (inputs) => gate.through(Effect.succeed(inputs['instr-query-count'] * 2)),
+  })
 
   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);
-    expect(store.get()._tag).toBe("Success");
-    expect(recorder.queries).toEqual(["InstrFetched"]);
-    expect(recorder.ends.query).toBe(1);
-  }).pipe(Effect.provide(TestLayer));
-});
+    yield* gate.hold
+    const store = yield* Fetched.store
+    // Parked mid-flight: the span is open, so its end must not have run yet.
+    yield* gate.awaitEntry(1)
+    expect(recorder.queries).toEqual(['InstrFetched'])
+    expect(recorder.ends.query).toBe(0)
 
-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", {
+    yield* gate.release
+    yield* until(
+      () => store.get()._tag,
+      (tag) => tag === 'Success',
+    )
+    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 gate = makeFlightGate()
   const WorkLive = Procedure.live(Work, function* () {
-    yield* tick(5);
-  });
+    yield* gate.through(Effect.void)
+  })
 
   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* gate.hold
+    yield* publish('Normal', Event.construct(Kicked, {}))
+    // Parked mid-run: the span opened with its channel and trigger, and stays open.
+    yield* gate.awaitEntry(1)
     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(0)
+
+    yield* gate.release
+    yield* until(
+      () => recorder.ends.procedure,
+      (n) => n >= 1,
+    )
+    expect(recorder.ends.procedure).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
 
-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,
-}) {}
+})<SceneRoot>() {}
 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(
@@ -282,43 +302,42 @@ const SceneApp = SceneRootLive.pipe(
   Layer.provideMerge(
     Layer.mergeAll(SceneBumpLive).pipe(
       Layer.provideMerge(
-        Layer.mergeAll(
-          Engine,
-          StateGroup.live(SceneStates, { "instr-scene-count": 0 }),
-        ),
+        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 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 };
-};
+    // Each run builds its own state store, so the fold itself is the barrier —
+    // it settles whether or not the run is being recorded.
+    const count = yield* StateGroup.select(SceneStates, 'instr-scene-count').store
+    yield* publish('High', Event.construct(SceneBumped, {}))
+    yield* until(
+      () => count.get(),
+      (n) => n === 1,
+    )
+  })
+  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);
+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);
-    }),
-);
+    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

@@ -27,18 +27,13 @@ export const noopInstrumentation: Instrumentation = {
   frame: () => noopSpanEnd,
 }
 
-export const CurrentInstrumentation: FiberRef.FiberRef<Instrumentation> =
-  GlobalValue.globalValue(Symbol.for('reform/CurrentInstrumentation'), () =>
-    FiberRef.unsafeMake<Instrumentation>(noopInstrumentation),
-  )
+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)
+export const stateUpdateHook = (instrumentation: Instrumentation, name: string): (() => void) =>
+  instrumentation === noopInstrumentation ? noopSpanEnd : () => instrumentation.stateUpdated(name)