@playfast/reform 1.0.1 → 1.1.1

package/README.md

@@ -449,12 +449,24 @@ class Counter extends Feature.make('counter', {
 // lazy: defer the module behind an import
 class Reports extends Feature.make('reports', {
   loadingStrategy: 'lazy',
+  composition: ReportsComp,
   load: lazyImport(() => import('./reports.module')),
+  eager: featureModule([], PlaceholderLive),
   placeholder: { loading: SpinnerComp, failed: RetryComp },
 }) {}
 ```
 
-A feature shares the app's engine but gets its own scope — `mountFeature(binding, engineContext)` loads it, builds its layer, dispatches its boot events, and disposes everything when the scope closes. Fill a slot with one via `provide(SomeSlot, Reports)`; the host paints the placeholders while it loads.
+A feature's `requires` tuple accepts shared State/Calc carriers, StateGroups, and
+ordinary Effect `Context.Tag`s. A lazy feature shares the app's engine but gets
+its own scope — `mountFeature(binding, parentContext)` loads it, builds its layer
+against the immediate parent, dispatches its boot events, and disposes everything
+when the scope closes. Fill a slot with one via `provide(SomeSlot, Reports)`;
+`provide` merges its optional eager placeholder module automatically while the
+host paints the placeholders and loads the main module.
+
+Default Features retain their binding identity too. Their module is merged by
+`provide`, their composition renders synchronously from the parent runtime, and
+their boot events run once for each keyed activation.
 
 ---
 
@@ -465,6 +477,7 @@ A scene bundles a root composition with the closed wiring that runs it — the s
 
 ```ts
 scene(composition, { provide: [...layers], boot?: [...events] })   // → Scene
+featureScene(eagerFeature, { provide: closedEnvironment })         // → Scene
 seedScene(base, seeds)                                             // tooling: override seed values
 isScene(value)                                                     // reflection guard
 
@@ -476,6 +489,10 @@ 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/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).
 
+`featureScene` is the typed root helper for a default/eager Feature. Its `provide`
+layer closes the engine plus the Feature's declared requirements; lazy Features
+are rejected because an application root must be immediately available.
+
 ---
 
 <a name="engine"></a>

package/package.json

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

@@ -2,12 +2,6 @@ import { expect, it } from '@effect/vitest'
 import { Data, Duration, Effect, Layer, Schema as S } from 'effect'
 import { AsyncCalc, Boundary, Calc, Engine, Event, State, StateGroup } from '../index'
 
-// Boundary merges several async lifecycles into one Pending/Errored/Ready value
-// — the Suspense-boundary analog, value-level. The behaviours under test: the
-// arm mapping (Loading pends, Idle and SWR-refetching count Ready, Error
-// surfaces), the chained-gate settle-gap pin, the `once` latch, and the
-// notification economy (arm-stable churn wakes nobody).
-
 const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
 
 const until = <A>(read: () => A, pred: (a: A) => boolean, rounds = 200): Effect.Effect<A> =>
@@ -51,13 +45,10 @@ it.live('pending while ANY covered query is on its first load; one Ready when al
     })
     expect(store.get()._tag).toBe('Pending')
 
-    // The fast query settles first — still Pending (the slow one holds it).
     yield* tick(20)
     expect(store.get()._tag).toBe('Pending')
 
     yield* until(() => store.get()._tag, (t) => t === 'Ready')
-    // Exactly ONE notification fired across the whole boot: Pending→Pending
-    // churn (Fast settling) was absorbed by the stable arm reference.
     expect(observed).toEqual(['Ready'])
   }).pipe(Effect.provide(TestLayer))
 })
@@ -86,8 +77,6 @@ it.live('a gated query that is OFF counts Ready — the off arm must not hold th
   )
   return Effect.gen(function* () {
     const store = yield* Gate.store
-    // The gated query is Idle (deliberately off): only the always-on first
-    // load pends, and Ready arrives without ever waiting on the Idle arm.
     yield* until(() => store.get()._tag, (t) => t === 'Ready')
     expect(store.get()._tag).toBe('Ready')
   }).pipe(Effect.provide(TestLayer))
