@playfast/reform 1.0.1 → 1.2.0

package/src/internal/queryDriverTypes.ts

@@ -0,0 +1,59 @@
+import { Brand, Effect, 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
+
+export const gatedFlag = <AlwaysOn extends boolean>(
+  alwaysOn: AlwaysOn | undefined,
+): GatedOf<AlwaysOn> =>
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- restate the runtime boolean as its conditional `GatedOf` literal; no guard maps a boolean to a conditional type
+  (alwaysOn !== true) as GatedOf<AlwaysOn>
+
+export type Revision = number & Brand.Brand<'reform/Revision'>
+export const Revision: Brand.Brand.Constructor<Revision> = Brand.nominal<Revision>()
+export const RevisionSchema: Schema.Schema<Revision, number> = Schema.Number.pipe(
+  Schema.brand('reform/Revision'),
+)
+export const revisionZero: Revision = Revision(0)
+export const bumpRevision = (revision: Revision): Revision => Revision(revision + 1)
+
+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>
+      }
+    | 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
+}
+
+export interface QueryDriver<A, E> {
+  readonly store: Store<AnyAsyncData<A, E>>
+  readonly requested: () => number
+}

package/src/internal/queryEvents.ts

@@ -1,17 +1,7 @@
 import { Context, Effect, Option } from 'effect'
 
-// `QueryEvents` is the optional host-signal seam invalidation *sources* subscribe
-// to — window focus/visibility and network reconnect. It carries no DOM itself:
-// the concrete `window.addEventListener` implementation lives in an edge package
-// (`@playfast/reform-query-browser`); core only declares the shape. Resolved via
-// `serviceOption` with a no-op fallback, so its absence (SSR, native, proofs) is
-// inert. The subscriptions return an unsubscribe thunk — the synchronous,
-// React-facing shape the rest of reform uses (see `Store.subscribe`).
-
 export interface QueryEventsApi {
-  /** Fires when the window/tab regains focus or visibility. */
   readonly subscribeFocus: (listener: () => void) => () => void
-  /** Fires when the network comes back online. */
   readonly subscribeOnline: (listener: () => void) => () => void
 }
 
@@ -21,13 +11,11 @@ export class QueryEvents extends QueryEventsBase {}
 
 const noop = (): (() => void) => () => {}
 
-/** A source that never fires — the fallback when no host provides `QueryEvents`. */
 export const noopQueryEvents: QueryEventsApi = {
   subscribeFocus: noop,
   subscribeOnline: noop,
 }
 
