@playfast/reform 0.0.10 → 0.1.0

package/README.md

@@ -13,7 +13,7 @@ State, events, reducers, derived values, async & remote data, and compositions
 
 ---
 
-reform is an application framework built on [Effect](https://effect.website). You describe your app as **definitions** — state, events, reducers, calculations, compositions — and provide their behavior **separately** as Effect layers. The core renders nothing: a host package ([`@playfast/react`](https://www.npmjs.com/package/@playfast/react), [`@playfast/react-native`](https://www.npmjs.com/package/@playfast/react-native)) turns a closed *scene* into a live tree, and [`@playfast/proof`](https://www.npmjs.com/package/@playfast/proof) drives that same scene headlessly in tests. One model, three consumers, no seam between them.
+reform is an application framework built on [Effect](https://effect.website). You describe your app as **definitions** — state, events, reducers, calculations, compositions — and provide their behavior **separately** as Effect layers. The core renders nothing: a host package ([`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react), [`@playfast/reform-react-native`](https://www.npmjs.com/package/@playfast/reform-react-native)) turns a closed *scene* into a live tree, and [`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof) drives that same scene headlessly in tests. One model, three consumers, no seam between them.
 
 ## Install
 
@@ -474,7 +474,7 @@ const AppScene = scene(AppRoot, {
 })
 ```
 
-`provide` is the list of layers that close the app (they must resolve to `MountedServices` — every composition's render service plus the `Bus`). Hand the scene to [`@playfast/react`](https://www.npmjs.com/package/@playfast/react) to mount or to [`@playfast/proof`](https://www.npmjs.com/package/@playfast/proof) to assert. `seedScene` overlays seed values onto already-closed layers (used by the dev tool to preview alternative initial state).
+`provide` is the list of layers that close the app (they must resolve to `MountedServices` — every composition's render service plus the `Bus`). Hand the scene to [`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react) to mount or to [`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof) to assert. `seedScene` overlays seed values onto already-closed layers (used by the dev tool to preview alternative initial state).
 
 ---
 
@@ -495,7 +495,7 @@ const AppLayer = Layer.mergeAll(
 )
 ```
 
-Also exported for hosts and headless tests: `Bus` / `publish(priority, event)` / `Priority` (`'High' | 'Normal'`); the `Reducers` / `Channels` / `Procedures` registries and their `ReducerEntry` / `ProcedureEntry` shapes; `CaptureSink` (the capturing UI sink proofs assert against); the tagged errors (`DuplicateRegistration`, `FeatureLoadFailed`, `InvalidProvideTarget`, `SlotRenderingUnavailable`, `UnknownGroupState`, `AsyncReducer`); and the **notification scheduler** — `Notifications` / `notificationsLayer` / `makeScheduler` / `defaultScheduler`, which hosts provide upstream for per-runtime isolation (concurrent SSR, multiple mounted roots). Everything else coalesces on the process-wide default scheduler.
+Also exported for hosts and headless tests: `Bus` / `publish(priority, event)` / `Priority` (`'High' | 'Normal'`); the `Reducers` / `Channels` / `Procedures` registries and their `ReducerEntry` / `ProcedureEntry` shapes; `CaptureSink` (the capturing UI sink proofs assert against); the tagged errors (`AsyncReducer`, `AsyncSceneLayer`, `DuplicateRegistration`, `FeatureLoadFailed`, `InvalidProvideTarget`, `UnknownGroupState`); and the **notification scheduler** — `Notifications` / `notificationsLayer` / `makeScheduler` / `defaultScheduler`, which hosts provide upstream for per-runtime isolation (concurrent SSR, multiple mounted roots). Everything else coalesces on the process-wide default scheduler.
 
 ---
 
@@ -533,7 +533,7 @@ const logic = Layer.mergeAll(
   }),
 )
 
-// a DOM presentation (rendered by @playfast/react)
+// a DOM presentation (rendered by @playfast/reform-react)
 const view = provide(CounterUi, Ui.make(CounterUi, ({ count }, _s, { bump }) =>
   <button onClick={() => bump({ by: 1 })}>count: {count}</button>
 ))
