@playfast/reform 0.0.5 → 0.0.8

package/src/remote/remoteState.typecheck.ts

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

package/src/runtime/bus.ts

@@ -22,15 +22,19 @@ export interface Envelope {
   readonly event: Tagged
 }
 
+const BusBase: Context.TagClass<Bus, 'reform/Bus', PubSub.PubSub<Envelope>> = Context.Tag(
+  'reform/Bus',
+)<Bus, PubSub.PubSub<Envelope>>()
+
 /** The single dispatch bus: an unbounded PubSub fanned out to the loop and procedures. */
-export class Bus extends Context.Tag('reform/Bus')<Bus, PubSub.PubSub<Envelope>>() {}
+export class Bus extends BusBase {}
 
 // Unbounded so `publish` never suspends: UI triggers dispatch synchronously
 // (`Runtime.runSync`, no fiber fork per event), and an event storm can't apply
 // backpressure to the UI thread. The single drain loop empties the bus every
 // microtask, so it does not accumulate. Swap to `PubSub.dropping(N)` if bounded
 // memory is preferred over never dropping (publish stays synchronous either way).
-export const busLayer = Layer.scoped(Bus, PubSub.unbounded<Envelope>())
+export const busLayer: Layer.Layer<Bus> = Layer.scoped(Bus, PubSub.unbounded<Envelope>())
 
 export const publish = (priority: Priority, event: Tagged): Effect.Effect<void, never, Bus> =>
   Effect.flatMap(Bus, (bus) => PubSub.publish(bus, { priority, event }))

package/src/runtime/hardening.test.ts

@@ -0,0 +1,69 @@
+import { expect, it } from '@effect/vitest'
+import { Cause, Duration, Effect, Exit, Layer, LogLevel, Logger, Schema as S } from 'effect'
+import { Channel, Engine, Event, publish, Reducer, State } from '../index'
+
+// Robustness guards for the drain loop and registries: a buggy reducer must not
+// take down the bus, and a name clash that would silently drop a registration
+// must be rejected.
+
+it.live('a reducer that throws is isolated; the loop keeps draining', () => {
+  class Counter extends State.make('counter', S.Number) {}
+  class Good extends Event.make('Good', S.Struct({})) {}
+  class Bad extends Event.make('Bad', S.Struct({})) {}
+  class GoodReducer extends Reducer.make('GoodReducer', { states: [Counter], events: [Good] }) {}
+  class BadReducer extends Reducer.make('BadReducer', { states: [Counter], events: [Bad] }) {}
+  const GoodLive = Reducer.live(GoodReducer, (n) => n + 1)
+  const BadLive = Reducer.live(BadReducer, () => {
+    throw new Error('boom')
+  })
+
+  const TestLayer = Layer.mergeAll(GoodLive, BadLive).pipe(
+    Layer.provideMerge(Layer.mergeAll(State.live(Counter, 0), Engine)),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Counter.store
+
+    // A fold that throws is caught and logged — the drain fiber survives.
+    yield* publish('Normal', Event.construct(Bad, {}))
+    yield* Effect.sleep(Duration.millis(10))
+    expect(store.get()).toBe(0)
+
+    // A later, healthy event still processes: the bus did not go deaf.
+    yield* publish('Normal', Event.construct(Good, {}))
+    yield* Effect.sleep(Duration.millis(10))
+    expect(store.get()).toBe(1)
+  }).pipe(
+    Effect.provide(TestLayer),
+    // The isolated failure logs an error; silence it so the passing test is quiet.
+    Logger.withMinimumLogLevel(LogLevel.None),
+  )
+})
+
+it.effect('two different channels registered under one name are rejected', () => {
+  class Merge extends Channel.make('Dup', { policy: { _tag: 'merge' } }) {}
+  class Latest extends Channel.make('Dup', { policy: { _tag: 'latest' } }) {}
+  const layer = Layer.mergeAll(Channel.live(Merge), Channel.live(Latest)).pipe(
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const exit = yield* Effect.scoped(Layer.build(layer)).pipe(Effect.exit)
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      expect(Cause.pretty(exit.cause)).toContain('duplicate Channel')
+    }
+  })
+})
+
+it.effect('the same channel registered twice is idempotent (shared lane)', () => {
+  class Lane extends Channel.make('Lane', { policy: { _tag: 'exclusive' } }) {}
+  const layer = Layer.mergeAll(Channel.live(Lane), Channel.live(Lane)).pipe(
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const exit = yield* Effect.scoped(Layer.build(layer)).pipe(Effect.exit)
+    expect(Exit.isSuccess(exit)).toBe(true)
+  })
+})

