@playfast/reform 0.1.0 → 1.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform",
   "playbook": "./playbook",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "The renderer-neutral core of the reform framework — typed, headless state, events, reducers, derived values, async/remote data, and compositions built on Effect.",
   "keywords": [

package/src/calc/calc.ts

@@ -8,6 +8,7 @@ import {
   wireSources,
 } from '../internal/sources'
 import { resolveScheduler } from '../internal/scheduler'
+import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { reuse } from '../internal/reuse'
 import { makeDerivedStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
@@ -93,6 +94,7 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
     calc.store,
     Effect.gen(function* () {
       const scheduler = yield* resolveScheduler
+      const instrumentation = yield* resolveInstrumentation
       const sources = yield* wireSources(calc.inputs, options.invalidateBy)
 
       // Memo cell: key and output captured together so reads are always
@@ -107,17 +109,27 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
         if (prev !== undefined && sameKey(key, prev.key)) {
           return prev.output
         }
+        // Span covers the projection AND the optional reuse walk — both are the
+        // calc's real per-recompute cost. Memo hits return above, uncounted.
+        // (`manifest.name`, not `.name` — a user subclass shadows the static.)
+        const end = instrumentation.calcRecomputed(calc.manifest.name)
         const fresh = compute(args)
         // With `reuse`, a recompute that lands value-equal to the previous
         // output returns the previous reference — the derived store's Equal
         // gate then wakes no subscriber at all.
         const output =
           options.reuse === true && prev !== undefined ? reuse(prev.output, fresh) : fresh
+        end()
         MutableRef.set(memo, { key, output })
         return output
       }
 
-      const derived = makeDerivedStore(recompute, sources.subscribe, scheduler)
+      const derived = makeDerivedStore(
+        recompute,
+        sources.subscribe,
+        scheduler,
+        stateUpdateHook(instrumentation, calc.manifest.name),
+      )
       yield* Effect.addFinalizer(() => Effect.sync(derived.unsubscribe))
       return derived.store
     }),

package/src/calc/calcFamily.ts

@@ -8,6 +8,7 @@ import {
   wireSources,
 } from '../internal/sources'
 import { resolveScheduler } from '../internal/scheduler'
+import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { makeDerivedStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 import { type FamilyOptions, type FamilyStore } from '../state/stateFamily'
@@ -115,6 +116,8 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
     family.store,
     Effect.gen(function* () {
       const scheduler = yield* resolveScheduler
+      const instrumentation = yield* resolveInstrumentation
+      const onOutputChange = stateUpdateHook(instrumentation, family.manifest.name)
       // Wired ONCE for the whole family — members share the sensing surface.
       const sources = yield* wireSources(family.inputs, options.invalidateBy)
       const entries = new Map<K, { readonly store: Store<Out>; readonly unsubscribe: () => void }>()
@@ -144,11 +147,13 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
           if (prev !== undefined && sameKey(memoKey, prev.key)) {
             return prev.output
           }
+          const end = instrumentation.calcRecomputed(family.manifest.name)
           const output = body(args)
+          end()
           MutableRef.set(memo, { key: memoKey, output })
           return output
         }
-        return makeDerivedStore(recompute, sources.subscribe, scheduler)
+        return makeDerivedStore(recompute, sources.subscribe, scheduler, onOutputChange)
       }
 
       // The `StateFamily` ref-count idiom: evict on the next microtask once a

package/src/channel/channel.ts

@@ -1,6 +1,7 @@
 import { Chunk, Context, type Duration, Effect, Layer, Match, Option, Queue, Stream } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
 import type { Tagged } from '../runtime/bus'
+import { resolveInstrumentation } from '../runtime/instrumentation'
 
 /**
  * How a channel schedules the procedure work routed to it. Channels generalize
@@ -217,6 +218,7 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
         return
       }
       const procedures = yield* Procedures
+      const instrumentation = yield* resolveInstrumentation
       const queue = yield* Queue.unbounded<Tagged>()
 
       // Run every procedure on THIS channel that handles the event. Read the live
@@ -232,7 +234,12 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
         return Effect.forEach(
           matching,
           (procedure) =>
-            procedure.run(event).pipe(
+            // The `procedureRun` span covers the whole body, success/failure/cancel
+            // alike (`ensuring` fires on all three).
+            Effect.sync(() => instrumentation.procedureRun(procedure.name, name, event._tag)).pipe(
+              Effect.flatMap((endSpan) =>
+                procedure.run(event).pipe(Effect.ensuring(Effect.sync(endSpan))),
+              ),
               Effect.tapErrorCause((cause) =>
                 Effect.logError(`reform: procedure on channel '${name}' failed`, cause),
               ),

package/src/index.ts

@@ -162,22 +162,49 @@ export { type SlotChild } from './compose/slot'
 
 // A scene bundles a composition with the closed wiring that runs it — the single
 // handle the react host, proofs, and the dev tool all consume.
-export { isScene, type MountedServices, type Scene, scene, seedScene } from './scene/scene'
+export {
+  isScene,
+  type MountedServices,
+  profiledScene,
+  type Scene,
+  scene,
+  sceneInstrumentation,
+  seedScene,
+} from './scene/scene'
 export type { SeedsOf } from './state/stateGroup'
 
 // Runtime surface for hosts (`@reform/react`) and headless tests.
-export { Bus, type Envelope, type Priority, publish, type Tagged } from './runtime/bus'
-export { Engine, type ReducerEntry, Reducers } from './runtime/loop'
+export { Bus, busLayer, type Envelope, type Priority, publish, type Tagged } from './runtime/bus'
+// The renderer-neutral scene runtime: hosts layer their lifecycle on top;
+// headless tests/proofs/drive scripts consume it directly.
+export {
+  type AppRuntime,
+  type FeatureMountHandlers,
+  makeAppRuntime,
+  type RuntimeHandle,
+} from './runtime/appRuntime'
+export { Engine, type ReducerEntry, Reducers, reducersLayer } from './runtime/loop'
+// The profiler SPI: synchronous hooks the engine calls on its hot paths, plus
+// the FiberRef seam `@playfast/reform-profiler` writes through (`profiledScene`).
+export {
+  CurrentInstrumentation,
+  type Instrumentation,
+  noopInstrumentation,
+  resolveInstrumentation,
+  type SpanEnd,
+} from './runtime/instrumentation'
 // The runtime-wide registry of live query handles. `AsyncCalc.invalidate` /
 // `AsyncCalc.refetch` and provider layers act on a query by name through it.
-export { Queries, type QueryHandle, type QueryRegistry } from './runtime/queries'
+export { Queries, queriesLayer, type QueryHandle, type QueryRegistry } from './runtime/queries'
 export {
   type ChannelClass,
   type ChannelPolicy,
   type ChannelRuntime,
   Channels,
+  channelsLayer,
   type ProcedureEntry,
   Procedures,
+  proceduresLayer,
 } from './channel/channel'
 export { CurrentTracker, type Subscribable, type Tracker } from './internal/track'
 export { CaptureSink, type CaptureSinkApi, type UiCapture } from './internal/capture'

package/src/internal/queryDriver.ts

@@ -14,6 +14,7 @@ import { type AnyAsyncData } from '../calc/asyncData'
 import { empty, type QueryState, toAsyncData } from '../calc/queryState'
 import { Queries, type QueryHandle } from '../runtime/queries'
 import { reuse } from './reuse'
+import { resolveInstrumentation } from '../runtime/instrumentation'
 import { resolveQueryStore } from './queryStore'
 import { resolveScheduler } from './scheduler'
 import {
@@ -139,6 +140,7 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
 ): Effect.Effect<QueryDriver<A, E>, never, InputStores<Inputs> | R | Scope.Scope> =>
   Effect.gen(function* () {
     const scheduler = yield* resolveScheduler
+    const instrumentation = yield* resolveInstrumentation
     const sources = yield* wireSources(options.inputs, options.invalidateBy)
     const extraKey = options.extraKey
     const persist = options.persist
@@ -272,9 +274,13 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
     // One run of the query, folded into the cell. A failure becomes `Error`; an
     // interrupt (latest-wins cancel) leaves the state untouched; a defect (a bug in
     // the body) is logged and isolated. A `Success` reports its generation through
-    // `onSettled` after the write, then persists (best-effort, trailing).
+    // `onSettled` after the write, then persists (best-effort, trailing). The
+    // `queryRun` span covers start → settle/cancel (`ensuring` fires on all three).
     const runQuery = (request: Request): Effect.Effect<void, never, R> =>
-      options.query(request.args).pipe(
+      Effect.sync(() => instrumentation.queryRun(options.name)).pipe(
+        Effect.flatMap((endSpan) =>
+          options.query(request.args).pipe(Effect.ensuring(Effect.sync(endSpan))),
+        ),
         Effect.tapDefect((defect) =>
           Effect.logError(`reform: ${options.label} '${options.name}' query defect`, defect),
         ),

package/src/internal/store.ts

@@ -30,7 +30,14 @@ export interface Store<in out A> extends Inspectable {
   subscribe(listener: () => void): () => void
 }
 
-export const makeStore = <A>(initial: A, scheduler: Scheduler = defaultScheduler): Store<A> => {
+/** Default change hook — a shared no-op so unprofiled stores pay one skipped call. */
+const noChange = (): void => {}
+
+export const makeStore = <A>(
+  initial: A,
+  scheduler: Scheduler = defaultScheduler,
+  onChange: () => void = noChange,
+): Store<A> => {
   // The store is a mutable reactive slot by design, so its value lives in a
   // `MutableRef` we update in place (no reassigned binding).
   const current = MutableRef.make(initial)
@@ -46,6 +53,7 @@ export const makeStore = <A>(initial: A, scheduler: Scheduler = defaultScheduler
       }
       MutableRef.set(current, next)
       MutableRef.update(version, (count) => count + 1)
+      onChange()
       scheduler.schedule(listeners)
     },
     subscribe: (listener) => {
@@ -74,6 +82,7 @@ export const makeDerivedStore = <A>(
   compute: () => A,
   subscribeUpstream: (onChange: () => void) => () => void,
   scheduler: Scheduler = defaultScheduler,
+  onOutputChange: () => void = noChange,
 ): { readonly store: Store<A>; readonly unsubscribe: () => void } => {
   const listeners = new Set<() => void>()
   const version = MutableRef.make(0)
@@ -86,6 +95,7 @@ export const makeDerivedStore = <A>(
     MutableRef.set(seen, { value: next })
     if (previous === undefined || !Equal.equals(previous.value, next)) {
       MutableRef.update(version, (count) => count + 1)
+      onOutputChange()
       scheduler.schedule(listeners)
     }
   }

package/src/runtime/appRuntime.ts

@@ -0,0 +1,174 @@
+import { Cause, Context, Effect, Exit, Layer, ManagedRuntime, Option, Scope } from 'effect'
+import { FeatureLoadFailed, forceSync } from '../internal/errors'
+import { type FeatureBinding, mountFeature } from '../feature/feature'
+import { type Node } from '../ui/node'
+import { type MountedServices, type Scene, sceneInstrumentation } from '../scene/scene'
+import { publish, type Priority, type Tagged } from './bus'
+import { type Instrumentation } from './instrumentation'
+
+// The renderer-neutral scene runtime: one `ManagedRuntime` over a scene's closed
+// layers, with the read/render/dispatch/feature-mount surface every host shares.
+// `@playfast/reform-react` builds its React lifecycle (StrictMode-deferred
+// dispose, providers) ON TOP of this; headless tests, proofs, and drive scripts
+// consume it directly — the "testing runtime" with no React and no harness.
+
+/** The lazy-feature lifecycle callbacks a host hands to `mountFeature`. */
+export interface FeatureMountHandlers {
+  readonly onLive: (runtime: RuntimeHandle) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+}
+
+/**
+ * The capabilities a host needs from a built reform runtime — what `Compose`
+ * (React) and the proof facade depend on. A feature mount yields a child handle
+ * over the feature's merged context, sharing the parent's render/dispatch.
+ */
+export interface RuntimeHandle {
+  /**
+   * Resolve any reform DI tag (a composition's mounted logic, a slot's wired
+   * child) from the app context. The mounted runtime provides every reform
+   * service, so this never fails for tags from the same app.
+   */
+  read<A>(tag: Context.Tag<A, A>): A
+  /** Run a fully-provided, synchronous render to its node (D2). */
+  runRender(effect: Effect.Effect<Node, never, never>): Node
+  /** Dispatch a runtime/boot event onto the bus. */
+  dispatch(priority: Priority, event: Tagged): void
+  /**
+   * Mount a feature against this runtime: load its module (lazy = dynamic import),
+   * build its `.live` layer on a fresh scope sharing this runtime's engine, and
+   * call `onLive` with a child runtime that reads the feature's composition/stores
+   * (and the shared services), or `onFailed` with a typed `FeatureLoadFailed`.
+   * Returns a disposer that closes the feature's scope — stopping its fibers and
+   * reclaiming its reducers/stores.
+   */
+  mountFeature(binding: FeatureBinding, handlers: FeatureMountHandlers): () => void
+  /**
+   * The scene's profiling hooks (`noopInstrumentation` unless `profileScene`d).
+   * On the handle (not only the app runtime) because render spans are recorded
+   * by whatever holds the handle — React `Compose`, the proof engine — and a
+   * feature's child handle must record into the same profiler as its parent.
+   */
+  readonly instrumentation: Instrumentation
+}
+
+/** A built scene runtime: the handle plus its boot/dispose lifecycle. */
+export interface AppRuntime extends RuntimeHandle {
+  /** Dispatch the scene's boot events, once — later calls are no-ops. */
+  boot(): void
+  /** Interrupt the runtime and latch the handle inert. Immediate and idempotent. */
+  dispose(): void
+  /** True once disposed, so a host can rebuild rather than reuse a dead runtime. */
+  isDisposed(): boolean
+}
+
+/**
+ * Build the concrete runtime over a `ManagedRuntime` made from a scene's closed
+ * layers. The mounted runtime provides every reform tag, so reading any one
+ * needs no further context; we erase the requirement the generic tag carries.
+ */
+export const makeAppRuntime = (scene: Scene): AppRuntime => {
+  const instrumentation = sceneInstrumentation(scene)
+  // A scene always provides at least one layer; merge them into the app layer.
+  const layer = scene.provide.reduce((accLayer, nextLayer) => Layer.merge(accLayer, nextLayer))
+  const runtime = ManagedRuntime.make(layer)
+  // The full app context (all services), captured once. A feature's `.live` layer
+  // is built against this so it shares the one engine (bus + registries). Typed as
+  // the host's `MountedServices` subset; at runtime it carries every service.
+  const rootContext = forceSync(() => runtime.runSync(Effect.context<MountedServices>()))
+
+  // Past actual dispose the `ManagedRuntime` is interrupted and every `runSync` /
+  // `runFork` against it throws `ManagedRuntime disposed`. A host can still render
+  // a tearing-down tree, and forked fibers (a RemoteState load, a boot dispatch)
+  // outlive the host cleanup — so the runtime is made inert past dispose instead
+  // of throwing into a render. A `const` latch mutated in place.
+  const status = { disposed: false, booted: false }
+
+  // A render is a self-contained `Effect<Node, never, never>` (no service needs),
+  // so once the managed runtime is gone it still runs on the default runtime —
+  // yielding a real node from the current store values, never a throw mid-render.
+  const runRender = (effect: Effect.Effect<Node, never, never>): Node =>
+    status.disposed ? Effect.runSync(effect) : runtime.runSync(effect)
+
+  // A dispatch past dispose has no live bus to reach; drop it.
+  const dispatch = (priority: Priority, event: Tagged): void => {
+    if (status.disposed) {
+      return
+    }
+    runtime.runFork(publish(priority, event))
+  }
+
+  // A child runtime over a feature's merged context (feature services + the shared
+  // engine). Reads resolve from that context; renders/dispatch share the
+  // inert-past-dispose helpers above.
+  const makeChildRuntime = (context: Context.Context<unknown>): RuntimeHandle => ({
+    read: <A>(tag: Context.Tag<A, A>): A => Context.unsafeGet(context, tag),
+    runRender,
+    dispatch,
+    mountFeature: (binding, handlers) => mountFeatureOnto(binding, handlers),
+    instrumentation,
+  })
+
+  const mountFeatureOnto = (
+    binding: FeatureBinding,
+    handlers: FeatureMountHandlers,
+  ): (() => void) => {
+    // Don't mount onto a runtime that's already torn down — the tree is unmounting.
+    if (status.disposed) {
+      return () => {}
+    }
+    const scope = Effect.runSync(Scope.make())
+    runtime.runFork(
+      mountFeature(binding, rootContext).pipe(
+        Effect.provideService(Scope.Scope, scope),
+        Effect.matchCause({
+          onFailure: (cause) =>
+            handlers.onFailed(
+              Option.getOrElse(Cause.failureOption(cause), () => new FeatureLoadFailed({ cause })),
+            ),
+          onSuccess: (context) => handlers.onLive(makeChildRuntime(context)),
+        }),
+      ),
+    )
+    return () => {
+      // The scope's finalizers (reducer/store reclaim) are self-contained, so when
+      // the managed runtime is already disposed they close on the default runtime
+      // rather than throwing through a dead `runFork`.
+      const close = Scope.close(scope, Exit.succeed(undefined))
+      if (status.disposed) {
+        Effect.runFork(close)
+      } else {
+        runtime.runFork(close)
+      }
+    }
+  }
+
+  const app: AppRuntime = {
+    // Read from the captured context (it carries every service), not
+    // `runtime.runSync(tag)`, so a read from a tearing-down tree can't throw
+    // `ManagedRuntime disposed` — and it drops the cast the runSync form needed.
+    read: <A>(tag: Context.Tag<A, A>): A => Context.unsafeGet(rootContext, tag),
+    runRender,
+    dispatch,
+    mountFeature: (binding, handlers) => mountFeatureOnto(binding, handlers),
+    boot: () => {
+      if (status.disposed || status.booted) {
+        return
+      }
+      status.booted = true
+      Option.fromNullable(scene.boot)
+        .pipe(Option.getOrElse((): ReadonlyArray<Tagged> => []))
+        .forEach((event) => dispatch('High', event))
+    },
+    dispose: () => {
+      if (status.disposed) {
+        return
+      }
+      status.disposed = true
+      void runtime.dispose()
+    },
+    isDisposed: () => status.disposed,
+    instrumentation,
+  }
+  return app
+}

package/src/runtime/instrumentation.test.ts

@@ -0,0 +1,303 @@
+import { expect, it } from '@effect/vitest'
+import { test } from 'vitest'
+import { Duration, Effect, Layer, ManagedRuntime, 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'
+
+// 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 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()
+
+    // 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))
+})
+
+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))
+})
+
+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
+    // 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 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))
+})
+
+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)
+    // 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))
+})
+
+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))
+})
+
+// ── 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 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 runtime = ManagedRuntime.make(layer)
+  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)
+
+  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()
+  }
+
+  // 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()
+  }
+})

