@playfast/reform 0.1.0 → 1.1.1

package/src/internal/queryDriverStore.ts

@@ -0,0 +1,153 @@
+import { Effect, MutableRef, Option, Schema } from 'effect'
+import type { AnyAsyncData } from '../calc/asyncData'
+import { type QueryState, toAsyncData } from '../calc/queryState'
+import type { QueryStoreApi } from './queryStore'
+import type { Scheduler } from './scheduler'
+import { makeDerivedStore, type Store } from './store'
+import type { AnySchema } from './variance'
+import type { InputsObject } from './sources'
+import type { AnySource } from '../state/token'
+
+interface HydrateQueryOptions<A, E> {
+  readonly cacheKey: string
+  readonly queryStore: QueryStoreApi
+  readonly schema: AnySchema<A>
+  readonly stateStore: Store<QueryState<A, E>>
+}
+
+export const hydrateQuery = <A, E>(
+  options: HydrateQueryOptions<A, E>,
+): Effect.Effect<void> =>
+  Effect.flatMap(options.queryStore.get(options.cacheKey), (cached) =>
+    Option.match(cached, {
+      onNone: () => Effect.void,
+      onSome: (raw) =>
+        Schema.decodeUnknown(options.schema)(raw).pipe(
+          Effect.match({
+            onFailure: () => undefined,
+            onSuccess: (decoded) =>
+              options.stateStore.set({
+                data: Option.some(decoded),
+                error: Option.none(),
+                isFetching: false,
+                isStale: true,
+              }),
+          }),
+        ),
+    }),
+  )
+
+interface PersistQueryValueOptions<A> {
+  readonly cacheKey: string
+  readonly produced: A
+  readonly queryStore: QueryStoreApi
+  readonly schema: AnySchema<A>
+}
+
+export const persistQueryValue = <A>(options: PersistQueryValueOptions<A>): Effect.Effect<void> =>
+  Schema.encode(options.schema)(options.produced).pipe(
+    Effect.flatMap((encoded) => options.queryStore.set(options.cacheKey, encoded)),
+    Effect.ignore,
+  )
+
+interface PersistWriterOptions<Inputs extends ReadonlyArray<AnySource>, A> {
+  readonly persist:
+    | { readonly key: string | ((inputs: InputsObject<Inputs>) => string); readonly schema: AnySchema<A> }
+    | undefined
+  readonly queryStore: QueryStoreApi
+}
+
+export const makePersistWriter = <Inputs extends ReadonlyArray<AnySource>, A>(
+  options: PersistWriterOptions<Inputs, A>,
+): ((produced: A, inputs: InputsObject<Inputs>) => Effect.Effect<void>) => {
+  if (options.persist === undefined) {
+    return () => Effect.void
+  }
+  const persist = options.persist
+  return (produced, inputs) =>
+    persistQueryValue({
+      cacheKey: typeof persist.key === 'function' ? persist.key(inputs) : persist.key,
+      produced,
+      queryStore: options.queryStore,
+      schema: persist.schema,
+    })
+}
+
+interface SubscribableSource {
+  readonly subscribe: (listener: () => void) => () => void
+}
+
+export const subscribeQuerySources = (
+  sources: SubscribableSource,
+  extraKey: SubscribableSource | undefined,
+  listener: () => void,
+): (() => void) => {
+  const offSources = sources.subscribe(listener)
+  const offExtra = extraKey?.subscribe(listener)
+  return () => {
+    offSources()
+    offExtra?.()
+  }
+}
+
+export const settleQueryError = <A, E>(stateStore: Store<QueryState<A, E>>, error: E): void => {
+  const previous = stateStore.get()
+  stateStore.set({ ...previous, error: Option.some(error), isFetching: false })
+}
+
+export const incrementGeneration = (generation: MutableRef.MutableRef<number>): number => {
+  MutableRef.update(generation, (current) => current + 1)
+  return MutableRef.get(generation)
+}
+
+interface QueryProjectionOptions<A, E> {
+  readonly gated: boolean
+  readonly scheduler: Scheduler
+  readonly stateStore: Store<QueryState<A, E>>
+}
+
+export const makeQueryProjection = <A, E>(
+  options: QueryProjectionOptions<A, E>,
+): { readonly store: Store<AnyAsyncData<A, E>>; readonly unsubscribe: () => void } => {
+  const projection = MutableRef.make<
+    { readonly state: QueryState<A, E>; readonly view: AnyAsyncData<A, E> } | undefined
+  >(undefined)
+  const project = (): AnyAsyncData<A, E> => {
+    const state = options.stateStore.get()
+    const previous = MutableRef.get(projection)
+    if (
+      previous !== undefined &&
+      previous.state.data === state.data &&
+      previous.state.error === state.error &&
+      previous.state.isFetching === state.isFetching
+    ) {
+      return previous.view
+    }
+    const view = toAsyncData(state, options.gated)
+    MutableRef.set(projection, { state, view })
+    return view
+  }
+  return makeDerivedStore(project, options.stateStore.subscribe, options.scheduler)
+}
+
+interface ReaderStoreOptions<A, E> {
+  readonly store: Store<AnyAsyncData<A, E>>
+  readonly readers: MutableRef.MutableRef<number>
+  readonly onFirstReader: () => void
+}
+
+export const withReaderTracking = <A, E>(options: ReaderStoreOptions<A, E>): Store<AnyAsyncData<A, E>> => ({
+  ...options.store,
+  subscribe: (listener) => {
+    const before = MutableRef.get(options.readers)
+    MutableRef.set(options.readers, before + 1)
+    const off = options.store.subscribe(listener)
+    if (before === 0) {
+      options.onFirstReader()
+    }
+    return () => {
+      off()
+      MutableRef.update(options.readers, (count) => Math.max(0, count - 1))
+    }
+  },
+})

package/src/internal/queryDriverTypes.ts

@@ -0,0 +1,57 @@
+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 } }
@@ -54,9 +51,6 @@ describe('reuse', () => {
     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 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 +60,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) {
@@ -91,7 +81,6 @@ describe('reuse', () => {
     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
   }
@@ -77,12 +64,6 @@ const reconcile = ({ prev, next, depth }: ReconcileArgs): unknown => {
     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 +74,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,14 @@ 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)
 
-/**
- * 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,24 @@
 import { type Context, Effect, Equal, Predicate } from 'effect'
 import { type AnySource, type SourceName, type SourceValue } from '../state/token'
 import { type Store } from './store'
+import type { AnyValue } from './variance'
 
-// 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 Svc, AnyValue> }
+    ? Svc
+    : 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,25 +26,15 @@ const inputKey = (input: AnySource): string =>
     ? input.manifest['name']
     : input.name
 
-/** Element-wise value equality of two invalidation keys. */
 export const sameKey = (left: ReadonlyArray<unknown>, right: ReadonlyArray<unknown>): boolean =>
   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>,
@@ -84,8 +49,6 @@ export const wireSources = <Inputs extends ReadonlyArray<AnySource>>(
     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)
 })