@playfast/reform 1.2.0 → 1.3.0

package/src/graph/summary.ts

@@ -0,0 +1,134 @@
+import type { UiContract } from '../compose/ui'
+
+export const FeatureGraphValidTypeId: unique symbol = Symbol.for('reform/FeatureGraphValid')
+export type FeatureGraphValidTypeId = typeof FeatureGraphValidTypeId
+
+export const FeatureModuleGraphValidTypeId: unique symbol = Symbol.for(
+  'reform/FeatureModuleGraphValid',
+)
+export type FeatureModuleGraphValidTypeId = typeof FeatureModuleGraphValidTypeId
+
+export const FeatureChildSummaryTypeId: unique symbol = Symbol.for('reform/FeatureChildSummary')
+export type FeatureChildSummaryTypeId = typeof FeatureChildSummaryTypeId
+
+export const FeatureGraphSummaryTypeId: unique symbol = Symbol.for('reform/FeatureGraphSummary')
+export type FeatureGraphSummaryTypeId = typeof FeatureGraphSummaryTypeId
+
+export const SlotBindingSummaryTypeId: unique symbol = Symbol.for('reform/SlotBindingSummary')
+export type SlotBindingSummaryTypeId = typeof SlotBindingSummaryTypeId
+
+export interface SlotBindingSummary {
+  readonly [SlotBindingSummaryTypeId]: SlotBindingSummaryTypeId
+}
+
+/**
+ * The constant-size proof published after a Feature's current module has passed
+ * graph validation. Type-only facts use empty-or-singleton tuples so the runtime
+ * summary stays compact while direct indexed access recovers their exact types.
+ */
+export interface FeatureGraphSummary<
+  out FeatureIdentity,
+  out MountProps,
+  out CompositionProps,
+  out C extends UiContract,
+  out S extends ReadonlyArray<unknown>,
+  out N extends string,
+  out CompositionIdentity,
+  out OpenServices,
+  out SupportOpenServices,
+  out UsesInput extends boolean,
+  out Input,
+> extends SlotBindingSummary {
+  readonly [FeatureGraphSummaryTypeId]: {
+    readonly featureIdentity: readonly [] | readonly [FeatureIdentity]
+    readonly mountProps: readonly [] | readonly [MountProps]
+    readonly compositionProps: readonly [] | readonly [CompositionProps]
+    readonly contract: readonly [] | readonly [C]
+    readonly states: readonly [] | readonly [S]
+    readonly name: N
+    readonly compositionIdentity: readonly [] | readonly [CompositionIdentity]
+    readonly openServices: readonly [] | readonly [OpenServices]
+    readonly supportOpenServices: readonly [] | readonly [SupportOpenServices]
+    readonly usesInput: readonly [] | readonly [UsesInput]
+    readonly input: readonly [] | readonly [Input]
+    readonly validated: FeatureModuleGraphValidTypeId
+  }
+  readonly [FeatureChildSummaryTypeId]: {
+    readonly featureIdentity: readonly [] | readonly [FeatureIdentity]
+    readonly compositionIdentity: readonly [] | readonly [CompositionIdentity]
+  }
+}
+
+export type FeatureChildSummary<
+  FeatureIdentity,
+  MountProps,
+  CompositionProps,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  CompositionIdentity,
+  OpenServices,
+  SupportOpenServices,
+  UsesInput extends boolean,
+  Input,
+> = FeatureGraphSummary<
+  FeatureIdentity,
+  MountProps,
+  CompositionProps,
+  C,
+  S,
+  N,
+  CompositionIdentity,
+  OpenServices,
+  SupportOpenServices,
+  UsesInput,
+  Input
+>
+
+export type AnyFeatureGraphSummary = FeatureGraphSummary<
+  unknown,
+  unknown,
+  unknown,
+  UiContract,
+  ReadonlyArray<unknown>,
+  string,
+  unknown,
+  unknown,
+  unknown,
+  boolean,
+  unknown
+>
+
+export type FeatureSummaryIdentity<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['featureIdentity'][number]
+export type FeatureSummaryMountProps<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['mountProps'][number]
+export type FeatureSummaryCompositionProps<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['compositionProps'][number]
+export type FeatureSummaryContract<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['contract'][number]
+export type FeatureSummaryStates<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['states'][number]
+export type FeatureSummaryName<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['name']
+export type FeatureSummaryCompositionIdentity<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['compositionIdentity'][number]
+export type FeatureSummaryOpenServices<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['openServices'][number]
+export type FeatureSummarySupportOpenServices<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['supportOpenServices'][number]
+export type FeatureSummaryUsesInput<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['usesInput'][number]
+export type FeatureSummaryInput<Summary extends AnyFeatureGraphSummary> =
+  Summary[FeatureGraphSummaryTypeId]['input'][number]
+
+export const CompositionChildSummaryTypeId: unique symbol = Symbol.for(
+  'reform/CompositionChildSummary',
+)
+export type CompositionChildSummaryTypeId = typeof CompositionChildSummaryTypeId
+
+export interface CompositionChildSummary<out CompositionIdentity> extends SlotBindingSummary {
+  readonly [CompositionChildSummaryTypeId]: {
+    readonly compositionIdentity: CompositionIdentity
+  }
+}

