@playfast/reform 1.2.1 → 1.4.0

package/src/internal/queryDriver.ts

@@ -1,22 +1,24 @@
-import { Cause, Chunk, Effect, MutableRef, Option, Queue, Runtime, type Scope, Stream } from 'effect'
+import { Cause, Effect, MutableRef, Option, Queue, Runtime, type Scope } from 'effect'
 import { empty, type QueryState } from '../calc/queryState'
 import { Queries, type QueryHandle } from '../runtime/queries'
-import { reuse } from './reuse'
 import { resolveInstrumentation } from '../runtime/instrumentation'
 import { resolveQueryStore } from './queryStore'
+import { makePersistWrite, persistCacheKey } from './queryDriverPersist'
+import { makeSettlers } from './queryDriverSettle'
 import { hydratePersistedQuery } from './queryDriverHydrate'
 import {
   incrementGeneration,
   makeQueryProjection,
   subscribeQuerySources,
-  settleQueryError,
   withReaderTracking,
 } from './queryDriverStore'
 import type { QueryDriver, QueryDriverOptions } from './queryDriverTypes'
+import { consumeRequests } from './queryDriverConsume'
 import { resolveScheduler } from './scheduler'
 import { type InputsObject, type InputStores, sameKey, wireSources } from './sources'
 import { makeStore } from './store'
 import { type AnySource } from '../state/token'
+import { microtask } from './platform'
 
 export {
   bumpRevision,
@@ -44,19 +46,23 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
 
     const keyOf = (args: InputsObject<Inputs>): ReadonlyArray<unknown> =>
       extraKey === undefined ? sources.keyOf(args) : [...sources.keyOf(args), extraKey.read()]
-    const persistKey = (
-      key: string | ((inputs: InputsObject<Inputs>) => string),
-      args: InputsObject<Inputs>,
-    ): string => (typeof key === 'function' ? key(args) : key)
     const disabledNow = (args: InputsObject<Inputs> = sources.snapshot()): boolean =>
       options.gated && options.disabled !== undefined ? options.disabled(args) : false
 
-    const idle: QueryState<A, E> = empty(false)
-    const stateStore = makeStore<QueryState<A, E>>(disabledNow() ? idle : empty(true), scheduler)
+    const keepPreviousData = options.keepPreviousData === true
+    const idle: QueryState<A, E> = empty(false, keepPreviousData)
+    const stateStore = makeStore<QueryState<A, E>>(
+      disabledNow() ? idle : empty(true, keepPreviousData),
+      scheduler,
+    )
 
     const readers = MutableRef.make(0)
 
     const lastKey = MutableRef.make<ReadonlyArray<unknown> | undefined>(undefined)
+    // Attribution tracks the *source* key, not `keyOf`: `extraKey` carries the
+    // invalidateOn revision, and a revision bump revalidates the same question
+    // rather than asking a new one.
+    const lastSourceKey = MutableRef.make<ReadonlyArray<unknown> | undefined>(undefined)
     // Monotonic source epoch for the one startup hydration attempt. Comparing
     // only the current key is insufficient: A → B → A would otherwise let the
     // original A cache land over the later A request. Same-key refetches do not
@@ -68,50 +74,31 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
     // captures this before the startup kick, while invalidation captures it when
     // the value is marked stale.
     const staleAtGeneration = MutableRef.make(0)
-    const markFetching = () => {
-      const state = stateStore.get()
-      if (!state.isFetching) {
-        stateStore.set({ ...state, isFetching: true })
-      }
-    }
-    const settleSuccess = (produced: A): A => {
-      const prev = stateStore.get()
-      const shared =
-        options.reuse === true && Option.isSome(prev.data)
-          ? reuse(prev.data.value, produced)
-          : produced
-      stateStore.set({
-        data: Option.some(shared),
-        error: Option.none(),
-        isFetching: false,
-        isStale: false,
-      })
-      return shared
-    }
-    const settleError = (error: E, failedGeneration: number) => {
-      // Preserve the stale cause after failure without duplicating a newer request.
-      MutableRef.update(staleAtGeneration, (current) => Math.max(current, failedGeneration))
-      settleQueryError(stateStore, error)
-    }
+    const { markFetching, settleSuccess, settleError, settleDefect } = makeSettlers<A, E>({
+      stateStore,
+      lastSourceKey,
+      generation,
+      staleAtGeneration,
+      reuse: options.reuse === true,
+    })
 
-    const persistWriteTo = (
-      target: NonNullable<typeof persist>,
-      produced: A,
-      args: InputsObject<Inputs>,
-    ): Effect.Effect<void> =>
-      target.codec.encode(produced).pipe(
-        Effect.flatMap((encoded) => queryStore.set(persistKey(target.key, args), encoded)),
-        // Persistence is best-effort and must not block the visible write.
-        Effect.ignore,
-      )
-    const persistWrite = (produced: A, args: InputsObject<Inputs>): Effect.Effect<void> =>
-      persist === undefined ? Effect.void : persistWriteTo(persist, produced, args)
+    const persistWrite = makePersistWrite({
+      queryStore,
+      persist,
+      label: options.label,
+      name: options.name,
+    })
 
-    const derived = makeQueryProjection({ gated: options.gated, scheduler, stateStore })
+    const derived = makeQueryProjection({
+      gated: options.gated,
+      scheduler,
+      stateStore,
+    })
     yield* Effect.addFinalizer(() => Effect.sync(derived.unsubscribe))
 
     interface Request {
       readonly args: InputsObject<Inputs>
+      readonly sourceKey: ReadonlyArray<unknown>
       readonly generation: number
     }
 
@@ -120,7 +107,7 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
         return Effect.void
       }
       return Effect.suspend(() => {
-        const shared = settleSuccess(produced)
+        const shared = settleSuccess(produced, request)
         options.onSettled?.(request.generation)
         return persistWrite(shared, request.args)
       })