@@ -541,7 +541,7 @@ const view = provide(CounterUi, Ui.make(CounterUi, ({ count }, _s, { bump }) =>
 export const CounterScene = scene(Counter, { provide: [Engine, logic, view] })
 ```
 
-Mount it with [`@playfast/react`](https://www.npmjs.com/package/@playfast/react), or prove it headlessly with [`@playfast/proof`](https://www.npmjs.com/package/@playfast/proof) — the same `CounterScene` value.
+Mount it with [`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react), or prove it headlessly with [`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof) — the same `CounterScene` value.
 
 ---
 
@@ -550,12 +550,12 @@ Mount it with [`@playfast/react`](https://www.npmjs.com/package/@playfast/react)
 | Package | Role |
 | --- | --- |
 | **`@playfast/reform`** | Renderer-neutral core (this package) |
-| [`@playfast/react`](https://www.npmjs.com/package/@playfast/react) | React / DOM host |
-| [`@playfast/react-native`](https://www.npmjs.com/package/@playfast/react-native) | React Native host |
-| [`@playfast/forms`](https://www.npmjs.com/package/@playfast/forms) | Headless form state |
-| [`@playfast/forms-react`](https://www.npmjs.com/package/@playfast/forms-react) | Typed JSX mapping for forms |
-| [`@playfast/proof`](https://www.npmjs.com/package/@playfast/proof) | Headless testing toolkit |
-| [`@playfast/eslint-plugin`](https://www.npmjs.com/package/@playfast/eslint-plugin) | Lint rules for reform conventions |
+| [`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react) | React / DOM host |
+| [`@playfast/reform-react-native`](https://www.npmjs.com/package/@playfast/reform-react-native) | React Native host |
+| [`@playfast/reform-forms`](https://www.npmjs.com/package/@playfast/reform-forms) | Headless form state |
+| [`@playfast/reform-forms-react`](https://www.npmjs.com/package/@playfast/reform-forms-react) | Typed JSX mapping for forms |
+| [`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof) | Headless testing toolkit |
+| [`@playfast/reform-eslint-plugin`](https://www.npmjs.com/package/@playfast/reform-eslint-plugin) | Lint rules for reform conventions |
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform",
   "playbook": "./playbook",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "type": "module",
   "description": "The renderer-neutral core of the reform framework — typed, headless state, events, reducers, derived values, async/remote data, and compositions built on Effect.",
   "keywords": [

package/src/boundary/boundary.ts

@@ -102,6 +102,7 @@ export interface BoundaryOptions {
    * loading state. Without the latch the boundary re-pends on any covered
    * first load, which is what a per-screen boundary wants.
    */
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- public options-bag input; omission is the documented default (no latch) and external callers pass a plain `{ once: true }` literal
   readonly once?: boolean
 }
 
@@ -153,19 +154,23 @@ export const live = <N extends string, Over extends ReadonlyArray<AnyLifecycleSo
         { readonly key: ReadonlyArray<unknown>; readonly value: BoundaryState } | undefined
       >(undefined)
       const recompute = (): BoundaryState => {
-        if (options.once === true && MutableRef.get(latched)) return readyArm
+        if (options.once === true && MutableRef.get(latched)) {
+          return readyArm
+        }
         const arms = sources.keyOf(sources.snapshot())
         const prev = MutableRef.get(memo)
-        if (prev !== undefined && sameKey(arms, prev.key)) return prev.value
+        if (prev !== undefined && sameKey(arms, prev.key)) {
+          return prev.value
+        }
         const errors = arms.flatMap(errorOf)
-        const value =
+        const mergedArm =
           errors.length > 0
             ? erroredArm(errors)
             : arms.some((arm) => tagOf(arm) === 'Loading')
               ? pendingArm
               : readyArm
-        MutableRef.set(memo, { key: arms, value })
-        return value
+        MutableRef.set(memo, { key: arms, value: mergedArm })
+        return mergedArm
       }
 
       const derived = makeDerivedStore(recompute, sources.subscribe, scheduler)
@@ -181,9 +186,13 @@ export const live = <N extends string, Over extends ReadonlyArray<AnyLifecycleSo
         // Ready self-corrects within the flush for readers, but a latch taken
         // there would freeze it; a subscriber runs only after the fixpoint,
         // where the value is converged.
-        if (recompute()._tag === 'Ready') MutableRef.set(latched, true)
+        if (recompute()._tag === 'Ready') {
+          MutableRef.set(latched, true)
+        }
         const offSelf = derived.store.subscribe(() => {
-          if (derived.store.get()._tag === 'Ready') MutableRef.set(latched, true)
+          if (derived.store.get()._tag === 'Ready') {
+            MutableRef.set(latched, true)
+          }
         })
         yield* Effect.addFinalizer(() => Effect.sync(offSelf))
       }

package/src/calc/asyncCalc.ts

@@ -1,4 +1,4 @@
-import { Context, Effect, Layer, Option, Schema } from 'effect'
+import { Context, Effect, Layer, Match, Option, Schema } from 'effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import { type AnyEvent } from '../event/event'
 import {
@@ -35,6 +35,7 @@ export interface AsyncCalcManifest<N extends string, A, E> extends Manifest {
   readonly kind: 'AsyncCalc'
   readonly name: N
   readonly output: Schema.Schema<A, any>
+  // 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 gated: boolean
@@ -63,8 +64,10 @@ export interface AsyncCalcConfig<Inputs extends ReadonlyArray<AnySource>, A, E,
   /** 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. */
+  // 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`. */
+  // 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
 }
 
@@ -81,6 +84,7 @@ 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
@@ -89,6 +93,7 @@ export type AsyncCalcLive<
    * 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
@@ -97,19 +102,58 @@ export type AsyncCalcLive<
    * 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. Values (de)serialize through the calc's `output` schema. No host
+   * 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).
    */
-  readonly persist?: boolean | { readonly key?: string }
+  // 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
-  ? { readonly disabled?: (inputs: InputsObject<Inputs>) => boolean }
-  : { readonly disabled?: never })
+  ? // 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 })
+
+/** `.live` config plus the optional `invalidateOn` event list (impl signature). */
+export type AsyncCalcLiveWithInvalidateOn<
+  Inputs extends ReadonlyArray<AnySource>,
+  A,
+  E,
+  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
@@ -195,9 +239,7 @@ export function live<
   R,
 >(
   calc: AsyncCalcClass<N, Inputs, A, E, Gated>,
-  config: AsyncCalcLive<Inputs, A, E, Gated, R> & {
-    readonly invalidateOn?: ReadonlyArray<AnyEvent>
-  },
+  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.
@@ -218,25 +260,22 @@ export function live<
     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.
-      const cfg = config as {
-        readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
-        readonly invalidateBy?: InvalidateBy<Inputs>
-        readonly disabled?: (inputs: InputsObject<Inputs>) => boolean
-        readonly coalesce?: 'switch' | 'trailing'
-        readonly reuse?: boolean
-        readonly persist?: boolean | { readonly key?: string }
-      }
+      // 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>
 
-      // `persist: true` keys by the calc name; `{ key }` overrides. The driver
+      // `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
       const persist =
-        cfg.persist === undefined || cfg.persist === false
+        persistOption === undefined || persistOption === false
           ? undefined
-          : {
-              key:
-                cfg.persist === true ? calc.manifest.name : cfg.persist.key ?? calc.manifest.name,
-              schema: calc.manifest.output,
-            }
+          : { key: persistKey, schema: calc.manifest.output }
 
       // The hidden revision store, read requirement-free (`serviceOption`): the
       // assembly below always provides it alongside this driver, and feeding it
@@ -244,10 +283,17 @@ export function live<
       // the user's `query` and `invalidateBy` receive exactly
       // `InputsObject<Inputs>`, with no hidden property to leak into
       // spread-into-RPC payloads.
-      const revision =
-        revisionState === undefined
-          ? undefined
-          : Option.getOrUndefined(yield* Effect.serviceOption(revisionState.store))
+      const revision = yield* Match.value(revisionState).pipe(
+        Match.when(undefined, () => Effect.succeed(undefined)),
+        Match.orElse((state) =>
+          Effect.serviceOption(state.store).pipe(Effect.map(Option.getOrUndefined)),
+        ),
+      )
+      const extraKeyFor = (rev: NonNullable<typeof revision>) => ({
+        read: () => rev.getSnapshot(),
+        subscribe: (listener: () => void) => rev.subscribe(listener),
+      })
+      const extraKey = revision === undefined ? undefined : extraKeyFor(revision)
       const driver = yield* makeQueryDriver({
         name: calc.manifest.name,
         label: 'AsyncCalc',
@@ -259,13 +305,7 @@ export function live<
         coalesce: cfg.coalesce,
         reuse: cfg.reuse,
         persist,
-        extraKey:
-          revision === undefined
-            ? undefined
-            : {
-                read: () => revision.getSnapshot(),
-                subscribe: (listener) => revision.subscribe(listener),
-              },
+        extraKey,
       })
 
       // The internal store is the full union; narrow to the definition's arms.
@@ -273,7 +313,9 @@ export function live<
     }),
   )
 
