@playfast/reform 0.0.7 → 0.0.8

package/src/remote/remoteState.test.ts

@@ -0,0 +1,695 @@
+import { expect, it } from '@effect/vitest'
+import { Duration, Effect, Layer, Match, Schema as S } from 'effect'
+import {
+  Channels,
+  Engine,
+  Event,
+  Procedures,
+  Reducer,
+  Reducers,
+  RemoteState,
+  State,
+  StateGroup,
+} from '../index'
+
+// RemoteState is server-owned state with optimistic mutations as one primitive:
+// visible = pending.reduce(apply, serverTruth). Dispatching an intent event is
+// the only write surface; a settled or failed intent leaves the queue and the
+// derivation converges. The headline guarantee is the GENERATION RULE: an
+// intent acked at query-run generation g settles only on a Success run with a
+// later generation — the optimistic change never flickers out mid-convergence.
+
+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()
+    return pred(a) || rounds <= 0
+      ? Effect.succeed(a)
+      : Effect.flatMap(tick(10), () => until(read, pred, rounds - 1))
+  })
+
+// ── Shared fixture: a tiny mutable item server. ─────────────────────────────
+
+const Item = S.Struct({ id: S.String, name: S.String })
+type Item = typeof Item.Type
+
+class Added extends Event.make('Added', S.Struct({ id: S.String, name: S.String })) {}
+class Renamed extends Event.make('Renamed', S.Struct({ id: S.String, name: S.String })) {}
+type Intent = Event.EventType<typeof Added> | Event.EventType<typeof Renamed>
+
+// The per-intent fold — idempotent against truth that already carries the
+// intent (an add whose id landed is skipped; a rename converges naturally).
+const applyIntent = (items: ReadonlyArray<Item>, intent: Intent): ReadonlyArray<Item> =>
+  Match.value(intent).pipe(
+    Match.tag('Added', ({ id, name }) =>
+      items.some((item) => item.id === id) ? items : [...items, { id, name }],
+    ),
+    Match.tag('Renamed', ({ id, name }) =>
+      items.map((item) => (item.id === id ? { ...item, name } : item)),
+    ),
+    Match.exhaustive,
+  )
+
+// A server double whose query SNAPSHOTS state at request arrival (like a real
+// DB read) and whose send applies the mutation right before acking.
+const makeServer = (initial: ReadonlyArray<Item>) => {
+  const state = { items: initial, fetches: 0 }
+  return {
+    state,
+    fetch: (delayMs: number) =>
+      Effect.suspend(() => {
+        state.fetches += 1
+        const snapshot = state.items
+        return Effect.as(tick(delayMs), snapshot)
+      }),
+    receive: (intent: Intent, delayMs: number) =>
+      Effect.flatMap(tick(delayMs), () =>
+        Effect.sync(() => {
+          state.items = applyIntent(state.items, intent)
+        }),
+      ),
+  }
+}
+
+it.live('an intent overlays instantly — no fetch fired, truth untouched', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => server.fetch(5),
+    // Slow send: the pure-optimistic window stays open for the assertions.
+    send: (intent) => server.receive(intent, 80),
+    apply: applyIntent,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const truth = yield* Items.truth.store
+    const queue = yield* Items.pending.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+    expect(server.state.fetches).toBe(1)
+
+    // Dispatch the intent: the overlay shows it before the RPC or any refetch.
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+    const optimistic = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.value.length === 2,
+    )
+    if (optimistic._tag === 'Success') {
+      expect(optimistic.value[1]).toEqual({ id: 'b', name: 'beta' })
+    }
+    expect(queue.get()).toMatchObject([{ status: 'sending' }])
+    // Nothing remote happened yet: one fetch ever, truth still one row.
+    expect(server.state.fetches).toBe(1)
+    expect(truth.get()).toMatchObject({ _tag: 'Success' })
+    const t = truth.get()
+    if (t._tag === 'Success') expect(t.value).toHaveLength(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('convergence: the send acks, the refetch lands, the queue drains — and no frame ever lacked the row', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => server.fetch(15),
+    send: (intent) => server.receive(intent, 15),
+    apply: applyIntent,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const queue = yield* Items.pending.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+
+    // FLICKER GUARD: log every Success frame from dispatch to convergence; the
+    // row must be present in all of them (the old settle-on-ack idiom fails
+    // this — the row vanished between the RPC response and the refetch landing).
+    const frames: Array<number> = []
+    const off = store.subscribe(() => {
+      const v = store.get()
+      if (v._tag === 'Success') frames.push(v.value.length)
+    })
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+    // Dispatch routes through the bus: wait for the entry to LAND before
+    // waiting for it to leave (an empty read here would be vacuous).
+    yield* until(() => queue.get(), (q) => q.length === 1)
+    yield* until(() => queue.get(), (q) => q.length === 0)
+    off()
+    expect(frames.length).toBeGreaterThan(0)
+    expect(frames.every((n) => n === 2)).toBe(true)
+
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+    if (settled._tag === 'Success') {
+      expect(settled.value).toEqual([
+        { id: 'a', name: 'alpha' },
+        { id: 'b', name: 'beta' },
+      ])
+    }
+    expect(server.state.fetches).toBe(2)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('THE GENERATION RULE: a refetch that started before the ack can never settle the intent', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  class Poke extends Event.make('Poke', S.Struct({})) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    // Slow query: its snapshot is taken at request arrival, so a run started
+    // before the send acks carries truth WITHOUT the mutation.
+    query: () => server.fetch(60),
+    send: (intent) => server.receive(intent, 15),
+    apply: applyIntent,
+    invalidateOn: [Poke],
+    // Trailing: the pre-ack run completes and LANDS (switch would cancel it),
+    // which is exactly the stale-Success the rule must refuse to settle on.
+    coalesce: 'trailing',
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const queue = yield* Items.pending.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+    expect(server.state.fetches).toBe(1)
+
+    const frames: Array<number> = []
+    const off = store.subscribe(() => {
+      const v = store.get()
+      if (v._tag === 'Success') frames.push(v.value.length)
+    })
+
+    // A refetch starts (generation 2, snapshot WITHOUT the row)…
+    yield* Event.dispatch(Poke, {})
+    yield* tick(5)
+    // …and the intent is dispatched + acked while it is still in flight. The
+    // ack registers a waiter for generation 3 and queues the trailing refetch.
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+
+    // The stale run (gen 2) lands its Success. The rule: it settles NOBODY —
+    // the entry stays pending and the overlay keeps the row over stale truth.
+    yield* until(() => server.state.fetches, (n) => n === 2)
+    yield* tick(25)
+    expect(queue.get()).toHaveLength(1)
+    expect(queue.get()[0]).toMatchObject({ status: 'confirmed' })
+    const midflight = store.get()
+    expect(midflight).toMatchObject({ _tag: 'Success' })
+    if (midflight._tag === 'Success') expect(midflight.value).toHaveLength(2)
+
+    // The post-ack run (gen 3) lands with the mutation: NOW the entry settles.
+    yield* until(() => queue.get(), (q) => q.length === 0)
+    off()
+    expect(server.state.fetches).toBe(3)
+    // The frames before the intent legitimately show one row (the Poke refetch
+    // flips `refetching` and notifies). The flicker property is: once the
+    // optimistic row APPEARS, no later frame may lack it.
+    const firstOptimistic = frames.indexOf(2)
+    expect(firstOptimistic).toBeGreaterThanOrEqual(0)
+    expect(frames.slice(firstOptimistic).every((n) => n === 2)).toBe(true)
+    const settled = store.get()
+    if (settled._tag === 'Success') {
+      expect(settled.value).toEqual([
+        { id: 'a', name: 'alpha' },
+        { id: 'b', name: 'beta' },
+      ])
+    }
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a failed send settles the intent, reverts the overlay, and Failed reaches a user reducer', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  class FailLog extends State.make('failLog', S.Array(S.String)) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => server.fetch(5),
+    send: () => Effect.fail('rejected' as const).pipe(Effect.delay(Duration.millis(15))),
+    apply: applyIntent,
+  })
+  // The toast/retry seam: an ordinary reducer on the public Failed event.
+  const LogReducer = Reducer.make('failLog', { states: [FailLog], events: [Items.Failed] })
+  const TestLayer = Layer.mergeAll(
+    ItemsLive,
+    Reducer.live(LogReducer, (log, event) => [...log, `${event.intent._tag}|${String(event.error)}`]),
+  ).pipe(
+    Layer.provideMerge(State.live(FailLog, [])),
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const queue = yield* Items.pending.store
+    const log = yield* FailLog.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+    yield* until(() => store.get(), (v) => v._tag === 'Success' && v.value.length === 2)
+    expect(queue.get()).toHaveLength(1)
+
+    // The send fails: entry leaves the queue, the view reverts by construction,
+    // and the Failed payload carried the intent + the error.
+    yield* until(() => queue.get(), (q) => q.length === 0)
+    const reverted = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.value.length === 1,
+    )
+    if (reverted._tag === 'Success') {
+      expect(reverted.value).toEqual([{ id: 'a', name: 'alpha' }])
+    }
+    yield* until(() => log.get(), (l) => l.length === 1)
+    expect(log.get()).toEqual(['Added|rejected'])
+    // No invalidation on failure: the one boot fetch is still the only one.
+    expect(server.state.fetches).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('two intents apply in dispatch order and settle together on the post-ack run', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => server.fetch(15),
+    send: (intent) => server.receive(intent, 15),
+    apply: applyIntent,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const queue = yield* Items.pending.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+
+    // Order matters: the rename targets the row the add creates. Reversed
+    // application would rename nothing and show 'beta'.
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+    yield* Event.dispatch(Renamed, { id: 'b', name: 'BETA' })
+    yield* until(() => queue.get(), (q) => q.length === 2)
+    const optimistic = store.get()
+    expect(optimistic).toMatchObject({ _tag: 'Success' })
+    if (optimistic._tag === 'Success') {
+      expect(optimistic.value[1]).toEqual({ id: 'b', name: 'BETA' })
+    }
+
+    yield* until(() => queue.get(), (q) => q.length === 0)
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+    if (settled._tag === 'Success') {
+      expect(settled.value).toEqual([
+        { id: 'a', name: 'alpha' },
+        { id: 'b', name: 'BETA' },
+      ])
+    }
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('one intent failing leaves the other pending and converging', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => server.fetch(10),
+    // The rename is rejected; the add is much slower and succeeds — so the
+    // partial state (one failed, one in flight) is observable.
+    send: (intent) =>
+      intent._tag === 'Renamed'
+        ? Effect.fail('rejected' as const).pipe(Effect.delay(Duration.millis(50)))
+        : server.receive(intent, 150),
+    apply: applyIntent,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const queue = yield* Items.pending.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+    yield* Event.dispatch(Renamed, { id: 'a', name: 'ALPHA' })
+    // Both folded: the overlay shows the rename optimistically.
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.value[0]?.name === 'ALPHA',
+    )
+    expect(queue.get()).toHaveLength(2)
+
+    // The rename fails and leaves; the add stays optimistic and intact.
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.value[0]?.name === 'alpha',
+    )
+    expect(queue.get()).toHaveLength(1)
+    expect(queue.get()[0]).toMatchObject({ status: 'sending', intent: { _tag: 'Added' } })
+    const partial = store.get()
+    if (partial._tag === 'Success') {
+      expect(partial.value).toEqual([
+        { id: 'a', name: 'alpha' },
+        { id: 'b', name: 'beta' },
+      ])
+    }
+
+    // The add converges independently.
+    yield* until(() => queue.get(), (q) => q.length === 0)
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+    if (settled._tag === 'Success') {
+      expect(settled.value).toEqual([
+        { id: 'a', name: 'alpha' },
+        { id: 'b', name: 'beta' },
+      ])
+    }
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live("pending exposes the lifecycle: 'sending' -> 'confirmed' -> gone", () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    // A slow refetch keeps the 'confirmed' window wide enough to observe.
+    query: () => server.fetch(40),
+    send: (intent) => server.receive(intent, 40),
+    apply: applyIntent,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const queue = yield* Items.pending.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+    const sending = yield* until(() => queue.get(), (q) => q.length === 1)
+    expect(sending[0]).toMatchObject({ status: 'sending', intent: { _tag: 'Added', id: 'b' } })
+
+    const confirmed = yield* until(
+      () => queue.get(),
+      (q) => q.length === 1 && q[0]?.status === 'confirmed',
+    )
+    expect(confirmed[0]).toMatchObject({ status: 'confirmed' })
+
+    yield* until(() => queue.get(), (q) => q.length === 0)
+    expect(queue.get()).toEqual([])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('gated: intents queue and send while Idle; re-enabling converges and settles', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => server.fetch(5),
+    send: (intent) => server.receive(intent, 10),
+    apply: applyIntent,
+    disabled: ({ page }) => page < 0,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: -1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'page').store
+    const store = yield* Items.store
+    const queue = yield* Items.pending.store
+    yield* tick()
+    expect(store.get()._tag).toBe('Idle')
+
+    // The intent still sends while the query is gated off: the server takes
+    // the mutation, but the view stays Idle and the entry waits for a run.
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+    yield* until(() => server.state.items, (items) => items.length === 2)
+    yield* tick(20)
+    expect(store.get()._tag).toBe('Idle')
+    expect(queue.get()).toHaveLength(1)
+    expect(server.state.fetches).toBe(0)
+
+    // Re-enable: the run lands with the mutation and settles the waiter.
+    source.set(1)
+    yield* until(() => queue.get(), (q) => q.length === 0)
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+    if (settled._tag === 'Success') {
+      expect(settled.value).toEqual([
+        { id: 'a', name: 'alpha' },
+        { id: 'b', name: 'beta' },
+      ])
+    }
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('reuse: untouched element identities survive the whole optimistic round-trip', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([
+    { id: 'a', name: 'alpha' },
+    { id: 'b', name: 'beta' },
+  ])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    // Fresh objects every fetch — only `reuse` can preserve identities.
+    query: () => Effect.map(server.fetch(10), (items) => items.map((item) => ({ ...item }))),
+    send: (intent) => server.receive(intent, 10),
+    apply: applyIntent,
+    reuse: true,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const queue = yield* Items.pending.store
+    const first = yield* until(() => store.get(), (v) => v._tag === 'Success')
+    if (first._tag !== 'Success') return
+    const untouched = first.value[0]
+
+    yield* Event.dispatch(Renamed, { id: 'b', name: 'BETA' })
+    yield* until(() => queue.get(), (q) => q.length === 1)
+    yield* until(() => queue.get(), (q) => q.length === 0)
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+    if (settled._tag !== 'Success') return
+    // Row a was never touched: same identity through the overlay recompute AND
+    // the convergence refetch. Row b moved: fresh.
+    expect(settled.value[0]).toBe(untouched)
+    expect(settled.value[1]).not.toBe(first.value[1])
+    expect(settled.value[1]).toEqual({ id: 'b', name: 'BETA' })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('invalidateOn + coalesce trailing compose with the mutation lifecycle', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  class BoardChanged extends Event.make('BoardChanged', S.Struct({})) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => server.fetch(10),
+    send: (intent) => server.receive(intent, 10),
+    apply: applyIntent,
+    invalidateOn: [BoardChanged],
+    coalesce: 'trailing',
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const queue = yield* Items.pending.store
+    yield* until(() => store.get(), (v) => v._tag === 'Success')
+    expect(server.state.fetches).toBe(1)
+
+    // A realtime push refetches like any invalidateOn event.
+    yield* Event.dispatch(BoardChanged, {})
+    yield* until(() => server.state.fetches, (n) => n === 2)
+
+    // The mutation lifecycle still converges under trailing conciliation.
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+    yield* until(() => queue.get(), (q) => q.length === 1)
+    yield* until(() => queue.get(), (q) => q.length === 0)
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+    if (settled._tag === 'Success') {
+      expect(settled.value).toEqual([
+        { id: 'a', name: 'alpha' },
+        { id: 'b', name: 'beta' },
+      ])
+    }
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a query Error passes through by reference with intents still pending', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    error: S.String,
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => Effect.fail('boom').pipe(Effect.delay(Duration.millis(5))),
+    send: (intent) => server.receive(intent, 10),
+    apply: applyIntent,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Items.store
+    const truth = yield* Items.truth.store
+    const queue = yield* Items.pending.store
+    yield* until(() => store.get(), (v) => v._tag === 'Error')
+
+    // The send succeeds and invalidates, but every run lands Error: an Error
+    // run settles NOBODY, so the entry stays pending (confirmed) — and the
+    // overlay passes the Error arm through by reference, never applying.
+    yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
+    yield* until(() => queue.get(), (q) => q.length === 1 && q[0]?.status === 'confirmed')
+    yield* until(() => store.get(), (v) => v._tag === 'Error' && v.refetching === false)
+    yield* tick(20)
+    expect(queue.get()).toHaveLength(1)
+    expect(store.get()).toBe(truth.get())
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('teardown: closing the scope unregisters the reducers, the procedure, and the channel', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => server.fetch(5),
+    send: (intent) => server.receive(intent, 5),
+    apply: applyIntent,
+  }).pipe(Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })))
+
+  return Effect.gen(function* () {
+    const reducers = yield* Reducers
+    const procedures = yield* Procedures
+    const channels = yield* Channels
+
+    yield* Effect.scoped(
+      Effect.gen(function* () {
+        yield* Layer.build(ItemsLive)
+        expect(reducers.entries.some((entry) => entry.name === 'Items/pending')).toBe(true)
+        expect(reducers.entries.some((entry) => entry.name === 'Items/revision')).toBe(true)
+        expect(procedures.entries.some((entry) => entry.name === 'Items/send')).toBe(true)
+        expect(channels.byName.has('Items/sends')).toBe(true)
+      }),
+    )
+
+    // Scope closed: every registration is gone (a lazy feature unmounting).
+    expect(reducers.entries.some((entry) => entry.name === 'Items/pending')).toBe(false)
+    expect(reducers.entries.some((entry) => entry.name === 'Items/revision')).toBe(false)
+    expect(procedures.entries.some((entry) => entry.name === 'Items/send')).toBe(false)
+    expect(channels.byName.has('Items/sends')).toBe(false)
+  }).pipe(Effect.provide(Engine))
+})