package/src/internal/queryDriver.ts

@@ -1,21 +1,10 @@
-import {
-  Cause,
-  Chunk,
-  Effect,
-  MutableRef,
-  Option,
-  type ParseResult,
-  Queue,
-  Runtime,
-  type Scope,
-  Stream,
-} from 'effect'
-import { type AnyAsyncData } from '../calc/asyncData'
+import { Cause, Chunk, Effect, MutableRef, Option, Queue, Runtime, type Scope, Stream } from 'effect'
 import { empty, type QueryState } from '../calc/queryState'
 import { Queries, type QueryHandle } from '../runtime/queries'
 import { reuse } from './reuse'
 import { resolveInstrumentation } from '../runtime/instrumentation'
 import { resolveQueryStore } from './queryStore'
+import { hydratePersistedQuery } from './queryDriverHydrate'
 import {
   incrementGeneration,
   makeQueryProjection,
@@ -23,62 +12,24 @@ import {
   settleQueryError,
   withReaderTracking,
 } from './queryDriverStore'
+import type { QueryDriver, QueryDriverOptions } from './queryDriverTypes'
 import { resolveScheduler } from './scheduler'
-import {
-  type InputsObject,
-  type InputStores,
-  type InvalidateBy,
-  sameKey,
-  wireSources,
-} from './sources'
-import { makeStore, type Store } from './store'
+import { type InputsObject, type InputStores, sameKey, wireSources } from './sources'
+import { makeStore } from './store'
 import { type AnySource } from '../state/token'
 
 export {
   bumpRevision,
   gatedFlag,
   type GatedOf,
+  type QueryCodec,
+  type QueryDriver,
+  type QueryDriverOptions,
   Revision,
   RevisionSchema,
   revisionZero,
 } from './queryDriverTypes'
 
-// Keep schema invariance behind a covariant persistence boundary.
-export interface QueryCodec<A> {
-  readonly encode: (value: A) => Effect.Effect<unknown, ParseResult.ParseError, never>
-  readonly decode: (input: unknown) => Effect.Effect<A, ParseResult.ParseError, never>
-}
-
-export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A, E, R> {
-  readonly name: string
-  readonly label: string
-  readonly gated: boolean
-  readonly inputs: Inputs
-  readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
-  readonly invalidateBy?: InvalidateBy<Inputs> | undefined
-  readonly disabled?: ((inputs: InputsObject<Inputs>) => boolean) | undefined
-  readonly coalesce?: 'switch' | 'trailing' | undefined
-  readonly reuse?: boolean | undefined
-  readonly extraKey?:
-    | {
-        readonly read: () => unknown
-        readonly subscribe: (listener: () => void) => () => void
-      }
-    | undefined
-  readonly persist?:
-    | {
-        readonly key: string | ((inputs: InputsObject<Inputs>) => string)
-        readonly codec: QueryCodec<A>
-      }
-    | undefined
-  readonly onSettled?: ((generation: number) => void) | undefined
-}
-
-export interface QueryDriver<A, E> {
-  readonly store: Store<AnyAsyncData<A, E>>
-  readonly requested: () => number
-}
-
 // oxlint-disable-next-line reform-rules/prefer-effect-fn -- generic export: Effect.fn's inferred type isn't portable under isolatedDeclarations
 export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R>(
   options: QueryDriverOptions<Inputs, A, E, R>,
@@ -268,42 +219,22 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
     yield* Effect.addFinalizer(() => Effect.sync(unsubscribe))
 
     // Fork hydration so an asynchronous store never blocks layer acquisition.
-    // Epoch, key, and settled-state guards prevent a late cache from replacing newer truth.
     if (persist !== undefined && !disabledNow()) {
       const hydrateArgs = sources.snapshot()
       const hydrateSourceKey = keyOf(hydrateArgs)
       const hydrateSourceEpoch = MutableRef.get(sourceEpoch)
-      const hydrateStaleAtGeneration = MutableRef.get(generation)
-      const hydrate = queryStore.get(persistKey(persist.key, hydrateArgs)).pipe(
-        Effect.flatMap((cached) =>
-          Option.match(cached, {
-            onNone: () => Effect.void,
-            onSome: (raw) =>
-              persist.codec.decode(raw).pipe(
-                Effect.tap((decoded) =>
-                  Effect.sync(() => {
-                    const state = stateStore.get()
-                    if (
-                      disabledNow() ||
-                      hydrateSourceEpoch !== MutableRef.get(sourceEpoch) ||
-                      !sameKey(hydrateSourceKey, keyOf(sources.snapshot())) ||
-                      Option.isSome(state.data) ||
-                      Option.isSome(state.error)
-                    ) {
-                      return
-                    }
-                    MutableRef.update(staleAtGeneration, (current) =>
-                      Math.max(current, hydrateStaleAtGeneration),
-                    )
-                    stateStore.set({ ...state, data: Option.some(decoded), isStale: true })
-                  }),
-                ),
-              ),
-          }),
-        ),
-        // Corrupt/incompatible cache: ignore and fetch fresh.
-        Effect.ignore,
-      )
+      const hydrate = hydratePersistedQuery({
+        queryStore,
+        cacheKey: persistKey(persist.key, hydrateArgs),
+        codec: persist.codec,
+        stateStore,
+        staleAtGeneration,
+        capturedGeneration: MutableRef.get(generation),
+        isSuperseded: () =>
+          disabledNow() ||
+          hydrateSourceEpoch !== MutableRef.get(sourceEpoch) ||
+          !sameKey(hydrateSourceKey, keyOf(sources.snapshot())),
+      })
       const runtime = yield* Effect.runtime<never>()
       const scope = yield* Effect.scope
       Runtime.runFork(runtime)(hydrate, { immediate: true, scope })

package/src/internal/queryDriverHydrate.ts

@@ -0,0 +1,45 @@
+import { Effect, MutableRef, Option } from 'effect'
+import type { QueryState } from '../calc/queryState'
+import type { QueryStoreApi } from './queryStore'
+import type { QueryCodec } from './queryDriverTypes'
+import type { Store } from './store'
+
+interface HydratePersistedOptions<A, E> {
+  readonly queryStore: QueryStoreApi
+  readonly cacheKey: string
+  readonly codec: QueryCodec<A>
+  readonly stateStore: Store<QueryState<A, E>>
+  readonly staleAtGeneration: MutableRef.MutableRef<number>
+  readonly capturedGeneration: number
+  // True once the sources moved past the snapshot this hydration was captured for.
+  readonly isSuperseded: () => boolean
+}
+
+const paint = <A, E>(options: HydratePersistedOptions<A, E>, decoded: A): void => {
+  const state = options.stateStore.get()
+  if (options.isSuperseded() || Option.isSome(state.data) || Option.isSome(state.error)) {
+    return
+  }
+  MutableRef.update(options.staleAtGeneration, (current) =>
+    Math.max(current, options.capturedGeneration),
+  )
+  options.stateStore.set({ ...state, data: Option.some(decoded), isStale: true })
+}
+
+// Epoch, key, and settled-state guards prevent a late cache from replacing newer truth.
+export const hydratePersistedQuery = <A, E>(
+  options: HydratePersistedOptions<A, E>,
+): Effect.Effect<void> =>
+  options.queryStore.get(options.cacheKey).pipe(
+    Effect.flatMap((cached) =>
+      Option.match(cached, {
+        onNone: () => Effect.void,
+        onSome: (raw) =>
+          options.codec
+            .decode(raw)
+            .pipe(Effect.tap((decoded) => Effect.sync(() => paint(options, decoded)))),
+      }),
+    ),
+    // Corrupt/incompatible cache: ignore and fetch fresh.
+    Effect.ignore,
+  )

package/src/internal/queryDriverTypes.ts

@@ -1,9 +1,8 @@
-import { Brand, Effect, Schema } from 'effect'
+import { Brand, Effect, type ParseResult, Schema } from 'effect'
 import type { AnyAsyncData } from '../calc/asyncData'
 import type { InputsObject, InvalidateBy } from './sources'
 import type { Store } from './store'
 import type { AnySource } from '../state/token'
-import type { AnySchema } from './variance'
 
 export type GatedOf<AlwaysOn extends boolean> = AlwaysOn extends true ? false : true
 
@@ -21,35 +20,34 @@ export const RevisionSchema: Schema.Schema<Revision, number> = Schema.Number.pip
 export const revisionZero: Revision = Revision(0)
 export const bumpRevision = (revision: Revision): Revision => Revision(revision + 1)
 
+// Keep schema invariance behind a covariant persistence boundary.
+export interface QueryCodec<A> {
+  readonly encode: (value: A) => Effect.Effect<unknown, ParseResult.ParseError, never>
+  readonly decode: (input: unknown) => Effect.Effect<A, ParseResult.ParseError, never>
+}
+
 export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A, E, R> {
   readonly name: string
   readonly label: string
   readonly gated: boolean
   readonly inputs: Inputs
   readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly invalidateBy?: InvalidateBy<Inputs> | undefined
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly disabled?: ((inputs: InputsObject<Inputs>) => boolean) | undefined
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly coalesce?: 'switch' | 'trailing' | undefined
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly reuse?: boolean | undefined
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly extraKey?:
     | {
         readonly read: () => unknown
         readonly subscribe: (listener: () => void) => () => void
       }
     | undefined
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly persist?:
     | {
         readonly key: string | ((inputs: InputsObject<Inputs>) => string)
-        readonly schema: AnySchema<A>
+        readonly codec: QueryCodec<A>
       }
     | undefined
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly onSettled?: ((generation: number) => void) | undefined
 }
 

package/src/internal/store.test.ts

@@ -1,7 +1,14 @@
 import { expect, test } from 'vitest'
 import { makeStore } from './store'
 
-const tick = () => new Promise<void>((resolve) => queueMicrotask(resolve))
+// Notifications land on the microtask queue — poll turns of it, never wall-clock.
+const until = async (predicate: () => boolean, rounds = 1000): Promise<void> => {
+  if (predicate() || rounds <= 0) {
+    return
+  }
+  await new Promise<void>((resolve) => queueMicrotask(resolve))
+  return until(predicate, rounds - 1)
+}
 
 const counter = () => ({ n: 0 })
 
@@ -14,19 +21,26 @@ test('subscribe observes changes; getSnapshot is always current', async () => {
 
   store.set(1)
   expect(store.getSnapshot()).toBe(1)
-  await tick()
+  await until(() => notifications.n > 0)
   expect(notifications.n).toBe(1)
 })
 
 test('a no-op write notifies no one', async () => {
   const store = makeStore('same')
+  const witness = makeStore(0)
   const notifications = counter()
+  const witnessWakes = counter()
   store.subscribe(() => {
     notifications.n++
   })
+  witness.subscribe(() => {
+    witnessWakes.n++
+  })
 
   store.set('same')
-  await tick()
+  // Both stores share the scheduler, so the witness flush drains anything the no-op could have queued.
+  witness.set(1)
+  await until(() => witnessWakes.n > 0)
   expect(notifications.n).toBe(0)
   expect(store.getSnapshot()).toBe('same')
 })
@@ -42,7 +56,8 @@ test('a batch of writes coalesces into a single notification per microtask', asy
   store.set(2)
   store.set(3)
   expect(store.getSnapshot()).toBe(3)
-  await tick()
+  // The drain is synchronous: the first wake already carries every write the batch would have fired.
+  await until(() => notifications.n > 0)
   expect(notifications.n).toBe(1)
 })
 
@@ -59,20 +74,26 @@ test('stores are independent — one slice does not wake another', async () => {
   })
 
   a.set(1)
-  await tick()
+  await until(() => aWakes.n > 0)
   expect(aWakes.n).toBe(1)
   expect(bWakes.n).toBe(0)
 })
 
 test('unsubscribe stops notifications', async () => {
   const store = makeStore(0)
+  const witness = makeStore(0)
   const notifications = counter()
+  const witnessWakes = counter()
   const unsubscribe = store.subscribe(() => {
     notifications.n++
   })
+  witness.subscribe(() => {
+    witnessWakes.n++
+  })
 
   unsubscribe()
   store.set(1)
-  await tick()
+  witness.set(1)
+  await until(() => witnessWakes.n > 0)
   expect(notifications.n).toBe(0)
 })

