@playfast/reform 0.1.0 → 1.1.1

package/src/calc/asyncCalc.ts

@@ -1,5 +1,6 @@
-import { Context, Effect, Layer, Match, Option, Schema } from 'effect'
-import { type Manifest, yieldableClass } from '../definition/definition'
+import { Context, Effect, Layer, Match, Option } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
+import { type Manifest } from '../definition/definition'
 import { type AnyEvent } from '../event/event'
 import {
   type InputsObject,
@@ -8,36 +9,25 @@ import {
 } from '../internal/sources'
 import {
   bumpRevision,
-  type GatedOf,
-  gatedFlag,
   makeQueryDriver,
   RevisionSchema,
   revisionZero,
 } from '../internal/queryDriver'
 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'
-
-// `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.
+import type { AnySchema, AnyValue } from '../internal/variance'
+export { invalidate, make, type NamedCalc, refetch } from './asyncCalcDefinitions'
 
 export interface AsyncCalcManifest<N extends string, A, E> 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
 }
 
@@ -47,35 +37,24 @@ export interface AsyncCalcClass<
   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 EffectType<AsyncData<A, E, Gated>, never, Store<AsyncData<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 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> {
   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: 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>
-  /** `true` ⇒ the query is always on: no `Idle` arm and `disabled` is rejected on `.live`. */
+  readonly error?: AnySchema<E>
   // 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.
- */
 export type AsyncCalcLive<
   Inputs extends ReadonlyArray<AnySource>,
   A,
@@ -86,34 +65,10 @@ export type AsyncCalcLive<
   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
@@ -125,7 +80,6 @@ export type AsyncCalcLive<
   : // 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,
@@ -137,7 +91,6 @@ export type AsyncCalcLiveWithInvalidateOn<
   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
@@ -155,57 +108,6 @@ export interface AsyncCalcLiveView<Inputs extends ReadonlyArray<AnySource>, A, E
     | { 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 = <
-  const N extends string,
-  const Inputs extends ReadonlyArray<AnySource>,
-  A,
-  E = never,
-  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.
-  const gated = gatedFlag(config.alwaysOn)
-  const manifest: AsyncCalcManifest<N, A, E> = {
-    kind: 'AsyncCalc',
-    name,
-    output: config.output,
-    gated,
-    ...(config.error !== undefined ? { error: config.error } : {}),
-  }
-  const read = Effect.flatMap(store, readTracked)
-  return yieldableClass(read, {
-    manifest,
-    store,
-    name,
-    inputs: config.inputs,
-    gated,
-  })
-}
-
-/**
- * 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>,
@@ -240,33 +142,18 @@ 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<Store<AsyncData<A, E, Gated>>, never, AnyValue> {
   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>
 
-      // `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
@@ -277,12 +164,6 @@ export function live<
           ? 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
-      // 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 +189,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 +196,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,
@@ -330,29 +204,3 @@ 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/asyncCalcDefinitions.ts

@@ -0,0 +1,48 @@
+import { Context, Effect } from 'effect'
+import { yieldableClass } from '../definition/definition'
+import { type GatedOf, gatedFlag } from '../internal/queryDriver'
+import type { Store } from '../internal/store'
+import { readTracked } from '../internal/track'
+import { Queries } from '../runtime/queries'
+import type { AnySource } from '../state/token'
+import type { AsyncData } from './asyncData'
+import type { AsyncCalcClass, AsyncCalcConfig, AsyncCalcManifest } from './asyncCalc'
+
+export const make = <
+  const N extends string,
+  const Inputs extends ReadonlyArray<AnySource>,
+  A,
+  E = never,
+  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}`,
+  )
+  const gated = gatedFlag(config.alwaysOn)
+  const manifest: AsyncCalcManifest<N, A, E> = {
+    kind: 'AsyncCalc',
+    name,
+    output: config.output,
+    gated,
+    ...(config.error !== undefined ? { error: config.error } : {}),
+  }
+  const read = Effect.flatMap(store, readTracked)
+  return yieldableClass(read, { manifest, store, name, inputs: config.inputs, gated })
+}
+
+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()),
+  )
+
+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

@@ -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>> =>

package/src/calc/calc.test.ts

@@ -2,15 +2,11 @@ import { expect, it } from '@effect/vitest'
 import { Duration, Effect, Layer, Schema as S } from 'effect'
 import { Calc, State, StateGroup } from '../index'
 
-// The calc store memoizes on input identity and — the behaviour under test —
-// only wakes its subscribers when a source change actually moves the output.
-
 const tick = Effect.sleep(Duration.millis(1))
 
 it.live('a source change that does not move the output notifies no subscriber', () => {
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
-  // `isPositive` is stable across 1 -> 2 (still true) but flips on 2 -> -1.
   class IsPositive extends Calc.make('IsPositive', {
     inputs: [StateGroup.select(Inputs, 'count')],
     output: S.Boolean,
@@ -33,13 +29,11 @@ it.live('a source change that does not move the output notifies no subscriber',
 
     expect(derived.get()).toBe(true)
 
-    // 1 -> 2: inputs changed, recompute runs, but the output (true) is unchanged.
     source.set(2)
     yield* tick
     expect(notifications.n).toBe(0)
     expect(derived.get()).toBe(true)
 
-    // 2 -> -1: output flips to false — exactly one notification.
     source.set(-1)
     yield* tick
     expect(notifications.n).toBe(1)
@@ -65,7 +59,6 @@ it.live('reading does not recompute while inputs are unchanged (memoized)', () =
   return Effect.gen(function* () {
     const derived = yield* Doubled.store
     const before = runs.n
-    // Repeated reads with no input change hit the memo — no extra compute.
     expect(derived.get()).toBe(10)
     expect(derived.get()).toBe(10)
     expect(runs.n).toBe(before)
@@ -80,7 +73,6 @@ it.live('a calc can depend on another calc as an input source', () => {
     output: S.Number,
   }) {}
   const DoubledLive = Calc.live(Doubled, ({ count }) => count * 2)
-  // `Doubled` (a Calc) is used directly as an input source; its name is the key.
   class PlusDoubled extends Calc.make('PlusDoubled', {
     inputs: [StateGroup.select(Inputs, 'count'), Doubled],
     output: S.Number,
@@ -95,17 +87,14 @@ it.live('a calc can depend on another calc as an input source', () => {
   return Effect.gen(function* () {
     const source = yield* StateGroup.select(Inputs, 'count').store
     const derived = yield* PlusDoubled.store
-    expect(derived.get()).toBe(15) // 5 + (5*2)
+    expect(derived.get()).toBe(15)
     source.set(3)
     yield* tick
-    expect(derived.get()).toBe(9) // 3 + (3*2)
+    expect(derived.get()).toBe(9)
   }).pipe(Effect.provide(TestLayer))
 })
 
 it.live('a diamond dependency resolves in one flush with a single leaf notification', () => {
-  // count ─┬─► A (count+1) ─┐
-  //        └─► B (count+10)─┴─► C (A+B).  A change to `count` moves both A and B;
-  // C must converge to the new value and wake its subscriber exactly once.
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
   class A extends Calc.make('A', {
@@ -133,11 +122,11 @@ it.live('a diamond dependency resolves in one flush with a single leaf notificat
     c.subscribe(() => {
       wakes.n += 1
     })
-    expect(c.get()).toBe(11) // (0+1) + (0+10)
+    expect(c.get()).toBe(11)
 
     source.set(5)
     yield* tick
-    expect(c.get()).toBe(21) // (5+1) + (5+10)
+    expect(c.get()).toBe(21)
     expect(wakes.n).toBe(1)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -168,13 +157,11 @@ it.live('invalidateBy: a calc recomputes only when the projected key moves', ()
     const base = runs.n
     expect(sum.get()).toBe(2)
 
-    // `b` moves but the key (just `a`) is unchanged — no recompute, value retained.
     sb.set(100)
     yield* tick
     expect(runs.n).toBe(base)
     expect(sum.get()).toBe(2)
 
-    // `a` moves — recompute, now seeing the current `b`.
     sa.set(5)
     yield* tick
     expect(sum.get()).toBe(105)
@@ -184,11 +171,6 @@ it.live('invalidateBy: a calc recomputes only when the projected key moves', ()
 it.live('inputs are keyed by the make() name even when the subclass binding differs', () => {
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
-  // The binding name ('Renamed…') deliberately differs from the make() name
-  // ('feed') — a class declaration defines its OWN static `name` from the
-  // binding, shadowing the explicit one. Minifiers rename bindings, so keying
-  // the snapshot off the static would make this input undefined in production
-  // builds; the inputs object must key by the manifest's make() name.
   class RenamedByTheMinifier extends Calc.make('feed', {
     inputs: [StateGroup.select(Inputs, 'count')],
     output: S.Number,
@@ -210,9 +192,7 @@ it.live('inputs are keyed by the make() name even when the subclass binding diff
   )
 
   return Effect.gen(function* () {
-    // The subclass's own static name is the (would-be-minified) binding name…
     expect(RenamedByTheMinifier.name).toBe('RenamedByTheMinifier')
-    // …but the snapshot keys by the make() name, so `feed` is defined.
     const downstream = yield* Downstream.store
     expect(downstream.get()).toBe(7)
     expect(seen.every((v) => v !== undefined)).toBe(true)
@@ -243,7 +223,6 @@ it.live('reuse: an unchanged subtree keeps its identity across recompute', () =>
     const derived = yield* Split.store
     const before = derived.get()
 
-    // Only `b` moves: the root and `right` are fresh, `left` keeps its identity.
     b.set(2)
     yield* tick
     const after = derived.get()
@@ -262,9 +241,6 @@ it.live('reuse: a value-equal recompute keeps the previous reference and wakes n
     inputs: [StateGroup.select(Inputs, 'count')],
     output: Box,
   }) {}
-  // A plain-object output: WITHOUT reuse every recompute is a fresh identity
-  // (and would notify); with it, a value-equal recompute returns the previous
-  // reference and the Equal gate stays silent.
   const IsPositiveLive = Calc.live(IsPositive, ({ count }) => ({ positive: count > 0 }), {
     reuse: true,
   })