@playfast/reform 1.0.1 → 1.2.0

package/src/calc/asyncCalc.ts

@@ -1,16 +1,15 @@
 import { Context, Effect, Layer, Match, Option, Schema } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import { type AnyEvent } from '../event/event'
-import {
-  type InputsObject,
-  type InputStores,
-  type InvalidateBy,
-} from '../internal/sources'
+import { type InputsObject, type InputStores, type InvalidateBy } from '../internal/sources'
+import type { AnySchema } from '../internal/variance'
 import {
   bumpRevision,
   type GatedOf,
   gatedFlag,
   makeQueryDriver,
+  type QueryCodec,
   RevisionSchema,
   revisionZero,
 } from '../internal/queryDriver'
@@ -20,62 +19,104 @@ import * as Reducer from '../reducer/reducer'
 import { Reducers } from '../runtime/loop'
 import { Queries } from '../runtime/queries'
 import * as State from '../state/state'
-import { type AnySource } from '../state/token'
+import { type AnySource, type Source, type SourceCapture } from '../state/token'
 import { type AsyncData, narrowStore } from './asyncData'
 
-// `AsyncCalc` is `Calc`'s async sibling: a derived store whose value is the
-// lifecycle of an Effect (a query), recomputed reactively from its inputs — the
-// React-Query model, but inside the reform graph and without dispatching events.
-// Definition (`make`) is reflectable data; implementation (`live`) is the effect.
-// The reactive machinery lives in `internal/queryDriver` (shared with
-// `RemoteState`); this module owns the definition shape and the `invalidateOn`
-// sugar.
+export interface AsyncCalcSchemaReflection {
+  readonly ast: Schema.Schema<unknown, unknown, unknown>['ast']
+}
 