@@ -137,9 +124,11 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
         Effect.matchCause({
           onSuccess: (produced): Option.Option<A> => Option.some(produced),
           onFailure: (cause): Option.Option<A> => {
-            const failure = Cause.failureOption(cause)
-            if (Option.isSome(failure) && !disabledNow()) {
-              settleError(failure.value, request.generation)
+            if (!disabledNow()) {
+              Option.match(Cause.failureOption(cause), {
+                onSome: (error) => settleError(error, request),
+                onNone: () => settleDefect(request),
+              })
             }
             return Option.none()
           },
@@ -152,27 +141,15 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
         ),
       )
 
-    const trailing = options.coalesce === 'trailing'
     const requests = yield* Queue.unbounded<Request>()
-    const trailingConsumer = Effect.forever(
-      Effect.gen(function* () {
-        const first = yield* Queue.take(requests)
-        const queued = yield* Queue.takeAll(requests)
-        const request = Option.getOrElse(Chunk.last(queued), () => first)
-        if (!disabledNow()) {
-          yield* runQuery(request)
-        }
-        const pending = yield* Queue.size(requests)
-        if (pending > 0 && !disabledNow()) {
-          yield* Effect.sync(markFetching)
-        }
+    yield* Effect.forkScoped(
+      consumeRequests(options.coalesce === 'trailing', {
+        requests,
+        runQuery,
+        disabledNow: () => disabledNow(),
+        markFetching,
       }),
     )
-    const switchConsumer = Stream.fromQueue(requests).pipe(
-      Stream.flatMap((request) => Stream.fromEffect(runQuery(request)), { switch: true }),
-      Stream.runDrain,
-    )
-    yield* Effect.forkScoped(trailing ? trailingConsumer : switchConsumer)
 
     const enqueue = (force: boolean) => {
       const args = sources.snapshot()
@@ -181,6 +158,7 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
           MutableRef.update(sourceEpoch, (current) => current + 1)
         }
         MutableRef.set(lastKey, undefined)
+        MutableRef.set(lastSourceKey, undefined)
         stateStore.set(idle)
         return
       }
@@ -189,12 +167,16 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       if (!force && previous !== undefined && sameKey(key, previous)) {
         return
       }
+      const sourceKey = sources.keyOf(args)
+      const previousSourceKey = MutableRef.get(lastSourceKey)
+      const changedKey = previousSourceKey !== undefined && !sameKey(sourceKey, previousSourceKey)
       if (previous !== undefined && !sameKey(key, previous)) {
         MutableRef.update(sourceEpoch, (current) => current + 1)
       }
       MutableRef.set(lastKey, key)
-      markFetching()
-      Queue.unsafeOffer(requests, { args, generation: nextGeneration() })
+      MutableRef.set(lastSourceKey, sourceKey)
+      markFetching(changedKey)
+      Queue.unsafeOffer(requests, { args, sourceKey, generation: nextGeneration() })
     }
     const trigger = () => enqueue(false)
     const refetch = () => enqueue(true)
@@ -205,14 +187,32 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
         refetch()
       }
     }