-/** Resolve the host's `QueryEvents`, or the no-op source when none is in context. */
 export const resolveQueryEvents: Effect.Effect<QueryEventsApi> = Effect.map(
   Effect.serviceOption(QueryEvents),
   Option.getOrElse(() => noopQueryEvents),

package/src/internal/queryStore.ts

@@ -1,13 +1,5 @@
 import { Context, Effect, Option } from 'effect'
 
-// `QueryStore` is the optional persistence seam an `AsyncCalc` writes through and
-// hydrates from — a key→value cache provided by the host (localStorage,
-// IndexedDB, AsyncStorage, …). Like `Notifications`, it is resolved through
-// `serviceOption`, so a calc that opts into `persist` imposes NO hard requirement:
-// absent host ⇒ the no-op store ⇒ the feature is simply inert (SSR, native,
-// proofs). Values cross the boundary as `unknown` and are (de)serialized through
-// the calc's own `output` schema by the driver, never trusted structurally.
-
 export interface QueryStoreApi {
   readonly get: (key: string) => Effect.Effect<Option.Option<unknown>>
   readonly set: (key: string, value: unknown) => Effect.Effect<void>
@@ -18,18 +10,12 @@ const QueryStoreBase: Context.TagClass<QueryStore, 'reform/QueryStore', QuerySto
   Context.Tag('reform/QueryStore')<QueryStore, QueryStoreApi>()
 export class QueryStore extends QueryStoreBase {}
 
-/** A store that persists nothing — the fallback when no host provides `QueryStore`. */
 export const noopQueryStore: QueryStoreApi = {
   get: () => Effect.succeedNone,
   set: () => Effect.void,
   remove: () => Effect.void,
 }
 
-/**
- * Resolve the host's `QueryStore`, or the no-op store when none is in context.
- * `serviceOption` keeps it requirement-free — a calc wired as a sibling of the
- * runtime that provides no persistence simply gets the inert store.
- */
 export const resolveQueryStore: Effect.Effect<QueryStoreApi> = Effect.map(
   Effect.serviceOption(QueryStore),
   Option.getOrElse(() => noopQueryStore),

package/src/internal/reuse.test.ts

@@ -2,9 +2,6 @@ import { describe, expect, it } from '@effect/vitest'
 import { Data, Schema as S } from 'effect'
 import { reuse } from './reuse'
 
-// The structural-sharing pass behind `reuse: true`: identities move only where
-// values moved, and the result is always value-equal to the fresh output.
-
 describe('reuse', () => {
   it('returns the previous value when the next is deeply value-equal', () => {
     const prev = { a: [1, 2, { b: 'x' }], c: { d: true } }
@@ -16,7 +13,10 @@ describe('reuse', () => {
     const e0 = { id: 1, name: 'a' }
     const e1 = { id: 2, name: 'b' }
     const prev = [e0, e1]
-    const next = [{ id: 1, name: 'a' }, { id: 2, name: 'B' }]
+    const next = [
+      { id: 1, name: 'a' },
+      { id: 2, name: 'B' },
+    ]
     const out = reuse(prev, next)
     expect(out).not.toBe(prev)
     expect(out[0]).toBe(e0)
@@ -52,11 +52,11 @@ describe('reuse', () => {
     class View extends S.Class<View>('View')({ title: S.String, rows: S.Array(Row) }) {}
     const keep = new Row({ id: 1, name: 'a' })
     const prev = new View({ title: 't', rows: [keep, new Row({ id: 2, name: 'b' })] })
-    const next = new View({ title: 't', rows: [new Row({ id: 1, name: 'a' }), new Row({ id: 2, name: 'B' })] })
+    const next = new View({
+      title: 't',
+      rows: [new Row({ id: 1, name: 'a' }), new Row({ id: 2, name: 'B' })],
+    })
     const out = reuse(prev, next)
-    // The container changed (row 2 renamed) so a fresh View comes back — but it
-    // is still a View (prototype preserved) and the untouched row keeps its
-    // exact previous identity.
     expect(out).not.toBe(prev)
     expect(out).toBeInstanceOf(View)
     expect(out.rows[0]).toBe(keep)
@@ -66,14 +66,10 @@ describe('reuse', () => {
   })
 
   it('compares Dates by instant (Effect Equal) and treats other class instances as opaque leaves', () => {
-    // Effect's `Equal.equals` compares Dates structurally: same instant ⇒ the
-    // previous identity is kept.
     const prev = { at: new Date(0) }
     const out = reuse(prev, { at: new Date(0) })
     expect(out.at).toBe(prev.at)
 
-    // A class without Equal: never recursed into, the fresh leaf wins even
-    // when its fields look identical.
     class Opaque {
       readonly v: number
       constructor(v: number) {
@@ -87,11 +83,11 @@ describe('reuse', () => {
 
   it('returns next below the depth bound', () => {
     type Nest = { readonly n?: Nest; readonly v: number }
-    const deep = (depth: number): Nest => (depth === 0 ? { v: 0 } : { v: depth, n: deep(depth - 1) })
+    const deep = (depth: number): Nest =>
+      depth === 0 ? { v: 0 } : { v: depth, n: deep(depth - 1) }
     const prev = deep(20)
     const next = deep(20)
     const out = reuse(prev, next)
-    // Value-equal throughout — shared down to the bound, fresh below it.
     expect(out).toEqual(next)
   })
 

package/src/internal/reuse.ts

@@ -1,14 +1,5 @@
 import { Equal, Record as Rec } from 'effect'
 
-// Structural sharing for recomputed calc outputs: reconcile a fresh output
-// against the previous one, substituting previous nodes wherever value equality
-// holds, so identities only move where values moved. Downstream memo boundaries
-// (React subtrees keyed on object identity) then skip everything that didn't
-// change. Referentially transparent: the result is value-equal to `next` — only
-// identities shift toward `previous` — and neither argument is mutated, so the
-// pass composes with the framework's Equal-based invalidation untouched.
-
-// Bounds the walk; calc outputs are shallow plain data by framework convention.
 const MAX_DEPTH = 16
 
 const isPlainRecord = (candidate: unknown): candidate is Record<string, unknown> =>
@@ -17,7 +8,6 @@ const isPlainRecord = (candidate: unknown): candidate is Record<string, unknown>
   (Object.getPrototypeOf(candidate) === Object.prototype ||
     Object.getPrototypeOf(candidate) === null)
 
-/** Own enumerable string-keyed fields of an object, as a plain record. */
 const ownRecord = (source: object): Record<string, unknown> =>
   Rec.fromEntries(
     Reflect.ownKeys(source)
@@ -34,7 +24,6 @@ interface ReconcileArgs {
   readonly depth: number
 }
 
-/** Reconcile two records field-by-field; reports whether every field stayed `prev`. */
 const reconcileRecord = (
   prev: Record<string, unknown>,
   next: Record<string, unknown>,
@@ -57,8 +46,6 @@ const reconcile = ({ prev, next, depth }: ReconcileArgs): unknown => {
   if (Object.is(prev, next)) {
     return prev
   }
-  // Data/Schema classes implement Equal+Hash: substitute wholesale on value
-  // equality. Plain objects/arrays fall through (their Equal is referential).
   if (Equal.equals(prev, next)) {
     return prev
   }
@@ -67,22 +54,19 @@ const reconcile = ({ prev, next, depth }: ReconcileArgs): unknown => {
   }
   if (Array.isArray(prev) && Array.isArray(next)) {
     const reconciled = next.map((element, index) =>
-      index < prev.length ? reconcile({ prev: prev[index], next: element, depth: depth - 1 }) : element,
+      index < prev.length
+        ? reconcile({ prev: prev[index], next: element, depth: depth - 1 })
+        : element,
     )
     const unchanged =
-      prev.length === next.length && reconciled.every((entry, index) => Object.is(entry, prev[index]))
+      prev.length === next.length &&
+      reconciled.every((entry, index) => Object.is(entry, prev[index]))
     return unchanged ? prev : reconciled
   }
   if (isPlainRecord(prev) && isPlainRecord(next)) {
     const { out, allPrev } = reconcileRecord(prev, next, depth)
     return allPrev ? prev : out
   }
-  // Data/Schema class instances that DIFFER still get walked: their Equal is
-  // fieldwise over own enumerable fields, so a reconstruction over reconciled
-  // fields (same prototype; the constructor is bypassed, but every leaf is a
-  // validated value out of `prev` or `next`) stays value-equal to `next` while
-  // unchanged children — e.g. one untouched element inside a class-typed
-  // container — keep their `prev` identity.
   if (
     Equal.isEqual(prev) &&
     Equal.isEqual(next) &&
@@ -93,18 +77,9 @@ const reconcile = ({ prev, next, depth }: ReconcileArgs): unknown => {
       ? prev
       : Object.create(Object.getPrototypeOf(next), Object.getOwnPropertyDescriptors(out))
   }
-  // Class instances without Equal (Date, Map, …) are opaque leaves.
   return next
 }
 
-/**
- * Substitute `previous` nodes into `next` wherever they are value-equal. The
- * walker only ever returns `previous`, `next`, or a key/index-wise
- * reconstruction of `next` whose every leaf came from one of them, so the
- * result is value-equal to `next` and the type is preserved by construction —
- * the single cast below is that argument, in the style of `wireSources` /
- * `narrowStore`.
- */
 export const reuse = <A>(previous: A, next: A): A =>
   // oxlint-disable-next-line reform-rules/no-type-assertion -- the walker returns a value-equal reconstruction of `next`, type-preserved by construction (the single seam this cast lives at)
   reconcile({ prev: previous, next, depth: MAX_DEPTH }) as A

package/src/internal/scheduler.ts

@@ -1,16 +1,5 @@
 import { Context, Effect, Layer, MutableRef, Option } from 'effect'
 
-/**
- * Coalesces store notifications into a single microtask flush so a batch of
- * writes wakes each subscriber at most once (RESEARCH #3). React owns frame
- * timing; we only collapse the notifications.
- *
- * One scheduler is shared by every store in a runtime, so writes across
- * different stores in the same tick batch into one flush. The instance is
- * resolved per store at creation: `Notifications` when a runtime provides it
- * (per-runtime isolation — see `resolveScheduler`), else the process-wide
- * `defaultScheduler`.
- */
 export interface Scheduler {
   readonly schedule: (listeners: Iterable<() => void>) => void
 }
@@ -19,9 +8,6 @@ export const makeScheduler = (): Scheduler => {
   const pending = new Set<() => void>()
   const armed = MutableRef.make(false)
 
-  // One listener's throw (a defect in a user calc body) must not abandon the
-  // rest of the flush; surface it to the host's global handler on a fresh
-  // microtask instead of unwinding the drain.
   const runListener = (listener: () => void): void =>
     Effect.runSync(
       Effect.try({ try: listener, catch: (error) => error }).pipe(
@@ -36,12 +22,6 @@ export const makeScheduler = (): Scheduler => {
       ),
     )
 
-  // Drain to a fixpoint within ONE microtask. A derived store's `onChange`
-  // re-schedules during the pass (it is itself a listener of its upstream), so
-  // resolving the whole dependency graph here — instead of re-arming a fresh
-  // microtask per layer — collapses a depth-N propagation into a single flush
-  // and wakes each leaf subscriber once at its final value. Converges because
-  // a derived store schedules only when its output actually moves (Equal).
   const drain = (): void => {
     if (pending.size === 0) {
       return
@@ -68,37 +48,17 @@ export const makeScheduler = (): Scheduler => {
   return { schedule }
 }
 
-/**
- * The process-wide scheduler, used by any store created outside a runtime that
- * provides its own `Notifications`. Fine for a single client app (microtask
- * ordering is global anyway); a runtime that needs isolation — concurrent SSR,
- * multiple mounted roots — provides `Notifications` upstream of its stores.
- */
 export const defaultScheduler: Scheduler = makeScheduler()
 
-/**
- * Optional per-runtime scheduler. When a runtime provides it upstream of its
- * state/calc layers, those stores coalesce on it instead of the global default,
- * isolating their notification timing from other runtimes in the same process.
- */
 const NotificationsBase: Context.TagClass<Notifications, 'reform/Notifications', Scheduler> =
   Context.Tag('reform/Notifications')<Notifications, Scheduler>()
 export class Notifications extends NotificationsBase {}
 
-/**
- * A fresh per-runtime scheduler. Merged into `Engine`, so a runtime that wires
- * its state/calc layers *downstream* of `Engine` gets isolated notification
- * timing; the common sibling wiring falls back to `defaultScheduler` (still
- * correct, just process-shared).
- */
-export const notificationsLayer: Layer.Layer<Notifications> = Layer.sync(Notifications, makeScheduler)
+export const notificationsLayer: Layer.Layer<Notifications> = Layer.sync(
+  Notifications,
+  makeScheduler,
+)
 
-/**
- * Resolve the scheduler a store should use: the runtime's `Notifications` if one
- * is in context, else the global default. Uses `serviceOption` so it imposes no
- * hard requirement — a store layer wired as a sibling of the runtime (the common
- * pattern) simply falls back to the default.
- */
 export const resolveScheduler: Effect.Effect<Scheduler> = Effect.map(
   Effect.serviceOption(Notifications),
   Option.getOrElse(() => defaultScheduler),

package/src/internal/seeds.ts

@@ -1,19 +1,5 @@
 import { FiberRef, GlobalValue } from 'effect'
 
-/**
- * The sanctioned tooling/test seam for seeding CLOSED scenes. A scene's layers
- * are pre-composed (each state group seeds its own live store), so an outer
- * layer cannot override an inner store — but a FiberRef set via
- * `Layer.locally(ref, value)(layer)` IS visible inside the construction effects
- * of nested layers. `State.live` consults this ref at store-construction time:
- * if the state's member name is present, the (schema-validated) value replaces
- * the authored seed; otherwise the authored seed wins.
- *
- * Empty by default — production wiring never touches it. The dev-tool inspector
- * (`Scene.seedScene`) and proofs are the only intended writers. `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 CurrentSeedOverrides: FiberRef.FiberRef<Readonly<Record<string, unknown>>> =
   GlobalValue.globalValue(Symbol.for('reform/CurrentSeedOverrides'), () =>
     FiberRef.unsafeMake<Readonly<Record<string, unknown>>>({}),

package/src/internal/sources.ts

@@ -1,49 +1,29 @@
-import { type Context, Effect, Equal, Predicate } from 'effect'
-import { type AnySource, type SourceName, type SourceValue } from '../state/token'
-import { type Store } from './store'
+import { Context, Effect, Equal, Predicate } from 'effect'
+import {
+  type AnySource,
+  type SourceIdentifier,
+  type SourceName,
+  type SourceValue,
+} from '../state/token'
 
-// The reactive plumbing shared by `Calc` and `AsyncCalc`: read a list of input
-// `Source`s, snapshot them by name, project a comparable invalidation key, and
-// subscribe to changes. Both derived primitives sense their inputs the same way
-// and differ only in what they do with a change (recompute vs. re-run a query).
-
-/** The decoded inputs handed to a calc body, keyed by each source's name. */
 export type InputsObject<Inputs extends ReadonlyArray<AnySource>> = {
   readonly [S in Inputs[number] as SourceName<S>]: SourceValue<S>
 }
 
-/**
- * The store services a list of store-carriers requires, as a *union of distinct*
- * stores (each carrier has its own backing tag), not a single store of a union.
- * Structural over the `store` tag, so it serves both calc inputs (`Source`s) and
- * state-group members (`StateClass`es) — anything carrying a `store` tag.
- */
 export type StoresOf<Items extends ReadonlyArray<unknown>> = {
-  [I in keyof Items]: Items[I] extends { readonly store: Context.Tag<infer Svc, any> } ? Svc : never
+  [I in keyof Items]: Items[I] extends {
+    readonly store: Context.Tag<infer Service, infer _Store>
+  }
+    ? Service
+    : never
 }[number]
 
-/** The store requirement a calc's inputs impose. */
 export type InputStores<Inputs extends ReadonlyArray<AnySource>> = StoresOf<Inputs>
 
-/** Project inputs into a comparable key; the calc reacts only when it moves. */
 export type InvalidateBy<Inputs extends ReadonlyArray<AnySource>> = (
   inputs: InputsObject<Inputs>,
 ) => ReadonlyArray<unknown>
 
-/**
- * The runtime key an input contributes to the inputs object. Prefer the
- * explicit `manifest.name` — the string handed to `make` — over the structural
- * `name`: a `Calc`/`AsyncCalc` *class* satisfies `Source` through its static
- * `name`, and a user subclass declaration (`class Feed extends Calc.make(…)`)
- * defines its OWN `name` from the class binding, shadowing the explicit one.
- * That binding is what minifiers rename, so keying the snapshot by `input.name`
- * made every subclassed calc input `undefined` in production builds (and would
- * silently mis-key in dev whenever the binding differs from the `make` name —
- * the type-level key, `SourceName<S>`, is always the `make` string). The
- * manifest is inherited through the static prototype chain and never shadowed.
- * `StateToken`s carry no manifest; their `name` is an instance field holding
- * the explicit member key, so the fallback is always the declared string.
- */
 const inputKey = (input: AnySource): string =>
   Predicate.hasProperty(input, 'manifest') &&
   Predicate.isRecord(input.manifest) &&
@@ -51,41 +31,38 @@ const inputKey = (input: AnySource): string =>
     ? input.manifest['name']
     : input.name
 
-/** Element-wise value equality of two invalidation keys. */
+// Capture an invariant source tag through a covariant read-only surface.
+interface ReadableStore<out A> {
+  readonly getSnapshot: () => A
+  readonly subscribe: (listener: () => void) => () => void
+}
+
+const readStore = <Source extends AnySource>(
+  source: Source,
+): Effect.Effect<ReadableStore<SourceValue<Source>>, never, SourceIdentifier<Source>> =>
+  Context.GenericTag<SourceIdentifier<Source>, ReadableStore<SourceValue<Source>>>(source.store.key)
+
 export const sameKey = (left: ReadonlyArray<unknown>, right: ReadonlyArray<unknown>): boolean =>
-  left.length === right.length && left.every((element, index) => Equal.equals(element, right[index]))
+  left.length === right.length &&
+  left.every((element, index) => Equal.equals(element, right[index]))
 
-/** The sensing surface both `Calc.live` and `AsyncCalc.live` build on. */
 export interface WiredSources<Inputs extends ReadonlyArray<AnySource>> {
-  /** Snapshot every input by name — the decoded inputs object a calc body sees. */
   readonly snapshot: () => InputsObject<Inputs>
-  /** The invalidation key for an inputs object: the projection, or all input values. */
   readonly keyOf: (inputs: InputsObject<Inputs>) => ReadonlyArray<unknown>
-  /** Subscribe to every source at once; the returned thunk unsubscribes from all. */
   readonly subscribe: (listener: () => void) => () => void
 }
 
-/**
- * Read each input's backing store and return the shared sensing surface. The
- * caller owns lifecycle: register the `subscribe` result's unsubscribe as a
- * scope finalizer (both live bodies run under `Layer.scoped`).
- */
 export const wireSources = <Inputs extends ReadonlyArray<AnySource>>(
   inputs: Inputs,
   invalidateBy?: InvalidateBy<Inputs>,
 ): Effect.Effect<WiredSources<Inputs>, never, InputStores<Inputs>> =>
   // oxlint-disable-next-line reform-rules/no-type-assertion -- restate the precise InputStores<Inputs> union the signature promises; Effect.forEach over a heterogeneous tuple widens R (the single seam this cast lives at)
   Effect.gen(function* () {
-    const sources: ReadonlyArray<Store<unknown>> = yield* Effect.forEach(
-      inputs,
-      (input) => input.store,
-    )
+    const sources = yield* Effect.forEach(inputs, readStore)
 
     const snapshot = (): InputsObject<Inputs> => {
       const args: Record<string, unknown> = {}
       inputs.forEach((input, index) => {
-        // `noUncheckedIndexedAccess`: `sources` is built 1:1 with `inputs`, but
-        // guard the index so the read is honestly total.
         const source = sources[index]
         if (source !== undefined) {
           args[inputKey(input)] = source.getSnapshot()

package/src/internal/stateRegistry.ts

@@ -1,19 +1,5 @@
 import { Effect } from 'effect'
 
-/**
- * Module-load registry of the DI tag identifiers minted by `State.make` /
- * `StateFamily.make`. Two distinct definitions that claim one identifier (e.g.
- * `State.make('open')` in two different features) otherwise collapse silently —
- * `Layer.merge` resolves identical tags to the rightmost, with no error. Here we
- * surface the clash.
- *
- * Warned, not thrown — mirroring duplicate reducer/procedure names: a cross-
- * feature clash is a footgun, but a module may legitimately be re-evaluated under
- * the same identifier (HMR), so a hard throw would punish dev reloads. The
- * `warned` set keeps that to one warning per identifier regardless of reloads.
- * In-group clashes (where every member is addressable by name) are a harder error
- * — see `StateGroup.make`, which throws.
- */
 const claimed = new Set<string>()
 const warned = new Set<string>()
 

package/src/internal/store.test.ts

@@ -3,8 +3,6 @@ import { makeStore } from './store'
 
 const tick = () => new Promise<void>((resolve) => queueMicrotask(resolve))
 
-// A const counter we increment in place — subscriber callbacks need somewhere to
-// tally without a reassigned `let`.
 const counter = () => ({ n: 0 })
 
 test('subscribe observes changes; getSnapshot is always current', async () => {
@@ -15,7 +13,7 @@ test('subscribe observes changes; getSnapshot is always current', async () => {
   })
 
   store.set(1)
-  expect(store.getSnapshot()).toBe(1) // snapshot is synchronous
+  expect(store.getSnapshot()).toBe(1)
   await tick()
   expect(notifications.n).toBe(1)
 })

package/src/internal/store.ts

@@ -2,26 +2,6 @@ import { Equal, MutableRef } from 'effect'
 import { type Inspectable, inspectable } from './inspect'
 import { defaultScheduler, type Scheduler } from './scheduler'
 
-/**
- * A reactive cell living outside Effect. The single source of truth for one
- * slice of state. `set` is internal: only the reduce loop ever holds a Store
- * (reducers return values, the loop writes them), which is how "state changes
- * only in the reduce loop" is enforced structurally — there is no public writer.
- *
- * This is the synchronous, React-facing analog of Effect's `SubscriptionRef`
- * (a `Ref` + `PubSub` + a `changes` `Stream`). We don't use `SubscriptionRef`
- * directly because `useSyncExternalStore` requires a *synchronous* `getSnapshot`
- * and a *synchronous* `subscribe` returning an unsubscribe thunk, whereas
- * `SubscriptionRef.get` is an `Effect` and its `changes` is a `Stream` (a fiber
- * per subscription). Mutable state is held in a `MutableRef` (Effect's mutable
- * cell), so there is no reassigned binding.
- *
- * `getSnapshot` + `subscribe` are the stable pair the React bridge binds to;
- * `getSnapshot` returns the same reference until the value actually changes.
- * `getVersion` returns a monotonic counter bumped on every real change — the
- * host sums it across a render's tracked stores for a `useSyncExternalStore`
- * snapshot, which closes the tear/dropped-update window a value snapshot can't.
- */
 export interface Store<in out A> extends Inspectable {
   get(): A
   set(value: A): void
@@ -30,7 +10,6 @@ export interface Store<in out A> extends Inspectable {
   subscribe(listener: () => void): () => void
 }
 
-/** Default change hook — a shared no-op so unprofiled stores pay one skipped call. */
 const noChange = (): void => {}
 
 export const makeStore = <A>(
@@ -38,8 +17,6 @@ export const makeStore = <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)
   const version = MutableRef.make(0)
   const listeners = new Set<() => void>()
@@ -66,18 +43,6 @@ export const makeStore = <A>(
   }
 }
 
-/**
- * A read-only `Store` whose value is computed from upstream sources.
- *
- * Reads are pull-fresh: `get`/`getSnapshot` call `compute` directly, so a
- * headless snapshot always reflects the current source state without waiting for
- * a notification (`compute` must memoize so an unchanged read returns a stable
- * reference — `useSyncExternalStore` requires it). *Notifications*, by contrast,
- * run through the same coalescing scheduler as `makeStore`: an upstream change
- * recomputes once and wakes subscribers only when the output actually moves (by
- * `Equal.equals`), so every store kind shares one notification timing. `set` is
- * a no-op — the only writer is the upstream subscription.
- */
 export const makeDerivedStore = <A>(
   compute: () => A,
   subscribeUpstream: (onChange: () => void) => () => void,
@@ -86,8 +51,6 @@ export const makeDerivedStore = <A>(
 ): { readonly store: Store<A>; readonly unsubscribe: () => void } => {
   const listeners = new Set<() => void>()
   const version = MutableRef.make(0)
-  // The last output we notified against — tracked only here, never touched by
-  // reads, so a `get` racing ahead of `onChange` can't suppress a notification.
   const seen = MutableRef.make<{ readonly value: A } | undefined>({ value: compute() })
   const onChange = () => {
     const previous = MutableRef.get(seen)

package/src/internal/track.ts

@@ -1,37 +1,20 @@
 import { Context, Effect, Option } from 'effect'
 import type { Store } from './store'
 
-/**
- * Anything a render can depend on: a source it can subscribe to for changes and
- * snapshot a monotonic version from. `Store` (and the calc/family stores)
- * structurally satisfy this. The host sums `getVersion()` across a render's
- * tracked sources for its `useSyncExternalStore` snapshot — a value that moves
- * whenever any dependency changes, which is what closes the tear/dropped-update
- * window a per-store value snapshot cannot.
- */
 export interface Subscribable {
   subscribe(listener: () => void): () => void
   getVersion(): number
 }
 
-/** A per-render dependency sink. The renderer provides one; reads record into it. */
 export interface Tracker {
   add(source: Subscribable): void
 }
 
-/**
- * The active render's dependency tracker (D5). Present only while a composition
- * is rendering under `@reform/react`; absent in procedures and headless reads.
- */
-const CurrentTrackerBase: Context.TagClass<CurrentTracker, 'reform/Tracker', Tracker> =
-  Context.Tag('reform/Tracker')<CurrentTracker, Tracker>()
+const CurrentTrackerBase: Context.TagClass<CurrentTracker, 'reform/Tracker', Tracker> = Context.Tag(
+  'reform/Tracker',
+)<CurrentTracker, Tracker>()
 export class CurrentTracker extends CurrentTrackerBase {}
 
-/**
- * Read a store's current snapshot and, if a tracker is active, record the store
- * as a dependency of the current render. One read API, two behaviors by context
- * (D5): inside a render it subscribes the slice; elsewhere it just snapshots.
- */
 export const readTracked = <A>(store: Store<A>): Effect.Effect<A> =>
   Effect.map(Effect.serviceOption(CurrentTracker), (tracker) => {
     if (Option.isSome(tracker)) {

package/src/internal/variance.ts

@@ -0,0 +1,5 @@
+import type { Schema } from 'effect'
+
+export type AnyValue = Schema.Schema.Type<Schema.Schema.AnyNoContext>
+
+export type AnySchema<A> = Schema.Schema<A, Schema.Schema.Encoded<Schema.Schema.AnyNoContext>>