-export interface AsyncCalcManifest<N extends string, A, E> extends Manifest {
+export interface AsyncCalcManifest<N extends string, A = unknown, E = never> extends Manifest {
   readonly kind: 'AsyncCalc'
   readonly name: N
-  readonly output: Schema.Schema<A, any>
+  readonly output: AnySchema<A>
   // 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 error?: Schema.Schema<E, any>
-  /** Whether the query can be disabled (drives the `Idle` arm). */
+  readonly error?: AnySchema<E>
   readonly gated: boolean
 }
 
-export interface AsyncCalcClass<
-  out N extends string,
-  out Inputs extends ReadonlyArray<AnySource>,
+export const AsyncCalcStoreTypeId: unique symbol = Symbol.for('reform/AsyncCalcStore')
+export type AsyncCalcStoreTypeId = typeof AsyncCalcStoreTypeId
+
+interface AsyncCalcStoreCompatibilityExternalApi<
+  N extends string,
   in out A,
   in out E,
   in out Gated extends boolean,
-> extends Effect.Effect<AsyncData<A, E, Gated>, never, Store<AsyncData<A, E, Gated>>> {
+> extends Store<AsyncData<A, E, Gated>> {
+  readonly [AsyncCalcStoreTypeId]?: N
+}
+
+export type AsyncCalcStore<
+  N extends string,
+  A,
+  E,
+  Gated extends boolean,
+> = AsyncCalcStoreCompatibilityExternalApi<N, A, E, Gated>
+
+export interface AsyncCalcClass<
+  N extends string,
+  Inputs extends ReadonlyArray<AnySource>,
+  A,
+  E,
+  Gated extends boolean,
+>
+  extends
+    EffectType<AsyncData<A, E, Gated>, never, AsyncCalcStore<N, A, E, Gated>>,
+    Source<N, AsyncData<A, E, Gated>, AsyncCalcStore<N, A, E, Gated>> {
   new (): {}
   readonly manifest: AsyncCalcManifest<N, A, E>
-  readonly store: Context.Tag<Store<AsyncData<A, E, Gated>>, Store<AsyncData<A, E, Gated>>>
-  /** The calc's name, so it doubles as a `Source` input to another (async) calc. */
+  readonly store: Context.Tag<AsyncCalcStore<N, A, E, Gated>, Store<AsyncData<A, E, Gated>>>
   readonly name: N
-  /** Marker data read by `AsyncCalc.live`. */
   readonly inputs: Inputs
-  /** Runtime mirror of `Gated`: whether `disabled` is honored / `Idle` can occur. */
   readonly gated: Gated
 }
 
-export interface AsyncCalcConfig<Inputs extends ReadonlyArray<AnySource>, A, E, AlwaysOn extends boolean> {
+export interface DefinedAsyncCalcClass<
+  N extends string,
+  Inputs extends ReadonlyArray<AnySource>,
+  A,
+  E,
+  Gated extends boolean,
+> extends AsyncCalcClass<N, Inputs, A, E, Gated> {
+  readonly codec: QueryCodec<A>
+  readonly capture: <Result>(visit: SourceCapture<Result>) => Result
+}
+
+type ConfigSchema<ValueOrSchema> = [ValueOrSchema] extends [Schema.Schema.AnyNoContext]
+  ? ValueOrSchema
+  : AnySchema<ValueOrSchema>
+
+type ConfigErrorSchema<ValueOrSchema> = [ValueOrSchema] extends [undefined]
+  ? ValueOrSchema
+  : ConfigSchema<ValueOrSchema>
+
+export interface AsyncCalcConfig<
+  Inputs extends ReadonlyArray<AnySource>,
+  OutputSchema,
+  ErrorSchema,
+  AlwaysOn extends boolean,
+> {
   readonly inputs: Inputs
-  /** Schema of the `Success` value. */
-  readonly output: Schema.Schema<A, any>
-  /** Schema of the failure. Omitted ⇒ the query is infallible and there is no `Error` arm. */
+  readonly output: ConfigSchema<OutputSchema>
   // 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 error?: Schema.Schema<E, any>
-  /** `true` ⇒ the query is always on: no `Idle` arm and `disabled` is rejected on `.live`. */
+  readonly error?: ConfigErrorSchema<ErrorSchema>
   // 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 alwaysOn?: AlwaysOn
 }
 
-/**
- * The `.live` config: the effect plus the reactive logic. `disabled` is only
- * accepted for a gateable query (no `alwaysOn`); `invalidateBy` is the same
- * `queryKey` projection `Calc` uses.
- */
+interface AsyncCalcMakeConfigExternalApi<
+  Inputs extends ReadonlyArray<AnySource>,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+  ErrorSchema extends Schema.Schema.AnyNoContext | undefined,
+  AlwaysOn extends boolean,
+> {
+  readonly inputs: Inputs
+  readonly output: OutputSchema
+  readonly error?: ErrorSchema
+  readonly alwaysOn?: AlwaysOn
+}
+
 export type AsyncCalcLive<
   Inputs extends ReadonlyArray<AnySource>,
   A,
@@ -84,48 +125,19 @@ export type AsyncCalcLive<
   R,
 > = {
   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>
-  /**
-   * Refetch conciliation. `'switch'` (default): a new key cancels the in-flight
-   * run (latest-wins). `'trailing'`: the in-flight run completes; key changes
-   * that arrive meanwhile conflate to the latest, and exactly ONE trailing
-   * refetch runs after it settles — a burst of N invalidations during one
-   * flight costs 2 fetches, not N cancel-restarts.
-   */
   // 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'
-  /**
-   * Structural sharing for `Success` values: reconcile each refetch result
-   * against the previous one, substituting previous nodes wherever value
-   * equality holds — refetches returning mostly-identical data keep unchanged
-   * subtree identities, so downstream memo boundaries skip them. Same pass as
-   * `Calc`'s `reuse`; opt-in (one O(result) walk per settle).
-   */
   // 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
-  /**
-   * Persist the `Success` value through an optional host `QueryStore` (e.g.
-   * `@playfast/reform-query-browser`'s localStorage layer): hydrate it on build
-   * so the value shows instantly (marked stale, so it still refetches) and write
-   * through on each settle. `true` keys it by the calc name; pass `{ key }` to
-   * override — a static string for a singleton, or a function of the inputs to
-   * key a family per-entity (so reactive-input keyed reads never collide on one
-   * slot). Values (de)serialize through the calc's `output` schema. No host
-   * `QueryStore` in context ⇒ inert (no hard requirement added).
-   */
   // 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?:
     | boolean
-    // 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 key?: string | ((inputs: InputsObject<Inputs>) => string) }
 } & (Gated extends true
-  ? // 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 }
-  : // 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?: never })
+  ? { readonly disabled?: (inputs: InputsObject<Inputs>) => boolean }
+  : { readonly disabled?: never })
 
-/** `.live` config plus the optional `invalidateOn` event list (impl signature). */
 export type AsyncCalcLiveWithInvalidateOn<
   Inputs extends ReadonlyArray<AnySource>,
   A,
@@ -133,47 +145,58 @@ export type AsyncCalcLiveWithInvalidateOn<
   Gated extends boolean,
   R,
 > = AsyncCalcLive<Inputs, A, E, Gated, 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 invalidateOn?: ReadonlyArray<AnyEvent>
 }
 
-/** Loose runtime view of `.live` config — `disabled` recovered past its type erasure. */
 export interface AsyncCalcLiveView<Inputs extends ReadonlyArray<AnySource>, A, E, R> {
   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>
-  // 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
-  // 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'
-  // 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
-  // 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?:
     | boolean
-    // 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 key?: string | ((inputs: InputsObject<Inputs>) => string) }
 }
 
-/**
- * Define an async derived value. `output`/`error` schemas and `alwaysOn` shape
- * the value type, so `yield* MyQuery` is typed to exactly the arms that can
- * occur. The query effect itself is supplied by `AsyncCalc.live`.
- */
-export const make = <
+export function make<
   const N extends string,
   const Inputs extends ReadonlyArray<AnySource>,
-  A,
-  E = never,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+  ErrorSchema extends Schema.Schema.AnyNoContext | undefined = undefined,
   const AlwaysOn extends boolean = false,
 >(
   name: N,
-  config: AsyncCalcConfig<Inputs, A, E, AlwaysOn>,
-): AsyncCalcClass<N, Inputs, A, E, GatedOf<AlwaysOn>> => {
-  const store = Context.GenericTag<Store<AsyncData<A, E, GatedOf<AlwaysOn>>>>(
-    `reform/asyncCalc/${name}`,
-  )
-  // Runtime mirror of the type-level `Gated`, typed as its literal in one place.
+  config: AsyncCalcConfig<Inputs, OutputSchema, ErrorSchema, AlwaysOn>,
+): DefinedAsyncCalcClass<
+  N,
+  Inputs,
+  Schema.Schema.Type<OutputSchema>,
+  ErrorSchema extends Schema.Schema.AnyNoContext ? Schema.Schema.Type<ErrorSchema> : never,
+  GatedOf<AlwaysOn>
+>
+export function make<
+  const N extends string,
+  const Inputs extends ReadonlyArray<AnySource>,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+  ErrorSchema extends Schema.Schema.AnyNoContext | undefined = undefined,
+  const AlwaysOn extends boolean = false,
+>(
+  name: N,
+  config: AsyncCalcMakeConfigExternalApi<Inputs, OutputSchema, ErrorSchema, AlwaysOn>,
+): DefinedAsyncCalcClass<
+  N,
+  Inputs,
+  Schema.Schema.Type<OutputSchema>,
+  ErrorSchema extends Schema.Schema.AnyNoContext ? Schema.Schema.Type<ErrorSchema> : never,
+  GatedOf<AlwaysOn>
+> {
+  type A = Schema.Schema.Type<OutputSchema>
+  type E = ErrorSchema extends Schema.Schema.AnyNoContext ? Schema.Schema.Type<ErrorSchema> : never
+  const store = Context.GenericTag<
+    AsyncCalcStore<N, A, E, GatedOf<AlwaysOn>>,
+    Store<AsyncData<A, E, GatedOf<AlwaysOn>>>
+  >(`reform/asyncCalc/${name}`)
   const gated = gatedFlag(config.alwaysOn)
   const manifest: AsyncCalcManifest<N, A, E> = {
     kind: 'AsyncCalc',
@@ -182,30 +205,23 @@ export const make = <
     gated,
     ...(config.error !== undefined ? { error: config.error } : {}),
   }
+  const codec: QueryCodec<A> = {
+    encode: Schema.encode(config.output),
+    decode: Schema.decodeUnknown(config.output),
+  }
   const read = Effect.flatMap(store, readTracked)
-  return yieldableClass(read, {
+  const calc: DefinedAsyncCalcClass<N, Inputs, A, E, GatedOf<AlwaysOn>> = yieldableClass(read, {
     manifest,
+    codec,
     store,
     name,
     inputs: config.inputs,
     gated,
+    capture: <Result>(visit: SourceCapture<Result>): Result => visit(calc),
   })
+  return calc
 }
 
-/**
- * Wire the query and its reactive logic. The query runs on the runtime (its `R`
- * — RPC clients, etc. — is captured from the layer context). A change to an
- * input re-runs it latest-wins (a new run cancels the in-flight one; or, with
- * `coalesce: 'trailing'`, lets it finish and runs one trailing refetch); while a
- * re-run is in flight the last `Success`/`Error` is kept with `refetching: true`.
- * Re-runs are driven by inputs / `invalidateBy` / `disabled` — and, with
- * `invalidateOn`, by listed events: pure sugar that generates a hidden revision
- * state + reducer (the sole writer) and appends the revision to the calc's key,
- * so an event-driven refetch is still just key movement under `Equal.equals`.
- * The hidden pair stays internal — the user's `query`/`invalidateBy` see exactly
- * the declared inputs — and costs the layer one extra requirement: the
- * `Reducers` registry (the `Engine`).
- */
 export function live<
   N extends string,
   Inputs extends ReadonlyArray<AnySource>,
@@ -218,7 +234,7 @@ export function live<
   config: AsyncCalcLive<Inputs, A, E, Gated, R> & {
     readonly invalidateOn: ReadonlyArray<AnyEvent>
   },
-): Layer.Layer<Store<AsyncData<A, E, Gated>>, never, InputStores<Inputs> | R | Reducers>
+): Layer.Layer<AsyncCalcStore<N, A, E, Gated>, never, InputStores<Inputs> | R | Reducers>
 export function live<
   N extends string,
   Inputs extends ReadonlyArray<AnySource>,
@@ -229,7 +245,7 @@ export function live<
 >(
   calc: AsyncCalcClass<N, Inputs, A, E, Gated>,
   config: AsyncCalcLive<Inputs, A, E, Gated, R>,
-): Layer.Layer<Store<AsyncData<A, E, Gated>>, never, InputStores<Inputs> | R>
+): Layer.Layer<AsyncCalcStore<N, A, E, Gated>, never, InputStores<Inputs> | R>
 export function live<
   N extends string,
   Inputs extends ReadonlyArray<AnySource>,
@@ -240,49 +256,31 @@ export function live<
 >(
   calc: AsyncCalcClass<N, Inputs, A, E, Gated>,
   config: AsyncCalcLiveWithInvalidateOn<Inputs, A, E, Gated, R>,
-  // The wide-R implementation signature behind precise overloads — the same
-  // seam `Reducer.live` uses; both overload returns are assignable (RIn is
-  // covariant), so no value is ever cast.
-): Layer.Layer<Store<AsyncData<A, E, Gated>>, never, any> {
-  // The hidden revision pair, built once per `live` call. Namespacing the state
-  // by the calc's name (`reform/state/${calcName}/invalidateOn`) keeps the tag
-  // out of any plausible user namespace; the duplicate-reducer check is
-  // warning-only and calc names are unique by convention.
+): Layer.Layer<AsyncCalcStore<N, A, E, Gated>, never, InputStores<Inputs> | R | Reducers> {
   const revisionState =
     config.invalidateOn === undefined
       ? undefined
       : State.make(`${calc.manifest.name}/invalidateOn`, RevisionSchema)
 
-  // Scoped so the source subscriptions and the driver fiber are released when
-  // the layer's scope closes (each proof/test builds and disposes its runtime).
   const driver = Layer.scoped(
     calc.store,
     Effect.gen(function* () {
-      // `disabled` is rejected at the type level for non-gated calcs (erased to
-      // `never` there); read it through a loose view for the runtime.
-      // oxlint-disable-next-line reform-rules/no-type-assertion -- loose runtime view: `disabled` is type-erased to `never` for non-gated calcs, no guard recovers it
-      const cfg = config as AsyncCalcLiveView<Inputs, A, E, R>
+      const cfg: AsyncCalcLiveView<Inputs, A, E, R> = config
 
-      // `persist: true` keys by the calc name; `{ key }` overrides — a static
-      // string for a singleton, or a function of the inputs for a keyed family
-      // (the driver resolves the function per-input at hydrate/write). The driver
-      // (de)serializes through the calc's own `output` schema.
       const persistOption = cfg.persist
       const persistKey =
         persistOption === true || persistOption === undefined || persistOption === false
           ? calc.manifest.name
-          : persistOption.key ?? calc.manifest.name
+          : (persistOption.key ?? calc.manifest.name)
+      const persistCodec: QueryCodec<A> = {
+        encode: Schema.encode(calc.manifest.output),
+        decode: Schema.decodeUnknown(calc.manifest.output),
+      }
       const persist =
         persistOption === undefined || persistOption === false
           ? undefined
-          : { key: persistKey, schema: calc.manifest.output }
+          : { key: persistKey, codec: persistCodec }
 
-      // The hidden revision store, read requirement-free (`serviceOption`): the
-      // assembly below always provides it alongside this driver, and feeding it
-      // through `extraKey` (not `wireSources`) keeps it out of the snapshot —
-      // the user's `query` and `invalidateBy` receive exactly
-      // `InputsObject<Inputs>`, with no hidden property to leak into
-      // spread-into-RPC payloads.
       const revision = yield* Match.value(revisionState).pipe(
         Match.when(undefined, () => Effect.succeed(undefined)),
         Match.orElse((state) =>
@@ -308,7 +306,6 @@ export function live<
         extraKey,
       })
 
-      // The internal store is the full union; narrow to the definition's arms.
       return narrowStore<A, E, Gated>(driver.store)
     }),
   )
@@ -316,12 +313,6 @@ export function live<
   if (config.invalidateOn === undefined || revisionState === undefined) {
     return driver
   }
-  // The hidden reducer: an ordinary `Reducer` folding every listed event to
-  // n + 1 — the revision's sole writer, registered/unregistered with this
-  // layer's scope like any user reducer. `Layer.provide` builds the hidden
-  // state once and feeds the same store to both the driver and the reducer,
-  // while the outer context (user inputs, the `Reducers` registry) passes
-  // through untouched.
   const revisionReducer = Reducer.make(`${calc.manifest.name}/invalidateOn`, {
     states: [revisionState],
     events: config.invalidateOn,
@@ -331,14 +322,6 @@ export function live<
   )
 }
 
-/**
- * Mark a query's value stale (`isStale := true`) — without fetching. A stale
- * query with active readers (a mounted view) refetches; an unread one refetches
- * when next subscribed. The imperative counterpart of `invalidateOn`, and what a
- * focus/online provider layer calls. A no-op if the calc isn't live; resolves the
- * `Queries` registry (part of `Engine`).
- */
-/** The minimal calc shape `invalidate`/`refetch` need: just its registry name. */
 export interface NamedCalc {
   readonly name: string
 }
@@ -348,11 +331,5 @@ export const invalidate = (calc: NamedCalc): Effect.Effect<void, never, Queries>
     Effect.sync(() => queries.byName.get(calc.name)?.invalidate()),
   )
 
-/**
- * Force an immediate refetch of the current key, bypassing the no-op-key guard
- * and independent of `isStale`. A no-op if the calc isn't live or is disabled.
- */
 export const refetch = (calc: NamedCalc): Effect.Effect<void, never, Queries> =>
-  Effect.flatMap(Queries, (queries) =>
-    Effect.sync(() => queries.byName.get(calc.name)?.refetch()),
-  )
+  Effect.flatMap(Queries, (queries) => Effect.sync(() => queries.byName.get(calc.name)?.refetch()))

package/src/calc/asyncData.ts

@@ -1,50 +1,31 @@
 import { type Store } from '../internal/store'
 
-// The value an `AsyncCalc` holds: a tagged union of the query's lifecycle,
-// consumed with `effect`'s `Match` (`Match.value(data).pipe(Match.tag('Success', …))`).
-//
-// The shape is narrowed by the definition, so you only handle arms that can
-// occur: `Idle` exists only for a gateable query (no `alwaysOn`), and `Error`
-// exists only when the query declares an `error` schema. There is no separate
-// "refreshing" arm — a re-fetch keeps the last `Success`/`Error` and flips its
-// `refetching` flag (stale-while-revalidate), so the UI never flashes empty.
-
-/** A gated query that is currently switched off (only when not `alwaysOn`). */
 export interface AsyncIdle {
   readonly _tag: 'Idle'
 }
 
-/** The first fetch, before any value exists. */
 export interface AsyncLoading {
   readonly _tag: 'Loading'
 }
 
-/** A resolved value; `refetching` is true while a background re-fetch runs. */
 export interface AsyncSuccess<A> {
   readonly _tag: 'Success'
   readonly value: A
   readonly refetching: boolean
 }
 
-/** A failed query; `refetching` is true while a background re-fetch runs. */
 export interface AsyncError<E> {
   readonly _tag: 'Error'
   readonly error: E
   readonly refetching: boolean
 }
 
-/**
- * The query lifecycle. `Gated` adds the `Idle` arm (a disable-able query); a
- * non-`never` `E` adds the `Error` arm. Both are decided at `AsyncCalc.make`, so
- * `yield* MyQuery` is typed to exactly the arms that can occur.
- */
 export type AsyncData<A, E = never, Gated extends boolean = false> =
   | (Gated extends true ? AsyncIdle : never)
   | AsyncLoading
   | AsyncSuccess<A>
   | ([E] extends [never] ? never : AsyncError<E>)
 
-/** The full (un-narrowed) union — used internally by the live store. */
 export type AnyAsyncData<A, E> = AsyncIdle | AsyncLoading | AsyncSuccess<A> | AsyncError<E>
 
 const idle: AsyncIdle = { _tag: 'Idle' }
@@ -60,7 +41,6 @@ const error = <E>(err: E, refetching = false): AsyncError<E> => ({
   refetching,
 })
 
-/** The arm-constructor namespace exposed as `AsyncData`. */
 export interface AsyncDataConstructors {
   readonly idle: AsyncIdle
   readonly loading: AsyncLoading
@@ -68,31 +48,14 @@ export interface AsyncDataConstructors {
   readonly error: <E>(err: E, refetching?: boolean) => AsyncError<E>
 }
 
-/**
- * Constructors for the arms, namespaced under the same name as the type so call
- * sites read `AsyncData.success(v)` / `AsyncData.error(e)` — no `error` import
- * shadowing the keyword and one obvious home for every arm.
- */
 export const AsyncData: AsyncDataConstructors = { idle, loading, success, error }
 
-/**
- * Narrow the live store (which holds the full `AnyAsyncData` union) to the arms
- * the definition actually permits (`Gated`/`E`). The single documented home for
- * that narrowing, so `AsyncCalc.live` returns it without an inline cast.
- */
 export const narrowStore = <A, E, Gated extends boolean>(
   store: Store<AnyAsyncData<A, E>>,
 ): Store<AsyncData<A, E, Gated>> =>
   // oxlint-disable-next-line reform-rules/no-type-assertion -- type-level narrow of the SAME runtime store to the definition's permitted arms; the single documented home for this seam
   store as unknown as Store<AsyncData<A, E, Gated>>
 
-/**
- * The read-only inverse of `narrowStore`: widen a definition-narrowed store back
- * to the full union, so a consumer (the `RemoteState` overlay) can dispatch on the
- * lifecycle arms without carrying the definition's `Gated`/`E` conditionals.
- * Sound for reads only — every narrowed value IS an `AnyAsyncData` — so callers
- * must never `set` through the widened view (derived stores ignore `set` anyway).
- */
 export const widenStore = <A, E, Gated extends boolean>(
   store: Store<AsyncData<A, E, Gated>>,
 ): Store<AnyAsyncData<A, E>> =>