-    const invalidate = () => {
-      const state = stateStore.get()
-      if (state.isStale) {
+    // Every invalidation in a frame is one signal, not N: the mark is raised
+    // synchronously but the response is coalesced onto a microtask, so a storm
+    // (a focus burst, several mutations acking together) issues one request. A
+    // later frame arms it again — that invalidation is genuinely uncovered by a
+    // request issued before it.
+    const refetchArmed = MutableRef.make(false)
+    const scheduleAutoRefetch = () => {
+      if (MutableRef.get(refetchArmed)) {
         return
       }
+      MutableRef.set(refetchArmed, true)
+      microtask(() => {
+        MutableRef.set(refetchArmed, false)
+        maybeAutoRefetch()
+      })
+    }
+    const invalidate = () => {
+      const state = stateStore.get()
+      // Always advance the mark: an invalidation raised while an earlier one's
+      // revalidation is in flight is not covered by that flight, so returning early
+      // on `isStale` would drop it whole (the refetch-on-focus path).
       MutableRef.set(staleAtGeneration, MutableRef.get(generation))
-      stateStore.set({ ...state, isStale: true })
-      maybeAutoRefetch()
+      if (!state.isStale) {
+        stateStore.set({ ...state, isStale: true })
+      }
+      scheduleAutoRefetch()
     }
 
     const unsubscribe = subscribeQuerySources(sources, extraKey, trigger)
@@ -225,7 +225,7 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       const hydrateSourceEpoch = MutableRef.get(sourceEpoch)
       const hydrate = hydratePersistedQuery({
         queryStore,
-        cacheKey: persistKey(persist.key, hydrateArgs),
+        cacheKey: persistCacheKey(persist.key, hydrateArgs),
         codec: persist.codec,
         stateStore,
         staleAtGeneration,
@@ -242,9 +242,16 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
 
     const initial = sources.snapshot()
     if (!disabledNow(initial)) {
-      MutableRef.set(lastKey, keyOf(initial))
+      const initialKey = keyOf(initial)
+      const initialSourceKey = sources.keyOf(initial)
+      MutableRef.set(lastKey, initialKey)
+      MutableRef.set(lastSourceKey, initialSourceKey)
       markFetching()
-      Queue.unsafeOffer(requests, { args: initial, generation: nextGeneration() })
+      Queue.unsafeOffer(requests, {
+        args: initial,
+        sourceKey: initialSourceKey,
+        generation: nextGeneration(),
+      })
     }
 
     const store = withReaderTracking({
@@ -271,5 +278,10 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       yield* Effect.addFinalizer(() => Effect.sync(() => queries.unregister(handle)))
     }
 
-    return { store, requested: () => MutableRef.get(generation) }
+    return {
+      store,
+      requested: () => MutableRef.get(generation),
+      key: () => sources.keyOf(sources.snapshot()),
+      subscribeKey: sources.subscribe,
+    }
   })

package/src/internal/queryDriverConsume.ts

@@ -0,0 +1,42 @@
+import { Chunk, Effect, Option, type Queue, Stream } from 'effect'
+
+// How a driver drains its request queue. `switch` keeps only the newest run alive;
+// `trailing` runs one at a time and collapses everything that piled up behind it,
+// re-raising the fetching mark when more is still waiting.
+export interface ConsumeOptions<Request, R> {
+  readonly requests: Queue.Queue<Request>
+  readonly runQuery: (request: Request) => Effect.Effect<void, never, R>
+  readonly disabledNow: () => boolean
+  readonly markFetching: () => void
+}
+
+const trailingConsumer = <Request, R>(
+  options: ConsumeOptions<Request, R>,
+): Effect.Effect<never, never, R> =>
+  Effect.forever(
+    Effect.gen(function* () {
+      const first = yield* options.requests.take
+      const queued = yield* options.requests.takeAll
+      const request = Option.getOrElse(Chunk.last(queued), () => first)
+      if (!options.disabledNow()) {
+        yield* options.runQuery(request)
+      }
+      const pending = yield* options.requests.size
+      if (pending > 0 && !options.disabledNow()) {
+        yield* Effect.sync(options.markFetching)
+      }
+    }),
+  )
+
+const switchConsumer = <Request, R>(
+  options: ConsumeOptions<Request, R>,
+): Effect.Effect<void, never, R> =>
+  Stream.fromQueue(options.requests).pipe(
+    Stream.flatMap((request) => Stream.fromEffect(options.runQuery(request)), { switch: true }),
+    Stream.runDrain,
+  )
+
+export const consumeRequests = <Request, R>(
+  trailing: boolean,
+  options: ConsumeOptions<Request, R>,
+): Effect.Effect<void, never, R> => (trailing ? trailingConsumer(options) : switchConsumer(options))

package/src/internal/queryDriverHydrate.ts

@@ -23,7 +23,12 @@ const paint = <A, E>(options: HydratePersistedOptions<A, E>, decoded: A): void =
   MutableRef.update(options.staleAtGeneration, (current) =>
     Math.max(current, options.capturedGeneration),
   )
-  options.stateStore.set({ ...state, data: Option.some(decoded), isStale: true })
+  options.stateStore.set({
+    ...state,
+    data: Option.some(decoded),
+    isStale: true,
+    isPreviousKey: false,
+  })
 }
 
 // Epoch, key, and settled-state guards prevent a late cache from replacing newer truth.
@@ -40,6 +45,7 @@ export const hydratePersistedQuery = <A, E>(
             .pipe(Effect.tap((decoded) => Effect.sync(() => paint(options, decoded)))),
       }),
     ),
