@playfast/reform 0.0.9 → 0.0.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform",
   "playbook": "./playbook",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "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.invalidate.test.ts

@@ -0,0 +1,166 @@
+import { expect, it } from '@effect/vitest'
+import { Duration, Effect, Layer, Option, Schema as S } from 'effect'
+import { AsyncCalc, Engine, Queries, QueryStore, State, StateGroup } from '../index'
+
+// The data-oriented half of AsyncCalc: `invalidate` flips `isStale` only (no
+// fetch), `refetch` forces a run, a stale query with active readers (or a fresh
+// subscriber) refetches, and `persist` hydrates + writes through an optional
+// QueryStore. `isStale` is read off the `Queries` registry handle.
+
+const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
+
+const isStale = (name: string) =>
+  Effect.map(Queries, (q) => q.byName.get(name)?.snapshot().isStale ?? false)
+
+// An in-memory QueryStore, so persistence is exercised with no DOM.
+const fakeQueryStore = (seed: Record<string, unknown> = {}) => {
+  const map = new Map<string, unknown>(Object.entries(seed))
+  const layer = Layer.succeed(QueryStore, {
+    get: (key) => Effect.sync(() => Option.fromNullable(map.has(key) ? map.get(key) : undefined)),
+    set: (key, value) => Effect.sync(() => void map.set(key, value)),
+    remove: (key) => Effect.sync(() => void map.delete(key)),
+  })
+  return { map, layer }
+}
+
+it.live('invalidate marks stale without fetching; a fresh subscriber then refetches', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return count
+      }),
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Q.store
+    yield* tick()
+    expect(runs.n).toBe(1)
+
+    // No active readers: invalidate flips the flag but fetches nothing.
+    yield* AsyncCalc.invalidate(Q)
+    yield* tick()
+    expect(yield* isStale('Q')).toBe(true)
+    expect(runs.n).toBe(1)
+
+    // A reader arriving over a stale query (the resubscribe/mount analog) refetches.
+    store.subscribe(() => {})
+    yield* tick()
+    expect(runs.n).toBe(2)
+    expect(yield* isStale('Q')).toBe(false)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('invalidate with an active reader auto-refetches immediately, keeping the value', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return count
+      }).pipe(Effect.delay(Duration.millis(20))),
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 7 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Q.store
+    store.subscribe(() => {}) // active reader
+    yield* tick(40)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
+    expect(runs.n).toBe(1)
+
+    // Stale + active ⇒ refetch now; the last value stays visible (SWR).
+    yield* AsyncCalc.invalidate(Q)
+    yield* tick(5)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: true })
+    yield* tick(40)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
+    expect(runs.n).toBe(2)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('refetch forces a run regardless of staleness', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return count
+      }),
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 3 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    yield* tick()
+    expect(runs.n).toBe(1)
+    expect(yield* isStale('Q')).toBe(false)
+
+    // Not stale, no key movement — refetch still runs.
+    yield* AsyncCalc.refetch(Q)
+    yield* tick()
+    expect(runs.n).toBe(2)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('persist: hydrates from the QueryStore (stale) then writes the settled value through', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  const store = fakeQueryStore({ P: 99 }) // a previously-persisted value
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) => Effect.succeed(count * 2).pipe(Effect.delay(Duration.millis(25))),
+    persist: { key: 'P' },
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 5 })),
+    Layer.provideMerge(store.layer),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const view = yield* Q.store
+    // The persisted value shows instantly, marked refetching (stale-while-revalidate).
+    expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
+
+    // The fresh fetch lands and is written through to the store.
+    yield* tick(45)
+    expect(view.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
+    expect(store.map.get('P')).toBe(10)
+  }).pipe(Effect.provide(TestLayer))
+})

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 {
@@ -18,6 +18,7 @@ import { type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 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 AsyncData, narrowStore } from './asyncData'
@@ -34,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
@@ -62,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
 }
 
@@ -80,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
@@ -88,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
@@ -96,10 +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 — 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
-  ? { 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
@@ -185,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.
@@ -208,13 +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
-      }
+      // 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 — 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 =
+        persistOption === undefined || persistOption === false
+          ? undefined
+          : { 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
@@ -222,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',
@@ -236,13 +304,8 @@ export function live<
         disabled: cfg.disabled,
         coalesce: cfg.coalesce,
         reuse: cfg.reuse,
-        extraKey:
-          revision === undefined
-            ? undefined
-            : {
-                read: () => revision.getSnapshot(),
-                subscribe: (listener) => revision.subscribe(listener),
-              },
+        persist,
+        extraKey,
       })
 
       // The internal store is the full union; narrow to the definition's arms.
@@ -250,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
@@ -265,3 +330,29 @@ export function live<
     Layer.provide(State.live(revisionState, revisionZero)),
   )
 }
+
+/**
+ * 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
+}
+
+export const invalidate = (calc: NamedCalc): Effect.Effect<void, never, Queries> =>
+  Effect.flatMap(Queries, (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()),
+  )

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,
   )
 }