@playfast/reform 1.1.1 → 1.2.1

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

@@ -1,8 +1,30 @@
 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'
+import { Effect, Layer, ManagedRuntime, MutableRef, Option, Schema as S } from 'effect'
+import { AsyncCalc, Engine, forceSync, RemoteState, State, StateGroup } from '../index'
+import { QueryStore } from '../internal/queryStore'
+import { Queries } from '../runtime/queries'
+import { makeFlightGate, until } from '../testkit/flight.testkit'
 
-const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
+// Yielding through a runtime resumes at the tail of its scheduler queue, so work
+// already scheduled there — a hydration continuation, a consumer wake — has run.
+const scheduled: Effect.Effect<void> = Effect.yieldNow()
+
+interface Notifier {
+  readonly subscribe: (listener: () => void) => () => void
+}
+
+// One write notifies every listener in a single scheduler drain, and the driver
+// subscribed before the test did: our own notification proves its trigger ran.
+const afterNotify = (source: Notifier, write: () => void): Effect.Effect<void> =>
+  Effect.suspend(() => {
+    const fired = MutableRef.make(false)
+    const off = source.subscribe(() => MutableRef.set(fired, true))
+    write()
+    return until(
+      () => MutableRef.get(fired),
+      (value) => value,
+    ).pipe(Effect.ensuring(Effect.sync(off)), Effect.asVoid)
+  })
 
 const isStale = (name: string) =>
   Effect.map(Queries, (q) => q.byName.get(name)?.snapshot().isStale ?? false)
@@ -17,6 +39,37 @@ const fakeQueryStore = (seed: Record<string, unknown> = {}) => {
   return { map, layer }
 }
 
+const controlled = <A>() => {
+  const resolver = MutableRef.make<(value: A) => void>(() => {})
+  const promise = new Promise<A>((resume) => {
+    MutableRef.set(resolver, resume)
+  })
+  return { promise, resolve: (value: A) => MutableRef.get(resolver)(value) }
+}
+
+const promiseQueryStore = (get: (key: string) => Promise<Option.Option<unknown>>) => {
+  const map = new Map<string, unknown>()
+  const layer = Layer.succeed(QueryStore, {
+    get: (key) => Effect.promise(() => get(key)),
+    set: (key, value) => Effect.sync(() => void map.set(key, value)),
+    remove: (key) => Effect.sync(() => void map.delete(key)),
+  })
+  return { map, layer }
+}
+
+const rearmOnEveryChange = (subscribe: (listener: () => void) => () => void): (() => void) => {
+  const current = MutableRef.make<() => void>(() => {})
+  const arm = () => {
+    const unsubscribe = subscribe(() => {
+      MutableRef.get(current)()
+      arm()
+    })
+    MutableRef.set(current, unsubscribe)
+  }
+  arm()
+  return () => MutableRef.get(current)()
+}
+
 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) {}
@@ -40,16 +93,24 @@ it.live('invalidate marks stale without fetching; a fresh subscriber then refetc
 
   return Effect.gen(function* () {
     const store = yield* Q.store
-    yield* tick()
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
     expect(runs.n).toBe(1)
 
+    // A refetch would mark the state fetching inside `invalidate` itself, so the
+    // reader-less mark is observable without waiting for anything.
     yield* AsyncCalc.invalidate(Q)
-    yield* tick()
     expect(yield* isStale('Q')).toBe(true)
+    expect(store.get()).toMatchObject({ _tag: 'Success', refetching: false })
     expect(runs.n).toBe(1)
 
     store.subscribe(() => {})
-    yield* tick()
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false && runs.n > 1,
+    )
     expect(runs.n).toBe(2)
     expect(yield* isStale('Q')).toBe(false)
   }).pipe(Effect.provide(TestLayer))
@@ -64,12 +125,15 @@ it.live('invalidate with an active reader auto-refetches immediately, keeping th
     output: S.Number,
     alwaysOn: true,
   }) {}