-    // Corrupt/incompatible cache: ignore and fetch fresh.
-    Effect.ignore,
+    // Corrupt/incompatible cache: ignore and fetch fresh. Catches defects too — a
+    // store backed by localStorage throws rather than failing typed.
+    Effect.catchAllCause(() => Effect.void),
   )

package/src/internal/queryDriverPersist.ts

@@ -0,0 +1,42 @@
+import { Effect } from 'effect'
+import type { QueryStoreApi } from './queryStore'
+import type { QueryCodec } from './queryDriverTypes'
+
+export interface PersistTarget<Args, A> {
+  readonly key: string | ((inputs: Args) => string)
+  readonly codec: QueryCodec<A>
+}
+
+export const persistCacheKey = <Args>(
+  key: string | ((inputs: Args) => string),
+  args: Args,
+): string => (typeof key === 'function' ? key(args) : key)
+
+export interface PersistWriterOptions<Args, A> {
+  readonly queryStore: QueryStoreApi
+  readonly persist: PersistTarget<Args, A> | undefined
+  readonly label: string
+  readonly name: string
+}
+
+export const makePersistWrite = <Args, A>(
+  options: PersistWriterOptions<Args, A>,
+): ((produced: A, args: Args) => Effect.Effect<void>) => {
+  const target = options.persist
+  if (target === undefined) {
+    return () => Effect.void
+  }
+  return (produced, args) =>
+    target.codec.encode(produced).pipe(
+      Effect.flatMap((encoded) =>
+        options.queryStore.set(persistCacheKey(target.key, args), encoded),
+      ),
+      // Persistence is best-effort and must not block the visible write. This
+      // catches defects, not just typed failures: a store backed by localStorage
+      // *throws* when quota is exhausted, and `Effect.ignore` would let that escape
+      // and kill the request consumer for the rest of the session.
+      Effect.catchAllCause((cause) =>
+        Effect.logWarning(`reform: ${options.label} '${options.name}' persist failed`, cause),
+      ),
+    )
+}