package/src/runtime/instrumentation.ts

@@ -0,0 +1,93 @@
+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,
+  stateUpdated: () => {},
+  calcRecomputed: () => noopSpanEnd,
+  queryRun: () => noopSpanEnd,
+  procedureRun: () => noopSpanEnd,
+  uiRendered: () => noopSpanEnd,
+  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,
+): (() => void) =>
+  instrumentation === noopInstrumentation
+    ? noopSpanEnd
+    : () => instrumentation.stateUpdated(name)

package/src/runtime/loop.ts

@@ -7,6 +7,7 @@ import {
 } from '../channel/channel'
 import { notificationsLayer } from '../internal/scheduler'
 import { Bus, busLayer, type Envelope, type Tagged } from './bus'
+import { type Instrumentation, resolveInstrumentation } from './instrumentation'
 import { Queries, queriesLayer } from './queries'
 
 /**
@@ -94,16 +95,21 @@ const bucketOf = <V>(map: Map<string, Array<V>>, tag: string): Array<V> =>
 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)
 
@@ -119,6 +125,8 @@ const drain = Effect.gen(function* () {
   const reducers = yield* Reducers
   const { byName: channels } = yield* Channels
   const procedures = yield* Procedures
+  // Captured once at engine build; the noop instance costs nothing per frame.
+  const instrumentation = yield* resolveInstrumentation
   const subscription = yield* PubSub.subscribe(bus)
 
   yield* Effect.forkScoped(
@@ -141,12 +149,16 @@ const drain = Effect.gen(function* () {
         // procedure bodies (run later, off their channel fibers) see post-batch
         // state. No `yield*` in between, or the flush could fire early.
         const failures = yield* Effect.sync(() => {
+          const endFrame = instrumentation.frame(ordered.length)
+          ordered.forEach((envelope) =>
+            instrumentation.eventDispatched(envelope.event._tag, envelope.priority),
+          )
           // Isolate each fold: a synchronous throw in one reducer must not abandon
           // the rest of the frame nor (via the `forever` below) kill the drain fiber
           // and freeze the whole app. Collect failures here, log after the block.
           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
@@ -157,6 +169,7 @@ const drain = Effect.gen(function* () {
               channels.get(channelName)?.offer(envelope.event)
             })
           })
+          endFrame()
           return collected
         })
         yield* Effect.forEach(

package/src/scene/scene.ts

@@ -5,6 +5,11 @@ import type { EventOf } from '../event/event'
 import { CurrentSeedOverrides } from '../internal/seeds'
 import type { SeedsOf } from '../state/stateGroup'
 import type { Bus } from '../runtime/bus'
+import {
+  CurrentInstrumentation,
+  type Instrumentation,
+  noopInstrumentation,
+} from '../runtime/instrumentation'
 
 // A scene is a VALUE — a composition plus the closed wiring that runs it: the
 // layers that supply its logic/views (each seeding its own live state) and the
@@ -43,6 +48,14 @@ export interface Scene<
   /** Events dispatched once the runtime is live (e.g. `RequestedTodos`). */
   // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional boot read as `scene.boot ?? []` across non-batch hosts (drive/proof/remote/react/editor); Option would break them
   readonly boot?: ReadonlyArray<BootEvent>