package/src/runtime/loop.test.ts

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

package/src/runtime/loop.ts

@@ -39,7 +39,9 @@ export interface ReducerRegistry {
   readonly unregister: (entry: ReducerEntry) => void
 }
 
-export class Reducers extends Context.Tag('reform/Reducers')<Reducers, ReducerRegistry>() {}
+const ReducersBase: Context.TagClass<Reducers, 'reform/Reducers', ReducerRegistry> =
+  Context.Tag('reform/Reducers')<Reducers, ReducerRegistry>()
+export class Reducers extends ReducersBase {}
 
 /** Drop an item from a `Map<string, Array>` bucket, pruning the key when it empties. */
 const dropFromBuckets = <T>(map: Map<string, Array<T>>, key: string, item: T): void => {
@@ -72,7 +74,7 @@ const makeReducerRegistry = (): ReducerRegistry => {
   }
 }
 
-export const reducersLayer = Layer.sync(Reducers, makeReducerRegistry)
+export const reducersLayer: Layer.Layer<Reducers> = Layer.sync(Reducers, makeReducerRegistry)
 
 /** High before Normal; within a priority class, dispatch order is preserved. */
 const rank = (priority: Envelope['priority']): number => (priority === 'High' ? 0 : 1)

package/src/scene/seedScene.test.ts