-  if (config.invalidateOn === undefined || revisionState === undefined) return driver
+  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
@@ -296,7 +338,12 @@ export function live<
  * focus/online provider layer calls. A no-op if the calc isn't live; resolves the
  * `Queries` registry (part of `Engine`).
  */
-export const invalidate = (calc: { readonly name: string }): Effect.Effect<void, never, Queries> =>
+/** The minimal calc shape `invalidate`/`refetch` need: just its registry name. */
+export interface NamedCalc {
+  readonly name: string
+}
+
+export const invalidate = (calc: NamedCalc): Effect.Effect<void, never, Queries> =>
   Effect.flatMap(Queries, (queries) =>
     Effect.sync(() => queries.byName.get(calc.name)?.invalidate()),
   )
@@ -305,7 +352,7 @@ export const invalidate = (calc: { readonly name: string }): Effect.Effect<void,
  * 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: { readonly name: string }): Effect.Effect<void, never, Queries> =>
+export const refetch = (calc: NamedCalc): Effect.Effect<void, never, Queries> =>
   Effect.flatMap(Queries, (queries) =>
     Effect.sync(() => queries.byName.get(calc.name)?.refetch()),
   )

package/src/calc/asyncData.ts

@@ -49,9 +49,9 @@ export type AnyAsyncData<A, E> = AsyncIdle | AsyncLoading | AsyncSuccess<A> | As
 
 const idle: AsyncIdle = { _tag: 'Idle' }
 const loading: AsyncLoading = { _tag: 'Loading' }