+  const gate = makeFlightGate()
   const QLive = AsyncCalc.live(Q, {
     query: ({ count }) =>
-      Effect.sync(() => {
-        runs.n += 1
-        return count
-      }).pipe(Effect.delay(Duration.millis(20))),
+      gate.through(
+        Effect.sync(() => {
+          runs.n += 1
+          return count
+        }),
+      ),
   })
   const TestLayer = QLive.pipe(
     Layer.provideMerge(StateGroup.live(Inputs, { count: 7 })),
@@ -79,15 +143,26 @@ it.live('invalidate with an active reader auto-refetches immediately, keeping th
   return Effect.gen(function* () {
     const store = yield* Q.store
     store.subscribe(() => {})
-    yield* tick(40)
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
     expect(runs.n).toBe(1)
 
+    // The auto-refetch is parked at the gate, so "kept the value while
+    // refetching" is a stable state rather than a window to catch.
+    yield* gate.hold
     yield* AsyncCalc.invalidate(Q)
-    yield* tick(5)
+    yield* gate.awaitEntry(2)
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: true })
-    yield* tick(40)
-    expect(store.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
+
+    yield* gate.release
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+    expect(settled).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
     expect(runs.n).toBe(2)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -114,41 +189,667 @@ it.live('refetch forces a run regardless of staleness', () => {
   )
 
   return Effect.gen(function* () {
-    yield* tick()
+    const store = yield* Q.store
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
     expect(runs.n).toBe(1)
     expect(yield* isStale('Q')).toBe(false)
 
     yield* AsyncCalc.refetch(Q)
-    yield* tick()
+    yield* until(
+      () => runs.n,
+      (n) => n > 1,
+    )
     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) {}
+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 })
+    class Q extends AsyncCalc.make('Q', {
+      inputs: [StateGroup.select(Inputs, 'count')],
+      output: S.Number,
+      alwaysOn: true,
+    }) {}
+    const gate = makeFlightGate()
+    // Armed before the layer builds: the revalidation parks, so the hydrated
+    // (stale) paint is a stable state rather than a window to catch.
+    Effect.runSync(gate.hold)
+    const QLive = AsyncCalc.live(Q, {
+      query: ({ count }) => gate.through(Effect.succeed(count * 2)),
+      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
+      yield* gate.awaitEntry(1)
+      expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
+
+      yield* gate.release
+      const settled = yield* until(
+        () => view.get(),
+        (v) => v._tag === 'Success' && v.refetching === false,
+      )
+      expect(settled).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
+      yield* until(
+        () => store.map.get('P'),
+        (persisted) => persisted === 10,
+      )
+      expect(store.map.get('P')).toBe(10)
+    }).pipe(Effect.provide(TestLayer))
+  },
+)
+
+it('persist: a re-armed watcher does not duplicate the generation covering hydration', async () => {
+  const cached = controlled<Option.Option<unknown>>()
+  const fresh = controlled<number>()
+  const persisted = promiseQueryStore(() => cached.promise)
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('CoveredHydrationQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const TestLayer = AsyncCalc.live(Q, {
+    query: () =>
+      Effect.sync(() => {
+        runs.n += 1
+      }).pipe(Effect.zipRight(Effect.promise(() => fresh.promise))),
+    coalesce: 'trailing',
+    persist: true,
+  }).pipe(Layer.provideMerge(persisted.layer), Layer.provideMerge(Engine))
+  const runtime = ManagedRuntime.make(TestLayer)
+
+  const view = forceSync(() => runtime.runSync(Q.store))
+  const stop = rearmOnEveryChange(view.subscribe)
+  await runtime.runPromise(
+    until(
+      () => runs.n,
+      (n) => n > 0,
+    ),
+  )
+  expect(runs.n).toBe(1)
+
+  cached.resolve(Option.some(99))
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success',
+    ),
+  )
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
+
+  // A duplicated generation would leave a trailing request pending, so settling
+  // out of `refetching` is what proves the run was covered exactly once.
+  fresh.resolve(10)
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    ),
+  )
+  expect(runs.n).toBe(1)
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
+  stop()
+  await runtime.dispose()
+})
+
+it('persist: an explicit refetch still trails the generation covering hydration', async () => {
+  const cached = controlled<Option.Option<unknown>>()
+  const fresh = controlled<number>()
+  const persisted = promiseQueryStore(() => cached.promise)
+  const runs = { n: 0 }
+  class CoveredHydrationRefetchQ extends AsyncCalc.make('CoveredHydrationRefetchQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const TestLayer = AsyncCalc.live(CoveredHydrationRefetchQ, {
+    query: () =>
+      Effect.sync(() => {
+        runs.n += 1
+      }).pipe(Effect.zipRight(Effect.promise(() => fresh.promise))),
+    coalesce: 'trailing',
+    persist: true,
+  }).pipe(Layer.provideMerge(persisted.layer), Layer.provideMerge(Engine))
+  const runtime = ManagedRuntime.make(TestLayer)
+
+  const view = forceSync(() => runtime.runSync(CoveredHydrationRefetchQ.store))
+  const stop = rearmOnEveryChange(view.subscribe)
+  await runtime.runPromise(
+    until(
+      () => runs.n,
+      (n) => n > 0,
+    ),
+  )
+  cached.resolve(Option.some(99))
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success',
+    ),
+  )
+
+  await runtime.runPromise(AsyncCalc.refetch(CoveredHydrationRefetchQ))
+  fresh.resolve(10)
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    ),
+  )
+  expect(runs.n).toBe(2)
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
+  stop()
+  await runtime.dispose()
+})
+
+it('invalidate after a requested generation stays uncovered when hydration lands', async () => {
+  const cached = controlled<Option.Option<unknown>>()
+  const fresh = controlled<number>()
+  const persisted = promiseQueryStore(() => cached.promise)
+  const runs = { n: 0 }
+  class InFlightInvalidateQ extends AsyncCalc.make('InFlightInvalidateQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const TestLayer = AsyncCalc.live(InFlightInvalidateQ, {
+    query: () =>
+      Effect.sync(() => {
+        runs.n += 1
+      }).pipe(Effect.zipRight(Effect.promise(() => fresh.promise))),
+    coalesce: 'trailing',
+    persist: true,
+  }).pipe(Layer.provideMerge(persisted.layer), Layer.provideMerge(Engine))
+  const runtime = ManagedRuntime.make(TestLayer)
+
+  const view = forceSync(() => runtime.runSync(InFlightInvalidateQ.store))
+  await runtime.runPromise(
+    until(
+      () => runs.n,
+      (n) => n > 0,
+    ),
+  )
+  expect(runs.n).toBe(1)
+
+  await runtime.runPromise(AsyncCalc.invalidate(InFlightInvalidateQ))
+  expect(await runtime.runPromise(isStale('InFlightInvalidateQ'))).toBe(true)
+  cached.resolve(Option.some(99))
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success',
+    ),
+  )
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
+
+  const stop = rearmOnEveryChange(view.subscribe)
+  fresh.resolve(7)
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    ),
+  )
+  expect(runs.n).toBe(2)
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
+  stop()
+  await runtime.dispose()
+})
+
+it('a failed refetch leaves its stale mark uncovered, so a fresh subscriber retries', async () => {
+  const runs = { n: 0 }
+  class FailedCoverQ extends AsyncCalc.make('FailedCoverQ', {
+    inputs: [],
+    output: S.Number,
+    error: S.String,
+    alwaysOn: true,
+  }) {}
+  const runtime = ManagedRuntime.make(
+    AsyncCalc.live(FailedCoverQ, {
+      query: () =>
+        Effect.suspend((): Effect.Effect<number, string> => {
+          runs.n += 1
+          return runs.n === 2 ? Effect.fail('boom') : Effect.succeed(runs.n)
+        }),
+    }).pipe(Layer.provideMerge(Engine)),
+  )
+
+  const view = forceSync(() => runtime.runSync(FailedCoverQ.store))
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success',
+    ),
+  )
+  expect(runs.n).toBe(1)
+
+  // Invalidate with no readers, then attach one: that reader's refetch covers the
+  // stale mark, and it fails.
+  await runtime.runPromise(AsyncCalc.invalidate(FailedCoverQ))
+  const first = view.subscribe(() => {})
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Error',
+    ),
+  )
+  expect(runs.n).toBe(2)
+  expect(view.get()).toMatchObject({ _tag: 'Error', error: 'boom' })
+  expect(await runtime.runPromise(isStale('FailedCoverQ'))).toBe(true)
+
+  // Nothing successful has covered the mark, so the next subscriber still retries.
+  first()
+  view.subscribe(() => {})
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    ),
+  )
+  expect(runs.n).toBe(3)
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 3, refetching: false })
+  await runtime.dispose()
+})
+
+it('persist: hydration before any request still gets one initial revalidation', async () => {
+  const fresh = controlled<number>()
+  const persisted = fakeQueryStore({ SyncHydrationQ: 99 })
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('SyncHydrationQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const TestLayer = AsyncCalc.live(Q, {
+    query: () =>
+      Effect.sync(() => {
+        runs.n += 1
+      }).pipe(Effect.zipRight(Effect.promise(() => fresh.promise))),
+    coalesce: 'trailing',
+    persist: true,
+  }).pipe(Layer.provideMerge(persisted.layer), Layer.provideMerge(Engine))
+  const runtime = ManagedRuntime.make(TestLayer)
+
+  const view = forceSync(() => runtime.runSync(Q.store))
+  const stop = rearmOnEveryChange(view.subscribe)
+  await runtime.runPromise(
+    until(
+      () => runs.n,
+      (n) => n > 0,
+    ),
+  )
+  expect(runs.n).toBe(1)
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
+
+  fresh.resolve(10)
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    ),
+  )
+  expect(runs.n).toBe(1)
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
+  stop()
+  await runtime.dispose()
+})
+
+it('a genuine key change still enqueues a trailing generation', async () => {
+  const release = controlled<void>()
+  const runs = { n: 0 }
+  class Count extends State.make('key-change-count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
-  const store = fakeQueryStore({ P: 99 })
-  class Q extends AsyncCalc.make('Q', {
-    inputs: [StateGroup.select(Inputs, 'count')],
+  class Q extends AsyncCalc.make('InFlightKeyChangeQ', {
+    inputs: [StateGroup.select(Inputs, 'key-change-count')],
     output: S.Number,
     alwaysOn: true,
   }) {}
-  const QLive = AsyncCalc.live(Q, {
-    query: ({ count }) => Effect.succeed(count * 2).pipe(Effect.delay(Duration.millis(25))),
+  const TestLayer = AsyncCalc.live(Q, {
+    query: ({ 'key-change-count': count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+      }).pipe(Effect.zipRight(Effect.promise(() => release.promise)), Effect.as(count)),
+    coalesce: 'trailing',
+  }).pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { 'key-change-count': 1 })),
+    Layer.provideMerge(Engine),
+  )
+  const runtime = ManagedRuntime.make(TestLayer)
+
+  const view = forceSync(() => runtime.runSync(Q.store))
+  const count = runtime.runSync(Count.store)
+  await runtime.runPromise(
+    until(
+      () => runs.n,
+      (n) => n > 0,
+    ),
+  )
+  expect(runs.n).toBe(1)
+
+  // The change is enqueued, not run: the first generation still owns the slot.
+  await runtime.runPromise(afterNotify(count, () => count.set(2)))
+  expect(runs.n).toBe(1)
+  release.resolve()
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success' && v.value === 2 && v.refetching === false,
+    ),
+  )
+  expect(runs.n).toBe(2)
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 2, refetching: false })
+  await runtime.dispose()
+})
+
+it('persist: promise-backed hydration keeps construction synchronous and preserves SWR ordering', async () => {
+  const cached = controlled<Option.Option<unknown>>()
+  const fresh = controlled<number>()
+  const store = promiseQueryStore(() => cached.promise)
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('AsyncPersistQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const TestLayer = AsyncCalc.live(Q, {
+    query: () => {
+      runs.n += 1
+      return Effect.promise(() => fresh.promise)
+    },
     persist: { key: 'P' },
+  }).pipe(Layer.provideMerge(store.layer), Layer.provideMerge(Engine))
+  const runtime = ManagedRuntime.make(TestLayer)
+
+  const view = forceSync(() => runtime.runSync(Q.store))
+  expect(view.get()).toMatchObject({ _tag: 'Loading' })
+  await runtime.runPromise(
+    until(
+      () => runs.n,
+      (n) => n > 0,
+    ),
+  )
+  expect(runs.n).toBe(1)
+
+  cached.resolve(Option.some(99))
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success',
+    ),
+  )
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
+
+  fresh.resolve(10)
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    ),
+  )
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
+  await runtime.runPromise(
+    until(
+      () => store.map.get('P'),
+      (persisted) => persisted === 10,
+    ),
+  )
+  expect(store.map.get('P')).toBe(10)
+  await runtime.dispose()
+})
+
+it('persist: late or corrupt hydration cannot overwrite fresh truth or a changed source key', async () => {
+  const cacheByKey = new Map<string, ReturnType<typeof controlled<Option.Option<unknown>>>>()
+  const store = promiseQueryStore((key) => {
+    const pending = controlled<Option.Option<unknown>>()
+    cacheByKey.set(key, pending)
+    return pending.promise
   })
-  const TestLayer = QLive.pipe(
-    Layer.provideMerge(StateGroup.live(Inputs, { count: 5 })),
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class Q extends AsyncCalc.make('AsyncPersistKeyed', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const TestLayer = AsyncCalc.live(Q, {
+    query: ({ count }) => Effect.succeed(count * 10),
+    persist: { key: ({ count }) => `P:${count}` },
+  }).pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })),
     Layer.provideMerge(store.layer),
     Layer.provideMerge(Engine),
   )