@@ -0,0 +1,169 @@
+import { Effect, Layer, ManagedRuntime, Schema as S } from 'effect'
+import { expect, test } from 'vitest'
+import {
+  type CaptureSinkApi,
+  CaptureSink,
+  Composition,
+  Engine,
+  Event,
+  provide,
+  publish,
+  Reducer,
+  type RenderEnv,
+  type Scene,
+  scene,
+  seedScene,
+  State,
+  StateGroup,
+  Ui,
+  ui,
+} from '../index'
+
+// `seedScene` is the tooling seam over CLOSED scenes: the app bundle below seeds
+// `count: 1` itself (no open store), and the overlay must reach the nested
+// `State.live` through `Layer.locally(CurrentSeedOverrides, …)` on the scene's
+// pre-composed layers. The harness mirrors the dev-tool preview: merge the
+// scene's `provide`, mount it in a ManagedRuntime, and read the root
+// composition's rendered props through the headless CaptureSink.
+
+class CountState extends State.make('count', S.Number) {}
+class MiniStates extends StateGroup.make(CountState) {}
+
+class Bumped extends Event.make('Bumped', S.Struct({})) {}
+
+class BumpReducer extends Reducer.make('BumpReducer', {
+  states: [CountState],
+  events: [Bumped],
+}) {}
+const BumpReducerLive = Reducer.live(BumpReducer, (n) => n + 1)
+
+class CounterUi extends ui('Counter')<{ props: { count: number } }>() {}
+class Counter extends Composition.make('Counter', {
+  title: 'Counter',
+  states: [MiniStates],
+  events: [Bumped],
+  ui: CounterUi,
+}) {}
+const CounterLive = Composition.live(Counter, function* () {
+  const count = yield* StateGroup.select(MiniStates, 'count')
+  const view = yield* CounterUi
+  return view({ count })
+})
+
+// The closed app layer a scene provides: views + logic + Engine, with the state
+// group seeding its AUTHORED value `count: 1` itself.
+const presentations = provide(CounterUi, Ui.make(CounterUi, () => null))
+const Views = CounterLive.pipe(Layer.provideMerge(presentations))
+const Logic = Layer.mergeAll(BumpReducerLive).pipe(
+  Layer.provideMerge(Layer.mergeAll(Engine, StateGroup.live(MiniStates, { count: 1 }))),
+)
+const MiniApp = Views.pipe(Layer.provideMerge(Logic))
+
+const CounterScene = scene(Counter, { provide: [MiniApp] })
+
+const headlessEnv: RenderEnv = {
+  props: {},
+  tracker: { add: () => {} },
+  slots: { slot: () => () => null },
+}
+
+// One ManagedRuntime per scene under test, with its own capture cell so two
+// runtimes in the same test (the no-leakage case) cannot bleed into each other.
+// Each `read` re-renders the root composition, repopulating the cell from the
+// stores that runtime actually built.
+const makeHarness = (s: Scene) => {
+  const captured: { count: number } = { count: -1 }
+  const sink: CaptureSinkApi = {
+    record: (capture) => {
+      const props = capture.props
+      if (
+        typeof props === 'object' &&
+        props !== null &&
+        'count' in props &&
+        typeof props.count === 'number'
+      ) {
+        captured.count = props.count
+      }
+    },
+  }
+  const layer = s.provide
+    .reduce((a, b) => Layer.merge(a, b))
+    .pipe(Layer.provideMerge(Layer.succeed(CaptureSink, sink)))
+  const runtime = ManagedRuntime.make(layer)
+  const read = Effect.flatMap(Counter.tag, (c) =>
+    Composition.render(c, headlessEnv).pipe(Effect.map(() => captured.count)),
+  )
+  return { runtime, read }
+}
+
+// Drive a read until a predicate holds, handing forked fibers the scheduler.
+const waitUntil = <A, R>(
+  read: Effect.Effect<A, never, R>,
+  pred: (a: A) => boolean,
+  rounds = 1000,
+): Effect.Effect<A, never, R> =>
+  Effect.flatMap(read, (a) =>
+    pred(a) || rounds <= 0
+      ? Effect.succeed(a)
+      : Effect.flatMap(Effect.yieldNow(), () => waitUntil(read, pred, rounds - 1)),
+  )
+
+test('a seeded scene boots its store from the override', async () => {
+  const { runtime, read } = makeHarness(seedScene(CounterScene, { count: 5 }))
+  try {
+    expect(await runtime.runPromise(read)).toBe(5)
+  } finally {
+    await runtime.dispose()
+  }
+})
+
+test('the live reducer drives the SAME overridden store', async () => {
+  const { runtime, read } = makeHarness(seedScene(CounterScene, { count: 5 }))
+  try {
+    const next = await runtime.runPromise(
+      Effect.gen(function* () {
+        expect(yield* read).toBe(5)
+        yield* publish('High', Event.construct(Bumped, {}))
+        return yield* waitUntil(read, (n) => n === 6)
+      }),
+    )
+    expect(next).toBe(6)
+  } finally {
+    await runtime.dispose()
+  }
+})
+
+test('an absent key leaves the authored seed in place', async () => {
+  const { runtime, read } = makeHarness(seedScene(CounterScene, { other: 1 }))
+  try {
+    expect(await runtime.runPromise(read)).toBe(1)
+  } finally {
+    await runtime.dispose()
+  }
+})
+
+test('a schema-invalid override falls back to the authored seed', async () => {
+  const { runtime, read } = makeHarness(seedScene(CounterScene, { count: 'not-a-number' }))
+  try {
+    expect(await runtime.runPromise(read)).toBe(1)
+  } finally {
+    await runtime.dispose()
+  }
+})
+
+test('seeding does not leak into the original scene', async () => {
+  const seeded = makeHarness(seedScene(CounterScene, { count: 5 }))
+  try {
+    expect(await seeded.runtime.runPromise(seeded.read)).toBe(5)
+  } finally {
+    await seeded.runtime.dispose()
+  }
+  // Building the ORIGINAL scene's layers again boots from the authored seed —
+  // the overlay lives only on the seeded variant's wrapped layers.
+  const original = makeHarness(CounterScene)
+  try {
+    expect(await original.runtime.runPromise(original.read)).toBe(1)
+  } finally {
+    await original.runtime.dispose()
+  }
+})

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 { claimStateTag } from '../internal/stateRegistry'
 import { makeStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 
@@ -40,7 +41,9 @@ export const make = <const N extends string, A>(
   schema: Schema.Schema<A, any>,
   options: StateOptions = {},
 ): StateClass<N, A> => {
-  const store = Context.GenericTag<Store<A>, Store<A>>(`reform/state/${name}`)
+  const identifier = `reform/state/${name}`
+  claimStateTag(identifier)
+  const store = Context.GenericTag<Store<A>, Store<A>>(identifier)
   const manifest: StateManifest<N, A> = {
     kind: 'State',
     name,