+  /**
+   * The profiler hooks this scene records into, when profiled (`profiledScene`).
+   * Hosts read it via {@link sceneInstrumentation} to time renders — kept on the
+   * scene (not only inside the layers) because render spans live in the HOST
+   * (React `Compose`, the proof engine), outside the runtime's layer context.
+   */
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional carrier like `boot`; absent on every unprofiled scene, so Option would tax all authoring call sites
+  readonly instrumentation?: Instrumentation
 }
 
 /** Closed wiring + optional boot events handed to {@link scene}. */
@@ -88,6 +101,27 @@ export const seedScene = <C extends UiContract, S extends ReadonlyArray<unknown>
     ? base
     : { ...base, provide: base.provide.map(Layer.locally(CurrentSeedOverrides, seeds)) }
 
+/**
+ * Overlay profiler hooks onto a CLOSED scene — the profiling analog of
+ * {@link seedScene}. Wraps each provided layer with
+ * `Layer.locally(CurrentInstrumentation, instr)` so engine/state/calc layers
+ * capture `instr` at build time, and carries `instr` on the scene so hosts can
+ * time renders. Scenes stay closed; production wiring never calls this —
+ * `@playfast/reform-profiler`'s `profileScene` is the intended caller.
+ */
+export const profiledScene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
+  base: Scene<C, S>,
+  instrumentation: Instrumentation,
+): Scene<C, S> => ({
+  ...base,
+  instrumentation,
+  provide: base.provide.map(Layer.locally(CurrentInstrumentation, instrumentation)),
+})
+
+/** The instrumentation a host records render spans into — noop when unprofiled. */
+export const sceneInstrumentation = (candidate: Scene): Instrumentation =>
+  candidate.instrumentation ?? noopInstrumentation
+
 /** Reflection guard: is this exported value a scene? */
 export const isScene = (candidate: unknown): candidate is Scene =>
   typeof candidate === 'object' &&