-const success = <A>(value: A, refetching = false): AsyncSuccess<A> => ({
+const success = <A>(payload: A, refetching = false): AsyncSuccess<A> => ({
   _tag: 'Success',
-  value,
+  value: payload,
   refetching,
 })
 const error = <E>(err: E, refetching = false): AsyncError<E> => ({
@@ -82,7 +82,9 @@ export const AsyncData: AsyncDataConstructors = { idle, loading, success, error
  */
 export const narrowStore = <A, E, Gated extends boolean>(
   store: Store<AnyAsyncData<A, E>>,
-): Store<AsyncData<A, E, Gated>> => store as unknown as Store<AsyncData<A, E, Gated>>
+): 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
@@ -93,4 +95,6 @@ export const narrowStore = <A, E, Gated extends boolean>(
  */
 export const widenStore = <A, E, Gated extends boolean>(
   store: Store<AsyncData<A, E, Gated>>,
-): Store<AnyAsyncData<A, E>> => store as unknown as Store<AnyAsyncData<A, E>>
+): Store<AnyAsyncData<A, E>> =>
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- read-only widen of the SAME runtime store back to the full union; sound for reads, documented inverse of narrowStore
+  store as unknown as Store<AnyAsyncData<A, E>>

package/src/calc/calc.ts

@@ -17,7 +17,9 @@ import { type AnySource } from '../state/token'
 // even though the reactive plumbing now lives in `internal/sources`.
 export { type InputsObject, type InputStores, type InvalidateBy } from '../internal/sources'
 
-export interface CalcOptions<Inputs extends ReadonlyArray<AnySource>> {
+// Boundary config object: optional fields are the framework's public, JSON-like
+// definition surface (`ExternalApi` postfix exempts them from `no-optional-fields`).
+export interface CalcOptionsExternalApi<Inputs extends ReadonlyArray<AnySource>> {
   /**
    * Custom invalidation: recompute only when the projected key changes by value
    * equality (React-Query's `queryKey`). Omitted ⇒ recompute when any input
@@ -83,7 +85,7 @@ export const make = <const N extends string, const Inputs extends ReadonlyArray<
 export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>, Out>(
   calc: CalcClass<N, Inputs, Out>,
   compute: (inputs: InputsObject<Inputs>) => Out,
-  options: CalcOptions<Inputs> = {},
+  options: CalcOptionsExternalApi<Inputs> = {},
 ): Layer.Layer<Store<Out>, never, InputStores<Inputs>> =>
   // Scoped so the source subscriptions are released when the layer's scope
   // closes (each proof/test builds and disposes its own runtime).
@@ -102,7 +104,9 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
         const args = sources.snapshot()
         const key = sources.keyOf(args)
         const prev = MutableRef.get(memo)
-        if (prev !== undefined && sameKey(key, prev.key)) return prev.output
+        if (prev !== undefined && sameKey(key, prev.key)) {
+          return prev.output
+        }
         const fresh = compute(args)
         // With `reuse`, a recompute that lands value-equal to the previous
         // output returns the previous reference — the derived store's Equal

package/src/calc/calcFamily.ts

@@ -84,9 +84,11 @@ export const read = <N extends string, Inputs extends ReadonlyArray<AnySource>,
   family: CalcFamilyClass<N, Inputs, K, Out>,
   key: K,
 ): Effect.Effect<Out, never, FamilyStore<K, Out>> =>
-  Effect.flatMap(family.store, (fs) => readTracked(fs.at(key)))
+  Effect.flatMap(family.store, (familyStore) => readTracked(familyStore.at(key)))
 
-export interface CalcFamilyLiveOptions<Inputs extends ReadonlyArray<AnySource>>
+// Boundary config object: optional fields are the framework's public, JSON-like
+// definition surface (`ExternalApi` postfix exempts them from `no-optional-fields`).
+export interface CalcFamilyLiveOptionsExternalApi<Inputs extends ReadonlyArray<AnySource>>
   extends FamilyOptions {
   /**
    * Family-wide invalidation key over the SHARED inputs (the member key plays
@@ -107,7 +109,7 @@ export interface CalcFamilyLiveOptions<Inputs extends ReadonlyArray<AnySource>>
 export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>, K, Out>(
   family: CalcFamilyClass<N, Inputs, K, Out>,
   compute: (key: K) => (inputs: InputsObject<Inputs>) => Out,
-  options: CalcFamilyLiveOptions<Inputs> = {},
+  options: CalcFamilyLiveOptionsExternalApi<Inputs> = {},
 ): Layer.Layer<FamilyStore<K, Out>, never, InputStores<Inputs>> =>
   Layer.scoped(
     family.store,
@@ -122,7 +124,9 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
 
       const dropEntry = (key: K): void => {
         const entry = entries.get(key)
-        if (entry !== undefined) entry.unsubscribe()
+        if (entry !== undefined) {
+          entry.unsubscribe()
+        }
         entries.delete(key)
         subscribers.delete(key)
       }
@@ -137,7 +141,9 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
           const args = sources.snapshot()
           const memoKey = sources.keyOf(args)
           const prev = MutableRef.get(memo)
-          if (prev !== undefined && sameKey(memoKey, prev.key)) return prev.output
+          if (prev !== undefined && sameKey(memoKey, prev.key)) {
+            return prev.output
+          }
           const output = body(args)
           MutableRef.set(memo, { key: memoKey, output })
           return output
@@ -151,11 +157,14 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
       const refCounted = (key: K, store: Store<Out>): Store<Out> => ({
         ...store,
         subscribe: (listener) => {
-          subscribers.set(key, (subscribers.get(key) ?? 0) + 1)
+          const priorCount = subscribers.get(key)
+          subscribers.set(key, (priorCount === undefined ? 0 : priorCount) + 1)
           const off = store.subscribe(listener)
           const released = { done: false }
           return () => {
-            if (released.done) return
+            if (released.done) {
+              return
+            }
             released.done = true
             off()
             const remaining = (subscribers.get(key) ?? 1) - 1
@@ -165,7 +174,10 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
             }
             subscribers.delete(key)
             queueMicrotask(() => {
-              if ((subscribers.get(key) ?? 0) === 0) dropEntry(key)
+              const liveCount = subscribers.get(key)
+              if (liveCount === undefined || liveCount === 0) {
+                dropEntry(key)
+              }
             })
           }
         },
@@ -174,7 +186,9 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
       const familyStore: FamilyStore<K, Out> = {
         at: (key) => {
           const existing = entries.get(key)
-          if (existing !== undefined) return existing.store
+          if (existing !== undefined) {
+            return existing.store
+          }
           const member = createMember(key)
           const created = evictWhenUnused
             ? { store: refCounted(key, member.store), unsubscribe: member.unsubscribe }
@@ -184,7 +198,7 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
         },
         forget: dropEntry,
         clear: () => {
-          for (const key of [...entries.keys()]) dropEntry(key)
+          ;[...entries.keys()].forEach((key) => dropEntry(key))
         },
         size: () => entries.size,
       }

package/src/calc/compose.ts

@@ -63,7 +63,7 @@ export function composeCalcs(
   // Fold leaf-first: each upstream is provided into the accumulated downstream,
   // so dependency order is exactly the argument order.
   return upstream.reduce<Layer.Layer<unknown, unknown, unknown>>(
-    (downstream, up) => Layer.provideMerge(downstream, up),
+    (downstream, upstreamLayer) => Layer.provideMerge(downstream, upstreamLayer),
     leaf,
   )
 }

package/src/calc/queryState.ts

@@ -37,16 +37,16 @@ export const empty = (fetching: boolean): QueryState<never, never> => ({
  * non-gated query, which always fetches) and `Idle` only for a switched-off
  * gateable query.
  */
-export const toAsyncData = <A, E>(s: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> =>
-  Option.match(s.error, {
-    onSome: (error) => AsyncData.error(error, s.isFetching),
+export const toAsyncData = <A, E>(state: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> =>
+  Option.match(state.error, {
+    onSome: (error) => AsyncData.error(error, state.isFetching),
     onNone: () =>
-      Option.match(s.data, {
-        onSome: (value) => AsyncData.success(value, s.isFetching),
-        onNone: () => (s.isFetching || !gated ? AsyncData.loading : AsyncData.idle),
+      Option.match(state.data, {
+        onSome: (payload) => AsyncData.success(payload, state.isFetching),
+        onNone: () => (state.isFetching || !gated ? AsyncData.loading : AsyncData.idle),
       }),
   })
 
 /** `Loading` in the React-Query sense: fetching with nothing to show yet. */
-export const isLoading = <A, E>(s: QueryState<A, E>): boolean =>
-  s.isFetching && Option.isNone(s.data)
+export const isLoading = <A, E>(state: QueryState<A, E>): boolean =>
+  state.isFetching && Option.isNone(state.data)