@@ -116,7 +105,6 @@ it.live('an SWR refetch never re-pends — Success with refetching: true is Read
     const store = yield* Gate.store
     yield* until(() => store.get()._tag, (t) => t === 'Ready')
 
-    // Move the input: the query goes Success+refetching (SWR) — Ready holds.
     seed.set(2)
     yield* until(() => qStore.get(), (q) => q._tag === 'Success' && q.refetching)
     expect(store.get()._tag).toBe('Ready')
@@ -157,7 +145,6 @@ it.live('a first-load failure surfaces as Errored with the failure, and a retry
       expect(failure instanceof Boom && failure.message).toBe('server down')
     }
 
-    // The retry path: the server heals, a listed fact refetches, Ready lands.
     healthy.now = true
     yield* Event.dispatch(Poke, {})
     yield* until(() => store.get()._tag, (t) => t === 'Ready')
@@ -166,12 +153,6 @@ it.live('a first-load failure surfaces as Errored with the failure, and a retry
 })
 
 it.live('settle-gap pin: a chained gate never leaks Ready between hops', () => {
-  // B enables only when A has succeeded — the app's Session → Bootstrap shape.
-  // The dangerous instant: A flips Success while B is still Idle (Idle counts
-  // Ready), so a naive merge could notify Ready before B's driver flips it to
-  // Loading. Layer dependency order (B's driver subscribes to A's store before
-  // the boundary does) plus the one-microtask fixpoint flush close the gap;
-  // this records every notification to prove no intermediate Ready escapes.
   class Seed extends State.make('seed', S.Number) {}
   class Inputs extends StateGroup.make(Seed) {}
   class A extends AsyncCalc.make('A', {
@@ -205,19 +186,12 @@ it.live('settle-gap pin: a chained gate never leaks Ready between hops', () => {
     expect(store.get()._tag).toBe('Pending')
 
     yield* until(() => store.get()._tag, (t) => t === 'Ready')
-    yield* tick(30) // let any straggler notification land before judging
-    // ONE Ready, at the end — never a Ready while B's hop was still pending.
+    yield* tick(30)
     expect(observed).toEqual(['Ready'])
   }).pipe(Effect.provide(TestLayer))
 })
 
 it.live('once + a Calc hop in the chain: the latch never freezes a mid-flush Ready', () => {
-  // The app's boot shape: AsyncCalc A → plain Calc projecting it → AsyncCalc B
-  // gated on the projection. Propagation crosses TWO scheduler-flush rounds,
-  // so when A settles there is a mid-flush frame where B has not yet flipped
-  // to Loading — a recompute-time latch would freeze that intermediate Ready
-  // and the boundary would abandon B's whole first load (caught live by the
-  // boot-frames walk: nav in, boards card still spinning).
   class Seed extends State.make('seed', S.Number) {}
   class Inputs extends StateGroup.make(Seed) {}
   class A extends AsyncCalc.make('A', {
@@ -247,8 +221,6 @@ it.live('once + a Calc hop in the chain: the latch never freezes a mid-flush Rea
   return Effect.gen(function* () {
     const bStore = yield* B.store
     const store = yield* Gate.store
-    // While B's first load is in flight the boundary MUST still be Pending —
-    // a poisoned latch would already report Ready here.
     yield* until(() => bStore.get()._tag, (t) => t === 'Loading')
     expect(store.get()._tag).toBe('Pending')
     yield* until(() => bStore.get()._tag, (t) => t === 'Success')
@@ -258,9 +230,6 @@ it.live('once + a Calc hop in the chain: the latch never freezes a mid-flush Rea
 })
 
 it.live('once: a covered gate enabling AFTER the latch never re-pends the boundary', () => {
-  // The boot-boundary semantics: a route-gated query (the board) first loads
-  // on a later navigation — its own screen owns that loading state, the shell
-  // splash must not come back.
   class Route extends State.make('routeFlag', S.Boolean) {}
   class Inputs extends StateGroup.make(Route) {}
   class Always extends AsyncCalc.make('Always', {
@@ -291,7 +260,6 @@ it.live('once: a covered gate enabling AFTER the latch never re-pends the bounda
     const store = yield* Gate.store
     yield* until(() => store.get()._tag, (t) => t === 'Ready')
 
-    // "Navigate": the routed query enables and goes Loading — latched Ready holds.
     route.set(true)
     yield* until(() => routedStore.get()._tag, (t) => t === 'Loading')
     expect(store.get()._tag).toBe('Ready')

package/src/boundary/boundary.ts

@@ -1,78 +1,34 @@
 import { Context, Data, Effect, Layer, MutableRef, Predicate } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import { resolveScheduler } from '../internal/scheduler'
 import { type InputStores, sameKey, wireSources } from '../internal/sources'
 import { makeDerivedStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 import { type Source } from '../state/token'
+import type { AnyValue } from '../internal/variance'
 
-// Boundary: the Suspense-boundary analog, value-level. One derived store that
-// merges the lifecycles of several async sources into a single
-// Pending/Errored/Ready value, so ONE surface (a splash, a skeleton) covers a
-// whole subtree's first load instead of every query consumer painting its own.
-//
-// Reform can do this without React's throw-a-promise machinery because
-// fetching is layer-driven, not render-driven: an `AsyncCalc` runs because its
-// layer is built, never because something rendered. A boundary therefore only
-// *aggregates* lifecycles — it cannot create render-waterfalls, and content it
-// reveals already has its data.
-//
-// The arm mapping IS the semantics, and most of it falls out of `AsyncData`:
-//   Loading            → Pending  (the arm only exists before the first value,
-//                                  so a boundary is first-load-only by construction)
-//   Success            → Ready    (even `refetching: true` — SWR refetches never
-//                                  re-show the fallback; no transition machinery)
-//   Idle               → Ready    (a gated query that is off is DELIBERATELY off —
-//                                  a signed-out viewer must not wait on a query
-//                                  that only runs signed-in)
-//   Error              → Errored  (the error-boundary half, also value-level)
-//
-// Chained gates (B enables when A succeeds) cannot leak a Ready between hops:
-// the boundary's layer requires every covered store, so each driver subscribes
-// upstream BEFORE the boundary does, the scheduler flush runs listeners in
-// subscription order to a fixpoint within one microtask, and reads are
-// pull-fresh — by the time any subscriber reads, the next hop is already
-// Loading. `boundary.test.ts` pins this with a recorded-notification proof.
-
-/** Some covered source is still on its FIRST load — show the fallback. */
 export interface BoundaryPending {
   readonly _tag: 'Pending'
 }
 
-/** Some covered source failed before its first value. */
 export interface BoundaryErrored {
   readonly _tag: 'Errored'
-  /** The failures, in `over` order (heterogeneous — display via `String`). */
   readonly errors: ReadonlyArray<unknown>
 }
 
-/** Every covered source has settled (or is deliberately gated off). */
 export interface BoundaryReady {
   readonly _tag: 'Ready'
 }
 
 export type BoundaryState = BoundaryPending | BoundaryErrored | BoundaryReady
 
-// Stable arm references: repeated recomputes return the same object, so the
-// derived store's Equal gate (and `useSyncExternalStore`'s stable-snapshot
-// contract) hold without a wrapper. `Errored` carries data, so it is a `Data`
-// struct — value-equal failures coalesce the same way.
 const pendingArm: BoundaryState = { _tag: 'Pending' }
 const readyArm: BoundaryState = { _tag: 'Ready' }
 const erroredArm = (errors: ReadonlyArray<unknown>): BoundaryState =>
   Data.struct({ _tag: 'Errored' as const, errors: Data.array(errors) })
 
-/**
- * Anything a boundary can cover: a `Source` whose value is an async lifecycle —
- * an `AsyncCalc`, or anything lifecycle-valued built over one (e.g. a
- * `RemoteState` overlay). The constraint is the same erased `Source` every calc
- * input uses (store invariance rules out a fixed lifecycle value type — each
- * definition's union carries its own `Gated`/`E` arms); the captured `const`
- * tuple keeps each member's precise store requirement, and the runtime merge
- * reads arms through structural guards, so a non-lifecycle source simply
- * counts as settled.
- */
-export type AnyLifecycleSource = Source<string, any>
+export type AnyLifecycleSource = Source<string, AnyValue>
 
 export interface BoundaryManifest<N extends string> extends Manifest {
   readonly kind: 'Boundary'
@@ -80,13 +36,11 @@ export interface BoundaryManifest<N extends string> extends Manifest {
 }
 
 export interface BoundaryClass<out N extends string, out Over extends ReadonlyArray<AnyLifecycleSource>>
-  extends Effect.Effect<BoundaryState, never, Store<BoundaryState>> {
+  extends EffectType<BoundaryState, never, Store<BoundaryState>> {
   new (): {}
   readonly manifest: BoundaryManifest<N>
   readonly store: Context.Tag<Store<BoundaryState>, Store<BoundaryState>>
-  /** The boundary's name, so it doubles as a `Source` input to a calc. */
   readonly name: N
-  /** The covered lifecycle sources — read by `live` and the editor's graph. */
   readonly over: Over
 }
 
@@ -95,23 +49,10 @@ export interface BoundaryConfig<Over extends ReadonlyArray<AnyLifecycleSource>>
 }
 
 export interface BoundaryOptions {
-  /**
-   * Latch: once Ready, stay Ready. A BOOT boundary wants this — a covered
-   * route-gated query that first enables on a later navigation (Idle →
-   * Loading) must not re-splash the whole shell; its own screen owns that
-   * 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
 }
 
-/**
- * Define a boundary over async sources. `yield* MyBoundary` reads the merged
- * `Pending | Errored | Ready` lifecycle; the consuming view renders ONE
- * fallback on Pending and its content slot on Ready — content reveals
- * together, with data already present (fetching never waited on rendering).
- */
 export const make = <const N extends string, const Over extends ReadonlyArray<AnyLifecycleSource>>(
   name: N,
   config: BoundaryConfig<Over>,
@@ -124,25 +65,15 @@ export const make = <const N extends string, const Over extends ReadonlyArray<An
   return yieldableClass(read, { manifest, store, name, over: config.over })
 }
 
-// The snapshot values arrive through `wireSources`' erased key projection
-// (`ReadonlyArray<unknown>`), so read the two facts the merge needs through
-// honest structural guards — no cast back to `AnyAsyncData`.
 const tagOf = (arm: unknown): string =>
   Predicate.hasProperty(arm, '_tag') && Predicate.isString(arm._tag) ? arm._tag : ''
 const errorOf = (arm: unknown): ReadonlyArray<unknown> =>
   Predicate.hasProperty(arm, 'error') && tagOf(arm) === 'Error' ? [arm.error] : []
 
-/**
- * Wire the merge. A derived store over the covered stores (sensed through the
- * same `wireSources` plumbing every calc uses): recomputes are memoized on the
- * input snapshots and the arms are stable references, so input churn that does
- * not move the merged arm wakes nobody.
- */
 export const live = <N extends string, Over extends ReadonlyArray<AnyLifecycleSource>>(
   boundary: BoundaryClass<N, Over>,
   options: BoundaryOptions = {},
 ): Layer.Layer<Store<BoundaryState>, never, InputStores<Over>> =>
-  // Scoped so the source subscriptions are released with the layer's scope.
   Layer.scoped(
     boundary.store,
     Effect.gen(function* () {
@@ -177,15 +108,6 @@ export const live = <N extends string, Over extends ReadonlyArray<AnyLifecycleSo
       yield* Effect.addFinalizer(() => Effect.sync(derived.unsubscribe))
 
       if (options.once === true) {
-        // Latch on CONVERGED values only — at build and on (coalesced,
-        // post-fixpoint) notifications — never inside `recompute`. A chained
-        // gate with a plain Calc hop between the async stores (bootstrap →
-        // current-workspace → boards) propagates over TWO flush rounds, so a
-        // mid-flush recompute can observe the frame where the downstream
-        // driver has not yet flipped its query to Loading. That intermediate
-        // 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)
         }

package/src/calc/asyncCalc.invalidate.test.ts

@@ -2,17 +2,11 @@ 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, {
@@ -49,13 +43,11 @@ it.live('invalidate marks stale without fetching; a fresh subscriber then refetc
     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)
@@ -86,12 +78,11 @@ it.live('invalidate with an active reader auto-refetches immediately, keeping th
 
   return Effect.gen(function* () {
     const store = yield* Q.store
-    store.subscribe(() => {}) // active reader
+    store.subscribe(() => {})
     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 })
@@ -127,7 +118,6 @@ it.live('refetch forces a run regardless of staleness', () => {
     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)
@@ -137,7 +127,7 @@ it.live('refetch forces a run regardless of staleness', () => {
 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
+  const store = fakeQueryStore({ P: 99 })
   class Q extends AsyncCalc.make('Q', {
     inputs: [StateGroup.select(Inputs, 'count')],
     output: S.Number,
@@ -155,10 +145,8 @@ it.live('persist: hydrates from the QueryStore (stale) then writes the settled v
 
   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)

package/src/calc/asyncCalc.test.ts

@@ -2,14 +2,8 @@ import { expect, it } from '@effect/vitest'
 import { Data, Duration, Effect, Layer, Schema as S } from 'effect'
 import { AsyncCalc, Engine, Event, State, StateGroup } from '../index'
 
-// AsyncCalc is a derived store whose value is the lifecycle of an Effect. It runs
-// the query reactively from its inputs (latest-wins), keeps the last value while
-// re-fetching (stale-while-revalidate), and goes Idle when a gated query disables.
-
 const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
 
-// Poll until the predicate holds (bounded) — for assertions that race real
-// timers under parallel-suite host load, where a fixed `tick` budget flakes.
 const until = <A>(read: () => A, pred: (a: A) => boolean, rounds = 200): Effect.Effect<A> =>
   Effect.suspend(() => {
     const a = read()
@@ -35,7 +29,6 @@ it.live('runs the query and resolves Loading -> Success', () => {
 
   return Effect.gen(function* () {
     const store = yield* Doubled.store
-    // Before the forked query resolves, the value is Loading.
     expect(store.get()._tag).toBe('Loading')
     yield* tick(40)
     const value = store.get()
@@ -92,7 +85,6 @@ it.live('a dependency change re-fetches, keeping the last value with refetching:
     yield* tick(40)
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
 
-    // Move the input: the prior value is kept while the new fetch is in flight.
     source.set(7)
     yield* tick(5)
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: true })
@@ -126,9 +118,6 @@ it.live('latest-wins: a rapid second change cancels the in-flight run', () => {
     yield* tick(40)
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 2 })
 
-    // Two changes in quick succession: the first run is switched out before it
-    // can write, so only the latest value lands (poll — fixed sleeps flake when
-    // a loaded host starves the 25ms query timer).
     source.set(3)
     yield* tick(5)
     source.set(4)
@@ -181,7 +170,6 @@ it.live('invalidateBy: an input change outside the key does not re-fetch', () =>
         runs.n += 1
         return page
       }),
-    // Only `page` is part of the key; `status` churn must not re-fetch.
     invalidateBy: ({ page }) => [page],
   })
   const TestLayer = QLive.pipe(
@@ -195,12 +183,10 @@ it.live('invalidateBy: an input change outside the key does not re-fetch', () =>
     yield* tick()
     expect(runs.n).toBe(1)
 
-    // status moves, key unchanged -> no re-fetch.
     status.set('b')
     yield* tick()
     expect(runs.n).toBe(1)
 
-    // page moves, key changes -> one re-fetch.
     page.set(2)
     yield* tick()
     expect(runs.n).toBe(2)
@@ -218,7 +204,6 @@ it.live('reuse: a refetch returning mostly-equal data keeps unchanged element id
     alwaysOn: true,
   }) {}
   const RowsLive = AsyncCalc.live(Rows, {
-    // Fresh objects every run — only the row matching `page` differs.
     query: ({ page }) =>
       Effect.succeed([
         { id: 1, name: 'one' },
@@ -240,7 +225,6 @@ it.live('reuse: a refetch returning mostly-equal data keeps unchanged element id
       (v) => v._tag === 'Success' && v.refetching === false && v.value !== first.value,
     )
     if (second._tag !== 'Success') return
-    // Row 1 didn't move: same identity. Row 2 did: fresh.
     expect(second.value[0]).toBe(first.value[0])
     expect(second.value[1]).not.toBe(first.value[1])
     expect(second.value[1]).toEqual({ id: 2, name: 'two@2' })
@@ -250,8 +234,6 @@ it.live('reuse: a refetch returning mostly-equal data keeps unchanged element id
 it.live('coalesce trailing: a burst during one flight completes it and runs ONE trailing refetch', () => {
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
-  // Completion log: the sync body runs AFTER the delay, so the order proves
-  // which runs actually finished (and that the in-flight one was not cancelled).
   const completed: number[] = []
   class Doubled extends AsyncCalc.make('Doubled', {
     inputs: [StateGroup.select(Inputs, 'count')],
@@ -274,9 +256,6 @@ it.live('coalesce trailing: a burst during one flight completes it and runs ONE
     yield* until(() => store.get(), (v) => v._tag === 'Success')
     expect(completed).toEqual([1])
 
-    // Three key changes during the first change's flight: the in-flight run (2)
-    // completes and lands, the middle change (3) is conflated away, and exactly
-    // one trailing run fetches the latest key (4).
     source.set(2)
     yield* tick(5)
     source.set(3)
@@ -310,8 +289,6 @@ it.live('coalesce trailing: the stale settle re-flags refetching until the trail
     const store = yield* Doubled.store
     yield* until(() => store.get(), (v) => v._tag === 'Success')
 
-    // Two changes: when the in-flight result (4) lands, a trailing run is still
-    // pending — the value must read as syncing, not settled.
     source.set(2)
     yield* tick(5)
     source.set(3)
@@ -353,8 +330,6 @@ it.live('coalesce trailing: a disable while a request waits in the slot skips th
     const store = yield* Q.store
     yield* until(() => store.get(), (v) => v._tag === 'Success')
 
-    // 2 starts a flight, 3 waits in the slot, then the gate closes: the flight's
-    // stale result must not land (Idle), and the queued request must not run.
     source.set(2)
     yield* tick(5)
     source.set(3)
@@ -364,7 +339,6 @@ it.live('coalesce trailing: a disable while a request waits in the slot skips th
     expect(store.get()._tag).toBe('Idle')
     expect(completed).toEqual([1, 2])
 
-    // Re-enabling re-runs (the driver forgot its key when switched off).
     source.set(5)
     const settled = yield* until(() => store.get(), (v) => v._tag === 'Success')
     expect(settled).toMatchObject({ _tag: 'Success', value: 10 })
@@ -372,9 +346,6 @@ it.live('coalesce trailing: a disable while a request waits in the slot skips th
   }).pipe(Effect.provide(TestLayer))
 })
 
-// `invalidateOn` is sugar for a hidden revision state + reducer appended to the
-// key — these proofs need the Engine (the Reducers registry + bus + drain loop).
-
 it.live('invalidateOn: dispatching a listed event re-fetches with refetching: true', () => {
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
@@ -404,8 +375,6 @@ it.live('invalidateOn: dispatching a listed event re-fetches with refetching: tr
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 4, refetching: false })
     expect(runs.n).toBe(1)
 
-    // The fact lands: the hidden revision bumps, the key moves, the value is
-    // kept while the re-fetch is in flight (SWR), then settles.
     yield* Event.dispatch(Poke, {})
     yield* tick(5)
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 4, refetching: true })
@@ -445,13 +414,10 @@ it.live('invalidateOn: composes with invalidateBy — non-key churn stays inert,
     yield* tick()
     expect(runs.n).toBe(1)
 
-    // Outside the user key: still no re-fetch (the hidden revision rides along
-    // WITHOUT widening the key to every input).
     status.set('b')
     yield* tick()
     expect(runs.n).toBe(1)
 
-    // The listed event always re-fetches.
     yield* Event.dispatch(Poke, {})
     yield* tick()
     expect(runs.n).toBe(2)
@@ -487,8 +453,6 @@ it.live('invalidateOn: a listed event while disabled stays Idle, and enabling re
     yield* tick()
     expect(store.get()._tag).toBe('Idle')
 
-    // A bump while gated off runs nothing — the driver shows Idle and forgets
-    // its key, so the eventual enable always re-runs.
     yield* Event.dispatch(Poke, {})
     yield* tick()
     expect(store.get()._tag).toBe('Idle')
@@ -543,8 +507,6 @@ it.live('invalidateOn: two async calcs keep independent hidden revisions', () =>
     yield* tick()
     expect(runs).toEqual({ a: 1, b: 1 })
 
-    // Each calc's hidden revision is namespaced by its own name: A's fact moves
-    // only A.
     yield* Event.dispatch(PokeA, {})
     yield* tick()
     expect(runs).toEqual({ a: 2, b: 1 })