package/src/internal/queryDriverPersistWarn.ts

@@ -0,0 +1,61 @@
+import { Effect, Predicate } from 'effect'
+
+// Mirrors the public `persist` config, whose shape is the author's to write.
+export type PersistOptionExternalApi<Args> =
+  | boolean
+  | undefined
+  | { readonly key?: string | ((inputs: Args) => string) }
+
+export interface PersistSlotInput<Args> {
+  readonly label: string
+  readonly name: string
+  readonly inputs: number
+  readonly option: PersistOptionExternalApi<Args>
+}
+
+interface SharedPersistSlot {
+  readonly label: string
+  readonly name: string
+  readonly inputs: number
+  readonly key: string | ((inputs: never) => string)
+  readonly enabled: boolean
+}
+
+// The cache slot a query persists into, plus the warning if that slot is shared.
+export const resolvePersistSlot = <Args>(
+  input: PersistSlotInput<Args>,
+): Effect.Effect<string | ((inputs: Args) => string)> => {
+  const option = input.option
+  const key =
+    option === true || option === undefined || option === false
+      ? input.name
+      : (option.key ?? input.name)
+  return Effect.as(
+    warnSharedPersistSlot({
+      label: input.label,
+      name: input.name,
+      inputs: input.inputs,
+      key,
+      enabled: option !== undefined && option !== false,
+    }),
+    key,
+  )
+}
+
+// A constant `persist` key gives every input key ONE cache slot: the last key to
+// settle overwrites the rest, and on the next boot that payload is hydrated as the
+// answer to whichever key is being asked. Sharing a slot on purpose is a legitimate
+// choice — a "last seen" cache — so this warns rather than refuses, but it must not
+// be silent: it is the same misattribution `isPreviousKey` exists to stop, arriving
+// across a reload where no epoch or key guard can see it.
+const warnSharedPersistSlot = (slot: SharedPersistSlot): Effect.Effect<void> => {
+  if (!slot.enabled || slot.inputs === 0 || !Predicate.isString(slot.key)) {
+    return Effect.void
+  }
+  return Effect.logWarning(
+    `reform: ${slot.label} '${slot.name}' persists ${slot.inputs} input(s) into the single cache slot ` +
+      `'${slot.key}'. Every input key overwrites the same entry, and a reload hydrates it as the answer ` +
+      `to whichever key is being asked. Pass persist: { key: (inputs) => ... } for a slot per key, or ` +
+      `keep the shared slot deliberately.`,
+  )
+}

package/src/internal/queryDriverSettle.ts