package/src/remote/pendingQueue.ts

@@ -0,0 +1,145 @@
+import { Equal, MutableRef, Option } from 'effect'
+import { inspectable } from '../internal/inspect'
+import type { Scheduler } from '../internal/scheduler'
+import type { Store } from '../internal/store'
+import type { PendingIntent } from './remoteStateTypes'
+
+export interface PendingNode<I> {
+  readonly entry: MutableRef.MutableRef<PendingIntent<I>>
+}
+
+// Duplicate opIds retain every node so indexed updates preserve the old map semantics.
+export interface PendingOpEntry<I> {
+  readonly nodes: Set<PendingNode<I>>
+}
+
+export interface PendingQueue<I> {
+  readonly store: Store<ReadonlyArray<PendingIntent<I>>>
+  readonly revision: () => number
+  readonly fold: <B>(initial: B, combine: (accumulator: B, entry: PendingIntent<I>) => B) => B
+  readonly append: (entry: PendingIntent<I>) => void
+  readonly ack: (opId: string) => void
+  readonly settle: (opId: string) => void
+}
+
+export const makePendingQueue = <I>(scheduler: Scheduler): PendingQueue<I> => {
+  // Set insertion order preserves dispatch/apply order while allowing O(1) updates.
+  const ordered = new Set<PendingNode<I>>()
+  const byOpId = new Map<string, PendingOpEntry<I>>()
+  const listeners = new Set<() => void>()
+  const revision = MutableRef.make(0)
+  const initial: ReadonlyArray<PendingIntent<I>> = []
+  const snapshot = MutableRef.make<Option.Option<ReadonlyArray<PendingIntent<I>>>>(
+    Option.some(initial),
+  )
+
+  const materialize = (): ReadonlyArray<PendingIntent<I>> => {
+    const cached = MutableRef.get(snapshot)
+    if (Option.isSome(cached)) {
+      return cached.value
+    }
+    const current = Array.from(ordered, (node) => MutableRef.get(node.entry))
+    MutableRef.set(snapshot, Option.some(current))
+    return current
+  }
+
+  const announce = (next: Option.Option<ReadonlyArray<PendingIntent<I>>>): void => {
+    MutableRef.set(snapshot, next)
+    MutableRef.update(revision, (current) => current + 1)
+    scheduler.schedule(listeners)
+  }
+
+  const link = (entry: PendingIntent<I>): void => {
+    const node: PendingNode<I> = {
+      entry: MutableRef.make(entry),
+    }
+    ordered.add(node)
+    const indexed = byOpId.get(entry.opId)
+    if (indexed === undefined) {
+      byOpId.set(entry.opId, { nodes: new Set([node]) })
+    } else {
+      indexed.nodes.add(node)
+    }
+  }
+
+  const clear = (): void => {
+    ordered.clear()
+    byOpId.clear()
+  }
+
+  const fold = <B>(initialValue: B, combine: (accumulator: B, entry: PendingIntent<I>) => B): B => {
+    const folded = MutableRef.make(initialValue)
+    ordered.forEach((node) => {
+      MutableRef.update(folded, (accumulator) => combine(accumulator, MutableRef.get(node.entry)))
+    })
+    return MutableRef.get(folded)
+  }
+
+  const append = (entry: PendingIntent<I>): void => {
+    link(entry)
+    announce(Option.none())
+  }
+
+  const ack = (opId: string): void => {
+    const indexed = byOpId.get(opId)
+    if (indexed === undefined) {
+      return
+    }
+    const stillSending = MutableRef.make(false)
+    indexed.nodes.forEach((node) => {
+      if (MutableRef.get(node.entry).status === 'sending') {
+        MutableRef.set(stillSending, true)
+      }
+    })
+    if (!MutableRef.get(stillSending)) {
+      return
+    }
+    // Rebuild every duplicate once one is sending, matching the former array map.
+    indexed.nodes.forEach((node) => {
+      MutableRef.update(node.entry, (entry) => ({ ...entry, status: 'confirmed' as const }))
+    })
+    announce(Option.none())
+  }
+
+  const settle = (opId: string): void => {
+    const indexed = byOpId.get(opId)
+    if (indexed === undefined) {
+      return
+    }
+    indexed.nodes.forEach((node) => {
+      ordered.delete(node)
+    })
+    byOpId.delete(opId)
+    announce(Option.none())
+  }
+
+  const store: Store<ReadonlyArray<PendingIntent<I>>> = {
+    get: materialize,
+    getSnapshot: materialize,
+    getVersion: () => MutableRef.get(revision),
+    set: (next) => {
+      if (Equal.equals(materialize(), next)) {
+        return
+      }
+      clear()
+      next.forEach(link)
+      announce(Option.some(next))
+    },
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    ...inspectable(() => ({ _id: 'reform/Store', value: materialize() })),
+  }
+
+  return {
+    store,
+    revision: () => MutableRef.get(revision),
+    fold,
+    append,
+    ack,
+    settle,
+  }
+}