@playfast/reform 1.1.1 → 1.2.1

package/src/runtime/loop.test.ts

@@ -1,6 +1,7 @@
 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'
+import { makeFlightGate, until } from '../testkit/flight.testkit'
 
 it.live('a frame of events drains in one pass with a single notification flush', () => {
   class Counter extends State.make('counter', S.Number) {}
@@ -22,7 +23,11 @@ it.live('a frame of events drains in one pass with a single notification flush',
     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))
+    // The flush is the frame's last act, so one notification means the fold is done.
+    yield* until(
+      () => notifications.n,
+      (n) => n >= 1,
+    )
 
     expect(store.get()).toBe(3)
     expect(notifications.n).toBe(1)
@@ -34,11 +39,12 @@ it.live('an exclusive channel serializes procedures that share it', () => {
   class StartB extends Event.make('StartB', S.Struct({})) {}
   class Exclusive extends Channel.make('Exclusive', { policy: { _tag: 'exclusive' } }) {}
 
+  const gate = makeFlightGate()
   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))
+    yield* gate.through(Effect.void)
     concurrency.active -= 1
   }
 
@@ -52,9 +58,20 @@ it.live('an exclusive channel serializes procedures that share it', () => {
   )
 
   return Effect.gen(function* () {
+    // Parking the first run IS the overlap: a shared lane that is not exclusive
+    // would start the second procedure while the first sits at the gate.
+    yield* gate.hold
     yield* publish('Normal', Event.construct(StartA, {}))
     yield* publish('Normal', Event.construct(StartB, {}))
-    yield* Effect.sleep(Duration.millis(60))
+    yield* gate.awaitEntry(1)
+    expect(gate.entered()).toBe(1)
+
+    yield* gate.release
+    yield* gate.awaitEntry(2)
+    yield* until(
+      () => concurrency.active,
+      (active) => active === 0,
+    )
     expect(concurrency.max).toBe(1)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -79,7 +96,11 @@ it.live('two procedures sharing a channel each run once for one shared event', (
 
   return Effect.gen(function* () {
     yield* publish('High', Event.construct(Shared, {}))
-    yield* Effect.sleep(Duration.millis(20))
+    yield* until(
+      () => runs.a + runs.b,
+      (total) => total >= 2,
+    )
+    // A duplicated offer would land in the same frame and double one of them.
     expect(runs.a).toBe(1)
     expect(runs.b).toBe(1)
   }).pipe(Effect.provide(TestLayer))
@@ -126,10 +147,12 @@ it.live('a reducer ignores events outside its declared set (no-op)', () => {
   return Effect.gen(function* () {
     const store = yield* Counter.store
     yield* publish('Normal', Event.construct(Unrelated, {}))
-    yield* Effect.sleep(Duration.millis(10))
-    expect(store.get()).toBe(0)
     yield* publish('Normal', Event.construct(Bump, {}))
-    yield* Effect.sleep(Duration.millis(10))
+    yield* until(
+      () => store.get(),
+      (n) => n > 0,
+    )
+    // Both events fold in one frame: a reducer that also took Unrelated reads 2.
     expect(store.get()).toBe(1)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -159,3 +182,57 @@ it.effect('a latest channel cancels the in-flight run when a new event arrives',
     expect(counts.completed).toBe(1)
   }).pipe(Effect.provide(TestLayer))
 })
+
+it.live('a fold returning the previous reference keeps the exact store value', () => {
+  const Viewer = S.Union(
+    S.TaggedStruct('Closed', {}),
+    S.TaggedStruct('Open', { revision: S.Number }),
+  )
+  class ViewerState extends State.make('viewer', Viewer) {}
+  class Marker extends State.make('marker', S.Number) {}
+  class Poked extends Event.make('Poked', S.Struct({})) {}
+  class PokeReducer extends Reducer.make('PokeReducer', {
+    states: [ViewerState],
+    events: [Poked],
+  }) {}
+  // Closed is a fixpoint: the fold hands back the previous reference untouched.
+  const PokeReducerLive = Reducer.live(PokeReducer, (viewer) =>
+    viewer._tag === 'Open' ? { ...viewer, revision: viewer.revision + 1 } : viewer,
+  )
+  class MarkReducer extends Reducer.make('MarkReducer', {
+    states: [Marker],
+    events: [Poked],
+  }) {}
+  const MarkReducerLive = Reducer.live(MarkReducer, (n) => n + 1)
+
+  const TestLayer = Layer.mergeAll(PokeReducerLive, MarkReducerLive).pipe(
+    Layer.provideMerge(
+      Layer.mergeAll(State.live(ViewerState, { _tag: 'Closed' }), State.live(Marker, 0), Engine),
+    ),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* ViewerState.store
+    const marker = yield* Marker.store
+    const before = store.get()
+    const notifications = { n: 0 }
+    const flushed = { n: 0 }
+    store.subscribe(() => {
+      notifications.n += 1
+    })
+    marker.subscribe(() => {
+      flushed.n += 1
+    })
+    yield* publish('Normal', Event.construct(Poked, {}))
+    // The marker folds on the same event and shares the scheduler's flush: once
+    // its listener fires, a viewer notification would have run in that batch too.
+    yield* until(
+      () => flushed.n,
+      (n) => n >= 1,
+    )
+    // Reference identity is the repaint signal: an unchanged fold must not be
+    // re-decoded into a fresh, structurally-equal value that wakes subscribers.
+    expect(store.get()).toBe(before)
+    expect(notifications.n).toBe(0)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/runtime/loop.ts

@@ -1,10 +1,6 @@
 import { Array as Arr, Cause, Chunk, Context, Effect, Layer, Option, PubSub, Queue } from 'effect'
-import {
-  Channels,
-  channelsLayer,
-  Procedures,
-  proceduresLayer,
-} from '../channel/channel'
+import { Channels, channelsLayer, Procedures, proceduresLayer } from '../channel/channel'
+import { makeBucketCache } from '../internal/bucketCache'
 import { notificationsLayer } from '../internal/scheduler'
 import { Bus, busLayer, type Envelope, type Tagged } from './bus'
 import { enforceBudget, makeTickCounter, resolveCurrentEventBudget } from './eventBudget'
@@ -19,56 +15,78 @@ export interface ReducerEntry {
 
 export interface ReducerRegistry {
   readonly entries: Array<ReducerEntry>
-  readonly byTag: Map<string, Array<ReducerEntry>>
+  readonly byName: Map<string, Set<ReducerEntry>>
+  readonly byTag: Map<string, Set<ReducerEntry>>
+  readonly tagged: (tag: string) => ReadonlyArray<ReducerEntry>
   readonly register: (entry: ReducerEntry) => void
   readonly unregister: (entry: ReducerEntry) => void
 }
 
-const ReducersBase: Context.TagClass<Reducers, 'reform/Reducers', ReducerRegistry> =
-  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 {}
 
-const dropFromBuckets = <T>(map: Map<string, Array<T>>, key: string, target: T): void => {
+const dropFromBuckets = <T>(map: Map<string, Set<T>>, key: string, target: T): void => {
   const bucket = map.get(key)
   if (bucket === undefined) {
     return
   }
-  const next = bucket.filter((entry) => entry !== target)
-  if (next.length === 0) {
+  bucket.delete(target)
+  if (bucket.size === 0) {
     map.delete(key)
-  } else {
-    map.set(key, next)
   }
 }
 
 const makeReducerRegistry = (): ReducerRegistry => {
-  const byTag = new Map<string, Array<ReducerEntry>>()
-  const state: { entries: Array<ReducerEntry> } = { entries: [] }
+  const entries = new Set<ReducerEntry>()
+  const byName = new Map<string, Set<ReducerEntry>>()
+  const byTag = new Map<string, Set<ReducerEntry>>()
+  const tagged = makeBucketCache(byTag)
+  const snapshot: { value: Option.Option<Array<ReducerEntry>> } = {
+    value: Option.some([]),
+  }
   return {
     get entries() {
-      return state.entries
+      return Option.getOrElse(snapshot.value, () => {
+        const current = Array.from(entries)
+        snapshot.value = Option.some(current)
+        return current
+      })
     },
+    byName,
     byTag,
+    tagged: tagged.read,
     register: (entry) => {
-      state.entries = [...state.entries, entry]
+      entries.add(entry)
+      snapshot.value = Option.none()
+      getOrCreateBucket(byName, entry.name).add(entry)
       entry.handles.forEach((tag) => {
-        const bucket = byTag.get(tag)
-        if (bucket === undefined) {
-          byTag.set(tag, [entry])
-        } else {
-          byTag.set(tag, [...bucket, entry])
-        }
+        getOrCreateBucket(byTag, tag).add(entry)
+        tagged.invalidate(tag)
       })
     },
     unregister: (entry) => {
-      state.entries = state.entries.filter((existing) => existing !== entry)
-      entry.handles.forEach((tag) => dropFromBuckets(byTag, tag, entry))
+      entries.delete(entry)
+      snapshot.value = Option.none()
+      dropFromBuckets(byName, entry.name, entry)
+      entry.handles.forEach((tag) => {
+        dropFromBuckets(byTag, tag, entry)
+        tagged.invalidate(tag)
+      })
     },
   }
 }
 
-const bucketOf = <V>(map: Map<string, Array<V>>, tag: string): Array<V> =>
-  Option.getOrElse(Option.fromNullable(map.get(tag)), (): Array<V> => [])
+const getOrCreateBucket = <T>(map: Map<string, Set<T>>, key: string): Set<T> => {
+  const existing = map.get(key)
+  if (existing !== undefined) {
+    return existing
+  }
+  const created = new Set<T>()
+  map.set(key, created)
+  return created
+}
 
 const isolateApply = (
   reducer: ReducerEntry,
@@ -78,9 +96,10 @@ const isolateApply = (
   const end = instrumentation.reducerRun(reducer.name, event._tag)
   return Effect.runSync(
     Effect.match(
-      Effect.try({ try: () => reducer.apply(event), catch: (error) => error }).pipe(
-        Effect.ensuring(Effect.sync(end)),
-      ),
+      Effect.try({
+        try: () => reducer.apply(event),
+        catch: (error) => error,
+      }).pipe(Effect.ensuring(Effect.sync(end))),
       {
         onFailure: (error) => Option.some({ event, error }),
         onSuccess: () => Option.none(),
@@ -91,7 +110,7 @@ const isolateApply = (
 
 export const reducersLayer: Layer.Layer<Reducers> = Layer.sync(Reducers, makeReducerRegistry)
 
-// High before Normal; partition preserves intra-priority dispatch order
+// Partitioning keeps dispatch order stable within each priority.
 const rank = (priority: Envelope['priority']): number => (priority === 'High' ? 0 : 1)
 
 const drain = Effect.gen(function* () {
@@ -100,8 +119,8 @@ const drain = Effect.gen(function* () {
   const { byName: channels } = yield* Channels
   const procedures = yield* Procedures
   const instrumentation = yield* resolveInstrumentation
-  // One counter per engine: feature child runtimes share the app budget
   const budget = yield* resolveCurrentEventBudget
+  // Child feature runtimes share this engine-level counter with the root.
   const counter = makeTickCounter(budget)
   const subscription = yield* PubSub.subscribe(bus)
 
@@ -115,25 +134,25 @@ const drain = Effect.gen(function* () {
         const [high, normal] = Arr.partition(frame, (envelope) => rank(envelope.priority) !== 0)
         const ordered = [...high, ...normal]
 
-        // Budget before folding — EventLoopOverflow is this tick's only typed failure
+        // Check before folding so runaway frames stop at the hard limit.
         const sample = yield* Effect.sync(() => counter.add(ordered.length))
         yield* enforceBudget(budget, sample)
 
-        // Sync block: coalesce reducer writes into one flush; no yield* mid-frame
+        // One synchronous block coalesces reducer writes into a single flush.
         const failures = yield* Effect.sync(() => {
           const endFrame = instrumentation.frame(ordered.length)
           ordered.forEach((envelope) =>
             instrumentation.eventDispatched(envelope.event._tag, envelope.priority),
           )
-          // Isolate folds so one throw cannot kill the drain fiber
           const collected = Arr.flatMap(ordered, (envelope) =>
-            Arr.filterMap(bucketOf(reducers.byTag, envelope.event._tag), (reducer) =>
+            // A reducer defect must not abandon the remaining frame.
+            Arr.filterMap(reducers.tagged(envelope.event._tag), (reducer) =>
               isolateApply(reducer, envelope.event, instrumentation),
             ),
           )
-          // Offer each distinct channel once (per-procedure would double-run shared channels)
           ordered.forEach((envelope) => {
-            bucketOf(procedures.channelsByTag, envelope.event._tag).forEach((channelName) => {
+            // channelsFor is distinct; per-procedure offers would double-run shared channels.
+            procedures.channelsFor(envelope.event._tag).forEach((channelName) => {
               channels.get(channelName)?.offer(envelope.event)
             })
           })
@@ -150,7 +169,7 @@ const drain = Effect.gen(function* () {
           { discard: true },
         )
       }).pipe(
-        // Only typed failures (overflow) escape; defects restart the tick so the bus never goes deaf
+        // Typed overflow halts the loop; defects are logged and the next tick continues.
         Effect.catchAllCause((cause) =>
           Option.match(Cause.failureOption(cause), {
             onSome: () => Effect.failCause(cause),
@@ -180,3 +199,13 @@ export const Engine: Layer.Layer<Bus | Reducers | Channels | Procedures | Querie
       ),
     ),
   )
+
+export const EngineRequirements: readonly [
+  typeof Bus,
+  typeof Reducers,
+  typeof Channels,
+  typeof Procedures,
+  typeof Queries,
+] = [Bus, Reducers, Channels, Procedures, Queries]
+
+export type EngineServices = Layer.Layer.Success<typeof Engine>

package/src/runtime/runtimeHandle.ts

@@ -0,0 +1,124 @@
+import type { Context, Effect, Option } from 'effect'
+import type {
+  CompositionActivation,
+  CompositionId,
+  RequiredSlotIdentities,
+} from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import type {
+  AnyFeatureBinding,
+  CapturedFeatureBinding,
+  FeatureBinding,
+  FeatureRequirement,
+} from '../feature/feature'
+import type {
+  AnyFeatureGraphSummary,
+  FeatureSummaryCompositionIdentity,
+  FeatureSummaryContract,
+  FeatureSummaryInput,
+  FeatureSummaryMountProps,
+  FeatureSummaryName,
+  FeatureSummaryOpenServices,
+  FeatureSummaryUsesInput,
+} from '../graph/closure'
+import type { FeatureLoadFailed } from '../internal/errors'
+import type { Node } from '../ui/node'
+import type { Priority, Tagged } from './bus'
+import type { Instrumentation } from './instrumentation'
+import type { EngineServices } from './loop'
+
+export const UnspecifiedRuntimeServicesTypeId: unique symbol = Symbol.for(
+  'reform/UnspecifiedRuntimeServices',
+)
+export type UnspecifiedRuntimeServicesTypeId = typeof UnspecifiedRuntimeServicesTypeId
+export interface UnspecifiedRuntimeServices {
+  readonly [UnspecifiedRuntimeServicesTypeId]: UnspecifiedRuntimeServicesTypeId
+}
+
+export type FeatureMountHandlersExternalApi<UsesInput extends boolean, Input, Services> = {
+  readonly onLive: (runtime: RuntimeHandle<Services>) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+} & (UsesInput extends true ? { readonly props: Input } : { readonly props?: never })
+
+export type FeatureMountHandlers<
+  UsesInput extends boolean,
+  Input,
+  Services,
+> = FeatureMountHandlersExternalApi<UsesInput, Input, Services>
+
+export type RuntimeFeatureAvailability<Services, OpenServices> = [
+  EngineServices | OpenServices,
+] extends [Services]
+  ? object
+  : {
+      readonly missingFeatureServices: Exclude<EngineServices | OpenServices, Services>
+    }
+
+export interface AnyFeatureMountHandlers {
+  readonly props: unknown
+  readonly onLive: <Services>(runtime: RuntimeHandle<Services>) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+}
+
+export interface CapturedFeatureMountHandlers<
+  Props,
+  HostServices,
+  FeatureServices,
+  C extends UiContract,
+  N extends string,
+  Identity,
+> {
+  readonly props: Props
+  readonly onLive: (
+    runtime: RuntimeHandle<
+      HostServices | FeatureServices | CompositionId<N, Identity, RequiredSlotIdentities<C>>
+    >,
+  ) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+}
+
+export interface RuntimeHandle<Services = UnspecifiedRuntimeServices> {
+  read<Identifier extends Services, Service>(tag: Context.Tag<Identifier, Service>): Service
+  readOption<Identifier, Service>(tag: Context.Tag<Identifier, Service>): Option.Option<Service>
+  runRender(effect: Effect.Effect<Node, never, never>): Node
+  dispatch(priority: Priority, event: Tagged): void
+  mountScoped(activation: CompositionActivation): () => void
+  mountFeature<
+    Summary extends AnyFeatureGraphSummary,
+    ROut,
+    const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  >(
+    binding: [EngineServices | FeatureSummaryOpenServices<Summary>] extends [Services]
+      ? FeatureBinding<Summary, ROut, DirectRequires>
+      : never,
+    handlers: FeatureMountHandlers<
+      FeatureSummaryUsesInput<Summary>,
+      FeatureSummaryInput<Summary>,
+      Services | ROut
+    >,
+  ): () => void
+  mountCapturedFeature<
+    Summary extends AnyFeatureGraphSummary,
+    ROut,
+    const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  >(
+    binding: CapturedFeatureBinding<Summary, ROut, DirectRequires> &
+      RuntimeFeatureAvailability<Services, FeatureSummaryOpenServices<Summary>>,
+    handlers: CapturedFeatureMountHandlers<
+      FeatureSummaryMountProps<Summary>,
+      Services,
+      ROut,
+      FeatureSummaryContract<Summary>,
+      FeatureSummaryName<Summary>,
+      FeatureSummaryCompositionIdentity<Summary>
+    >,
+  ): () => void
+  mountAnyFeature(binding: AnyFeatureBinding, handlers: AnyFeatureMountHandlers): () => void
+  readonly instrumentation: Instrumentation
+}
+
+export interface AppRuntime<Services = UnspecifiedRuntimeServices> extends RuntimeHandle<Services> {
+  boot(): void
+  dispose(): void
+  isDisposed(): boolean
+}

package/src/scene/featureScene.test.ts

@@ -19,11 +19,13 @@ const GreetingBase: Context.TagClass<Greeting, 'featureScene.Greeting', Greeting
 class Greeting extends GreetingBase {}
 
 class Started extends Event.make('featureScene.Started', S.Struct({})) {}
-class RootUi extends ui('featureScene.RootUi')<{ props: { readonly greeting: string } }>() {}
+class RootUi extends ui('featureScene.RootUi')<{
+  props: { readonly greeting: string }
+}>() {}
 class RootComp extends Composition.make('featureScene.RootComp', {
   title: 'Feature root',
   ui: RootUi,
-}) {}
+})<RootComp>() {}
 
 const RootLive = Composition.live(RootComp, function* () {
   const greeting = yield* Greeting