@@ -0,0 +1,85 @@
+import { MutableRef, Option } from 'effect'
+import type { QueryState } from '../calc/queryState'
+import { settleQueryError } from './queryDriverStore'
+import { reuse } from './reuse'
+import { sameKey } from './sources'
+import type { Store } from './store'
+
+// What a request is an answer to. `sourceKey` is the *input* key, excluding
+// `extraKey`: a revision bump revalidates the same question rather than asking a
+// new one, so it must not read as a key change.
+export interface SettleRequest {
+  readonly sourceKey: ReadonlyArray<unknown>
+  readonly generation: number
+}
+
+export interface SettlersOptions<A, E> {
+  readonly stateStore: Store<QueryState<A, E>>
+  readonly lastSourceKey: MutableRef.MutableRef<ReadonlyArray<unknown> | undefined>
+  readonly generation: MutableRef.MutableRef<number>
+  readonly staleAtGeneration: MutableRef.MutableRef<number>
+  readonly reuse: boolean
+}
+
+export interface Settlers<A, E> {
+  readonly supersededKey: (requestSourceKey: ReadonlyArray<unknown>) => boolean
+  readonly markFetching: (superseded?: boolean) => void
+  readonly settleSuccess: (produced: A, request: SettleRequest) => A
+  readonly settleError: (error: E, request: SettleRequest) => void
+  readonly settleDefect: (request: SettleRequest) => void
+}
+
+export const makeSettlers = <A, E>(options: SettlersOptions<A, E>): Settlers<A, E> => {
+  const { stateStore } = options
+
+  // A settling request answers the key it was issued for. If the sources have
+  // moved on, whatever it writes is about a question nobody is asking any more.
+  const supersededKey = (requestSourceKey: ReadonlyArray<unknown>): boolean => {
+    const current = MutableRef.get(options.lastSourceKey)
+    return current === undefined || !sameKey(requestSourceKey, current)
+  }
+
+  const markFetching = (superseded = false): void => {
+    const state = stateStore.get()
+    const isPreviousKey = state.isPreviousKey || superseded
+    if (!state.isFetching || isPreviousKey !== state.isPreviousKey) {
+      stateStore.set({ ...state, isFetching: true, isPreviousKey })
+    }
+  }
+
+  const settleSuccess = (produced: A, request: SettleRequest): A => {
+    const prev = stateStore.get()
+    const shared =
+      options.reuse && Option.isSome(prev.data) ? reuse(prev.data.value, produced) : produced
+    stateStore.set({
+      ...prev,
+      data: Option.some(shared),
+      error: Option.none(),
+      isFetching: false,
+      // An answer requested before an invalidation cannot discharge it: the mark
+      // clears only for a strictly newer generation, matching `maybeAutoRefetch`.
+      isStale: request.generation <= MutableRef.get(options.staleAtGeneration),
+      isPreviousKey: supersededKey(request.sourceKey),
+    })
+    return shared
+  }
+
+  const settleError = (error: E, request: SettleRequest): void => {
+    // Preserve the stale cause after failure without duplicating a newer request.
+    MutableRef.update(options.staleAtGeneration, (current) => Math.max(current, request.generation))
+    settleQueryError(stateStore, error, supersededKey(request.sourceKey))
+  }
+
+  // A run that dies is over; leaving `isFetching` raised advertises a flight that
+  // no longer exists. Only the newest run may retract it — a superseded run's
+  // death says nothing about its successor.
+  const settleDefect = (request: SettleRequest): void => {
+    if (MutableRef.get(options.generation) !== request.generation) {
+      return
+    }
+    const state = stateStore.get()
+    stateStore.set({ ...state, isFetching: false })
+  }
+
+  return { supersededKey, markFetching, settleSuccess, settleError, settleDefect }
+}

package/src/internal/queryDriverStore.ts

@@ -1,78 +1,8 @@
-import { Effect, MutableRef, Option, Schema } from 'effect'
+import { MutableRef, Option } from 'effect'
 import type { AnyAsyncData } from '../calc/asyncData'
 import { type QueryState, toAsyncData } from '../calc/queryState'
-import type { QueryStoreApi } from './queryStore'
 import type { Scheduler } from './scheduler'
 import { makeDerivedStore, type Store } from './store'