package/src/state/state.ts

@@ -2,6 +2,7 @@ import { Context, Effect, FiberRef, Layer, Option, Schema } from 'effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import { resolveScheduler } from '../internal/scheduler'
 import { CurrentSeedOverrides } from '../internal/seeds'
+import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { claimStateTag } from '../internal/stateRegistry'
 import { makeStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
@@ -89,7 +90,9 @@ export const live = <S extends AnyState>(
 ): Layer.Layer<Store<StateValue<S>>> =>
   Layer.effect(
     state.store,
-    Effect.zipWith(resolveScheduler, resolveSeed(state, initial), (scheduler, seed) =>
-      makeStore(seed, scheduler),
+    Effect.all([resolveScheduler, resolveSeed(state, initial), resolveInstrumentation]).pipe(
+      Effect.map(([scheduler, seed, instrumentation]) =>
+        makeStore(seed, scheduler, stateUpdateHook(instrumentation, state.manifest.name)),
+      ),
     ),
   )

package/src/state/stateFamily.ts

@@ -2,6 +2,7 @@ import { Context, Effect, Layer, Option, type Schema } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
 import { resolveScheduler, type Scheduler } from '../internal/scheduler'
 import { claimStateTag } from '../internal/stateRegistry'
+import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { makeStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 
@@ -50,6 +51,7 @@ const makeFamilyStore = <K, V>(
   seed: (key: K) => V,
   scheduler: Scheduler,
   options: FamilyOptions = {},
+  onChange: () => void = () => {},
 ): FamilyStore<K, V> => {
   const entries = new Map<K, Store<V>>()
   const evictWhenUnused = options.evictWhenUnused === true
@@ -94,7 +96,7 @@ const makeFamilyStore = <K, V>(
       if (existing !== undefined) {
         return existing
       }
-      const base = makeStore(seed(key), scheduler)
+      const base = makeStore(seed(key), scheduler, onChange)
       const created = evictWhenUnused ? refCounted(key, base) : base
       entries.set(key, created)
       return created
@@ -185,6 +187,13 @@ export const live = <N extends string, K, V>(
   const seed: (key: K) => V = typeof initial === 'function' ? (initial as (key: K) => V) : () => initial
   return Layer.effect(
     family.store,
-    Effect.map(resolveScheduler, (scheduler) => makeFamilyStore<K, V>(seed, scheduler, options)),
+    Effect.zipWith(resolveScheduler, resolveInstrumentation, (scheduler, instrumentation) =>
+      makeFamilyStore<K, V>(
+        seed,
+        scheduler,
+        options,
+        stateUpdateHook(instrumentation, family.manifest.name),
+      ),
+    ),
   )
 }