+  const runtime = ManagedRuntime.make(TestLayer)
+  const view = forceSync(() => runtime.runSync(Q.store))
+  const count = runtime.runSync(Count.store)
 
-  return Effect.gen(function* () {
-    const view = yield* Q.store
-    expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
+  count.set(2)
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success' && v.value === 20 && v.refetching === false,
+    ),
+  )
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 20, refetching: false })
+  // Awaiting the same promise, then a scheduler round, lands after every
+  // continuation the superseded hydration could still have been holding.
+  cacheByKey.get('P:1')?.resolve(Option.some(99))
+  await cacheByKey.get('P:1')?.promise
+  await runtime.runPromise(scheduled)
+  expect(view.get()).toMatchObject({ _tag: 'Success', value: 20, refetching: false })
 
-    yield* tick(45)
-    expect(view.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
-    expect(store.map.get('P')).toBe(10)
-  }).pipe(Effect.provide(TestLayer))
+  await runtime.dispose()
+
+  const churnedCache = controlled<Option.Option<unknown>>()
+  const churnedStore = promiseQueryStore(() => churnedCache.promise)
+  const churnedRuntime = ManagedRuntime.make(
+    AsyncCalc.live(Q, {
+      query: () => Effect.never,
+      persist: { key: ({ count }) => `churned:${count}` },
+    }).pipe(
+      Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })),
+      Layer.provideMerge(churnedStore.layer),
+      Layer.provideMerge(Engine),
+    ),
+  )
+  const churnedView = forceSync(() => churnedRuntime.runSync(Q.store))
+  const churnedCount = churnedRuntime.runSync(Count.store)
+  await churnedRuntime.runPromise(afterNotify(churnedCount, () => churnedCount.set(2)))
+  await churnedRuntime.runPromise(afterNotify(churnedCount, () => churnedCount.set(1)))
+  churnedCache.resolve(Option.some(99))
+  await churnedCache.promise
+  await churnedRuntime.runPromise(scheduled)
+  expect(churnedView.get()).toMatchObject({ _tag: 'Loading' })
+  await churnedRuntime.dispose()
+
+  const erroredCache = controlled<Option.Option<unknown>>()
+  const erroredStore = promiseQueryStore(() => erroredCache.promise)
+  class ErroredQ extends AsyncCalc.make('AsyncPersistErrored', {
+    inputs: [],
+    output: S.Number,
+    error: S.String,
+    alwaysOn: true,
+  }) {}
+  const erroredRuntime = ManagedRuntime.make(
+    AsyncCalc.live(ErroredQ, {
+      query: () => Effect.fail('fresh-error'),
+      persist: true,
+    }).pipe(Layer.provideMerge(erroredStore.layer), Layer.provideMerge(Engine)),
+  )
+  const erroredView = forceSync(() => erroredRuntime.runSync(ErroredQ.store))
+  const queries = erroredRuntime.runSync(Queries)
+  await erroredRuntime.runPromise(
+    until(
+      () => erroredView.get(),
+      (v) => v._tag === 'Error',
+    ),
+  )
+  expect(erroredView.get()).toMatchObject({ _tag: 'Error', error: 'fresh-error' })
+  erroredCache.resolve(Option.some(99))
+  await erroredCache.promise
+  await erroredRuntime.runPromise(scheduled)
+  expect(erroredView.get()).toMatchObject({ _tag: 'Error', error: 'fresh-error' })
+  const erroredHandle = queries.byName.get('AsyncPersistErrored')
+  expect(erroredHandle).toBeDefined()
+  if (erroredHandle !== undefined) {
+    expect(Option.isNone(erroredHandle.snapshot().data)).toBe(true)
+  }
+  await erroredRuntime.dispose()
+
+  const corrupt = controlled<Option.Option<unknown>>()
+  const pendingFresh = controlled<number>()
+  const corruptStore = promiseQueryStore(() => corrupt.promise)
+  const corruptRuntime = ManagedRuntime.make(
+    AsyncCalc.live(Q, {
+      query: () => Effect.promise(() => pendingFresh.promise),
+      persist: { key: 'corrupt' },
+    }).pipe(
+      Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })),
+      Layer.provideMerge(corruptStore.layer),
+      Layer.provideMerge(Engine),
+    ),
+  )
+  const corruptView = forceSync(() => corruptRuntime.runSync(Q.store))
+  corrupt.resolve(Option.some('not-a-number'))
+  await corrupt.promise
+  await corruptRuntime.runPromise(scheduled)
+  expect(corruptView.get()).toMatchObject({ _tag: 'Loading' })
+  pendingFresh.resolve(7)
+  await corruptRuntime.runPromise(
+    until(
+      () => corruptView.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    ),
+  )
+  expect(corruptView.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
+  await corruptRuntime.dispose()
+})
+
+it('persist: finalization and gating prevent late or unnecessary hydration', async () => {
+  const cached = controlled<Option.Option<unknown>>()
+  const store = promiseQueryStore(() => cached.promise)
+  class Q extends AsyncCalc.make('FinalizedPersistQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const runtime = ManagedRuntime.make(
+    AsyncCalc.live(Q, {
+      query: () => Effect.never,
+      persist: true,
+    }).pipe(Layer.provideMerge(store.layer), Layer.provideMerge(Engine)),
+  )
+  const view = forceSync(() => runtime.runSync(Q.store))
+  await runtime.dispose()
+
+  // The scope is closed, so awaiting the cache promise is enough: any surviving
+  // hydration would resume on that same continuation.
+  cached.resolve(Option.some(99))
+  await cached.promise
+  await Effect.runPromise(scheduled)
+  expect(view.get()).toMatchObject({ _tag: 'Loading' })
+  expect(store.map.size).toBe(0)
+
+  const disabledCalls = { gets: 0, runs: 0 }
+  const disabledStore = promiseQueryStore(() => {
+    disabledCalls.gets += 1
+    return Promise.resolve(Option.some(1))
+  })
+  class Enabled extends State.make('disabled-persist-enabled', S.Boolean) {}
+  class DisabledInputs extends StateGroup.make(Enabled) {}
+  class DisabledQ extends AsyncCalc.make('DisabledPersistQ', {
+    inputs: [StateGroup.select(DisabledInputs, 'disabled-persist-enabled')],
+    output: S.Number,
+  }) {}
+  const disabledRuntime = ManagedRuntime.make(
+    AsyncCalc.live(DisabledQ, {
+      query: () => Effect.sync(() => (disabledCalls.runs += 1)),
+      disabled: ({ 'disabled-persist-enabled': enabled }) => !enabled,
+      persist: true,
+    }).pipe(
+      Layer.provideMerge(StateGroup.live(DisabledInputs, { 'disabled-persist-enabled': false })),
+      Layer.provideMerge(disabledStore.layer),
+      Layer.provideMerge(Engine),
+    ),
+  )
+  const disabledView = forceSync(() => disabledRuntime.runSync(DisabledQ.store))
+  const enabled = disabledRuntime.runSync(Enabled.store)
+  expect(disabledView.get()).toMatchObject({ _tag: 'Idle' })
+  expect(disabledCalls).toEqual({ gets: 0, runs: 0 })
+
+  // Enabling is the anchor: once its run has landed, a hydration read during the
+  // disabled window would already have shown up in the counts.
+  enabled.set(true)
+  await disabledRuntime.runPromise(
+    until(
+      () => disabledView.get(),
+      (v) => v._tag === 'Success',
+    ),
+  )
+  expect(disabledView.get()).toMatchObject({ _tag: 'Success', value: 1 })
+  expect(disabledCalls).toEqual({ gets: 0, runs: 1 })
+  await disabledRuntime.dispose()
+})
+
+it('persist: promise hydration is shared by RemoteState and participates in reuse', async () => {
+  const Item = S.Struct({ id: S.String, name: S.String })
+  type Item = typeof Item.Type
+  const cached = controlled<Option.Option<unknown>>()
+  const fresh = controlled<ReadonlyArray<Item>>()
+  const store = promiseQueryStore(() => cached.promise)
+  class Items extends RemoteState.make('AsyncPersistRemoteItems', {
+    inputs: [],
+    output: S.Array(Item),
+    intents: [],
+    alwaysOn: true,
+  }) {}
+  const runtime = ManagedRuntime.make(
+    RemoteState.live(Items, {
+      query: () => Effect.promise(() => fresh.promise),
+      send: () => Effect.void,
+      apply: (items) => items,
+      persist: true,
+      reuse: true,
+    }).pipe(Layer.provideMerge(store.layer), Layer.provideMerge(Engine)),
+  )
+  const view = forceSync(() => runtime.runSync(Items.store))
+  const cachedItem = { id: 'a', name: 'alpha' }
+  cached.resolve(Option.some([cachedItem]))
+  await runtime.runPromise(
+    until(
+      () => view.get(),
+      (v) => v._tag === 'Success',
+    ),
+  )
+  const hydrated = view.get()
+  expect(hydrated).toMatchObject({ _tag: 'Success', refetching: true })
+  if (hydrated._tag === 'Success') {
+    fresh.resolve([{ id: 'a', name: 'alpha' }])
+    await runtime.runPromise(
+      until(
+        () => view.get(),
+        (v) => v._tag === 'Success' && v.refetching === false,
+      ),
+    )
+    const settled = view.get()
+    expect(settled).toMatchObject({ _tag: 'Success', refetching: false })
+    if (settled._tag === 'Success') {
+      expect(settled.value[0]).toBe(hydrated.value[0])
+      expect(store.map.get('AsyncPersistRemoteItems')).toEqual([{ id: 'a', name: 'alpha' }])
+    }
+  }
+  await runtime.dispose()
 })