-import type { AnySchema } from './variance'
-import type { InputsObject } from './sources'
-import type { AnySource } from '../state/token'
-
-interface HydrateQueryOptions<A, E> {
-  readonly cacheKey: string
-  readonly queryStore: QueryStoreApi
-  readonly schema: AnySchema<A>
-  readonly stateStore: Store<QueryState<A, E>>
-}
-
-export const hydrateQuery = <A, E>(options: HydrateQueryOptions<A, E>): Effect.Effect<void> =>
-  Effect.flatMap(options.queryStore.get(options.cacheKey), (cached) =>
-    Option.match(cached, {
-      onNone: () => Effect.void,
-      onSome: (raw) =>
-        Schema.decodeUnknown(options.schema)(raw).pipe(
-          Effect.match({
-            onFailure: () => undefined,
-            onSuccess: (decoded) =>
-              options.stateStore.set({
-                data: Option.some(decoded),
-                error: Option.none(),
-                isFetching: false,
-                isStale: true,
-              }),
-          }),
-        ),
-    }),
-  )
-
-interface PersistQueryValueOptions<A> {
-  readonly cacheKey: string
-  readonly produced: A
-  readonly queryStore: QueryStoreApi
-  readonly schema: AnySchema<A>
-}
-
-export const persistQueryValue = <A>(options: PersistQueryValueOptions<A>): Effect.Effect<void> =>
-  Schema.encode(options.schema)(options.produced).pipe(
-    Effect.flatMap((encoded) => options.queryStore.set(options.cacheKey, encoded)),
-    Effect.ignore,
-  )
-
-interface PersistWriterOptions<Inputs extends ReadonlyArray<AnySource>, A> {
-  readonly persist:
-    | {
-        readonly key: string | ((inputs: InputsObject<Inputs>) => string)
-        readonly schema: AnySchema<A>
-      }
-    | undefined
-  readonly queryStore: QueryStoreApi
-}
-
-export const makePersistWriter = <Inputs extends ReadonlyArray<AnySource>, A>(
-  options: PersistWriterOptions<Inputs, A>,
-): ((produced: A, inputs: InputsObject<Inputs>) => Effect.Effect<void>) => {
-  if (options.persist === undefined) {
-    return () => Effect.void
-  }
-  const persist = options.persist
-  return (produced, inputs) =>
-    persistQueryValue({
-      cacheKey: typeof persist.key === 'function' ? persist.key(inputs) : persist.key,
-      produced,
-      queryStore: options.queryStore,
-      schema: persist.schema,
-    })
-}
 
 interface SubscribableSource {
   readonly subscribe: (listener: () => void) => () => void
@@ -91,9 +21,13 @@ export const subscribeQuerySources = (
   }
 }
 
-export const settleQueryError = <A, E>(stateStore: Store<QueryState<A, E>>, error: E): void => {
+export const settleQueryError = <A, E>(
+  stateStore: Store<QueryState<A, E>>,
+  error: E,
+  isPreviousKey: boolean,
+): void => {
   const previous = stateStore.get()
-  stateStore.set({ ...previous, error: Option.some(error), isFetching: false })
+  stateStore.set({ ...previous, error: Option.some(error), isFetching: false, isPreviousKey })
 }
 
 export const incrementGeneration = (generation: MutableRef.MutableRef<number>): number => {
@@ -120,7 +54,8 @@ export const makeQueryProjection = <A, E>(
       previous !== undefined &&
       previous.state.data === state.data &&
       previous.state.error === state.error &&
-      previous.state.isFetching === state.isFetching
+      previous.state.isFetching === state.isFetching &&
+      previous.state.isPreviousKey === state.isPreviousKey
     ) {
       return previous.view
     }

package/src/internal/queryDriverTypes.ts

@@ -36,6 +36,9 @@ export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A,
   readonly disabled?: ((inputs: InputsObject<Inputs>) => boolean) | undefined
   readonly coalesce?: 'switch' | 'trailing' | undefined
   readonly reuse?: boolean | undefined
+  // Show the previous key's result while the new key is in flight. Off by default:
+  // a retained payload is not an answer to the key being asked.
+  readonly keepPreviousData?: boolean | undefined
   readonly extraKey?:
     | {
         readonly read: () => unknown
@@ -54,4 +57,11 @@ export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A,
 export interface QueryDriver<A, E> {
   readonly store: Store<AnyAsyncData<A, E>>
   readonly requested: () => number
+  // The current *input* key, excluding `extraKey`: what a result or an optimistic
+  // intent is about. A revision bump revalidates the same question.
+  readonly key: () => ReadonlyArray<unknown>
+  // Wake on a key move. A reader that derives from the key as well as the payload
+  // cannot see one through the store: a key change that settles nothing writes
+  // nothing, so the payload it reads is unchanged while its meaning is not.
+  readonly subscribeKey: (listener: () => void) => () => void
 }