@playfast/reform 1.0.1 → 1.2.0

package/src/internal/queryDriver.ts

@@ -1,21 +1,28 @@
 import {
-  Brand,
   Cause,
   Chunk,
   Effect,
   MutableRef,
   Option,
+  type ParseResult,
   Queue,
-  Schema,
+  Runtime,
   type Scope,
   Stream,
 } from 'effect'
 import { type AnyAsyncData } from '../calc/asyncData'
-import { empty, type QueryState, toAsyncData } from '../calc/queryState'
+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 {
+  incrementGeneration,
+  makeQueryProjection,
+  subscribeQuerySources,
+  settleQueryError,
+  withReaderTracking,
+} from './queryDriverStore'
 import { resolveScheduler } from './scheduler'
 import {
   type InputsObject,
@@ -24,116 +31,54 @@ import {
   sameKey,
   wireSources,
 } from './sources'
-import { makeDerivedStore, makeStore, type Store } from './store'
+import { makeStore, type Store } from './store'
 import { type AnySource } from '../state/token'
 
-// The query-lifecycle driver shared by `AsyncCalc.live` and `RemoteState.live`:
-// sense the inputs, run the query latest-wins (or trailing-conflated), and fold
-// the result into a flat `QueryState` cell (data/error/isFetching/isStale). The
-// public store is the `AnyAsyncData` *projection* of that cell, so existing
-// arm-matching consumers and `RemoteState` are unchanged. `invalidate` (flip
-// `isStale`) and `refetch` (force a run) are exposed as separate operations and
-// registered into the `Queries` registry by name. The asyncCalc test suite is the
-// driver's regression suite.
-
-/** `Gated` (whether the `Idle` arm exists) is the inverse of `alwaysOn`. */
-export type GatedOf<AlwaysOn extends boolean> = AlwaysOn extends true ? false : true
+export {
+  bumpRevision,
+  gatedFlag,
+  type GatedOf,
+  Revision,
+  RevisionSchema,
+  revisionZero,
+} from './queryDriverTypes'
 
-/** The runtime gated flag for an `alwaysOn` config, typed as its `Gated` literal. */
-export const gatedFlag = <AlwaysOn extends boolean>(alwaysOn: AlwaysOn | undefined): GatedOf<AlwaysOn> =>
-  // oxlint-disable-next-line reform-rules/no-type-assertion -- restate the runtime boolean as its conditional `GatedOf` literal; no guard maps a boolean to a conditional type
-  (alwaysOn !== true) as GatedOf<AlwaysOn>
-
-// The hidden revision behind `invalidateOn` — a module-local *branded* number.
-// Reform store services are type-identified (`Context.GenericTag<Store<A>>`), so
-// the hidden state's value type must be un-collidable: `Layer.provide` erases
-// exactly `Store<Revision>` from the returned layer and can never type-level
-// erase a user input that happens to be a number state. Never exported from the
-// package index, so the editor catalog (which only indexes module exports)
-// never sees it.
-export type Revision = number & Brand.Brand<'reform/Revision'>
-export const Revision: Brand.Brand.Constructor<Revision> = Brand.nominal<Revision>()
-export const RevisionSchema: Schema.Schema<Revision, number> = Schema.Number.pipe(
-  Schema.brand('reform/Revision'),
-)
-export const revisionZero: Revision = Revision(0)
-export const bumpRevision = (revision: Revision): Revision => Revision(revision + 1)
+// Keep schema invariance behind a covariant persistence boundary.
+export interface QueryCodec<A> {
+  readonly encode: (value: A) => Effect.Effect<unknown, ParseResult.ParseError, never>
+  readonly decode: (input: unknown) => Effect.Effect<A, ParseResult.ParseError, never>
+}
 
 export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A, E, R> {
-  /** The owning definition's name — the defect log line and the `Queries` key. */
   readonly name: string
-  /** The owning primitive's kind label — only for the defect log line. */
   readonly label: string
-  /** Whether `disabled` is honored / the `Idle` arm can occur. */
   readonly gated: boolean
   readonly inputs: Inputs
   readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly invalidateBy?: InvalidateBy<Inputs> | undefined
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly disabled?: ((inputs: InputsObject<Inputs>) => boolean) | undefined
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly coalesce?: 'switch' | 'trailing' | undefined
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly reuse?: boolean | undefined
-  /**
-   * An extra key segment + wake source beyond the declared inputs — the hidden
-   * `invalidateOn` revision. Kept out of `wireSources` so the user's `query`
-   * and `invalidateBy` see exactly the declared inputs.
-   */
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly extraKey?:
     | {
         readonly read: () => unknown
         readonly subscribe: (listener: () => void) => () => void
       }
     | undefined
-  /**
-   * Persist the `Success` value through the optional `QueryStore`: hydrate the
-   * cell from `key` before the first run (seeded `isStale: true`, so it shows
-   * instantly and still refetches) and write through on each settle. Values
-   * (de)serialize through `schema`, never trusted structurally.
-   */
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly persist?:
     | {
-        // A static string keys a singleton read; a function of the inputs keys a
-        // family per-entity, so reactive-input keyed reads never collide on one slot.
         readonly key: string | ((inputs: InputsObject<Inputs>) => string)
-        readonly schema: Schema.Schema<A, any>
+        readonly codec: QueryCodec<A>
       }
     | undefined
-  /**
-   * Fired when a run's `Success` value has landed in the store (same scheduler
-   * flush — never before the converged value is readable), with the run's
-   * generation. Not fired on `Error`, interrupt, or while disabled. The seam
-   * `RemoteState` settles pending intents through.
-   */
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly onSettled?: ((generation: number) => void) | undefined
 }
 
 export interface QueryDriver<A, E> {
-  /** The lifecycle store (the `AnyAsyncData` projection — callers narrow to their arms). */
   readonly store: Store<AnyAsyncData<A, E>>
-  /**
-   * The highest generation requested so far (0 before the first kick).
-   * Generations are assigned when a run is REQUESTED (enqueued), so a waiter
-   * registered as `requested() + 1` is satisfied only by a run that began
-   * after registration — the settle-ordering rule `RemoteState` builds on.
-   */
   readonly requested: () => number
 }
 
-/**
- * Build the driver: state cell + projection + subscription + request queue + run
- * fiber, all owned by the ambient scope (callers run this under `Layer.scoped`). A
- * change to an input re-runs the query latest-wins (a new run cancels the in-flight
- * one; or, with `coalesce: 'trailing'`, lets it finish and runs one trailing
- * refetch); while a re-run is in flight the last `data`/`error` is kept with
- * `isFetching: true`. `invalidate` flips `isStale`; a stale query with active
- * readers auto-refetches (the same rule that drives refetch-on-resubscribe).
- */
 // oxlint-disable-next-line reform-rules/prefer-effect-fn -- generic export: Effect.fn's inferred type isn't portable under isolatedDeclarations
 export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R>(
   options: QueryDriverOptions<Inputs, A, E, R>,
@@ -148,44 +93,30 @@ 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()]
-    // The persist storage key at the current inputs: a static string for a
-    // singleton, or the per-input function for a keyed family (no DOM/extraKey
-    // churn — purely the user-declared key, so it stays stable across refetches).
-    const persistKey = (key: string | ((inputs: InputsObject<Inputs>) => string), args: InputsObject<Inputs>): string =>
-      typeof key === 'function' ? key(args) : key
-    const subscribeAll = (listener: () => void): (() => void) => {
-      const offSources = sources.subscribe(listener)
-      const offExtra = extraKey?.subscribe(listener)
-      return () => {
-        offSources()
-        offExtra?.()
-      }
-    }
+    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
 
-    // The flat source-of-truth cell. `idle` is a shared reference so re-disabling
-    // an already-idle query is a no-op write (the store's Equal gate suppresses it).
     const idle: QueryState<A, E> = empty(false)
     const stateStore = makeStore<QueryState<A, E>>(disabledNow() ? idle : empty(true), scheduler)
 
-    // Active-reader count of the PROJECTION (React components, the RemoteState
-    // overlay). Drives the "stale + active ⇒ refetch" policy and refetch-on-
-    // resubscribe (a 0→1 transition).
     const readers = MutableRef.make(0)
 
-    // The last requested key, so a change that doesn't move it (or only churns an
-    // input `invalidateBy` ignores) doesn't re-fetch.
     const lastKey = 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
+    // move this epoch, so cache may still paint during an in-flight revalidation.
+    const sourceEpoch = MutableRef.make(0)
     const generation = MutableRef.make(0)
-    const nextGeneration = (): number => {
-      MutableRef.update(generation, (current) => current + 1)
-      return MutableRef.get(generation)
-    }
-
-    // ── State writers, each touching only the axes it owns. The untouched axes
-    // keep their field references, so a pure `isStale` flip leaves the projection
-    // reference unmoved (see `project`). ──────────────────────────────────────
+    const nextGeneration = (): number => incrementGeneration(generation)
+    // A stale cause needs a strictly newer requested generation. Hydration
+    // 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) {
@@ -206,11 +137,10 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       })
       return shared
     }
-    const settleError = (error: E) => {
-      const prev = stateStore.get()
-      // Keep `data` underneath: `error` wins in the projection (the `Error` arm),
-      // but a consumer reading `QueryState` still has the last good value.
-      stateStore.set({ ...prev, error: Option.some(error), isFetching: false })
+    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 persistWriteTo = (
@@ -218,39 +148,15 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       produced: A,
       args: InputsObject<Inputs>,
     ): Effect.Effect<void> =>
-      Schema.encode(target.schema)(produced).pipe(
+      target.codec.encode(produced).pipe(
         Effect.flatMap((encoded) => queryStore.set(persistKey(target.key, args), encoded)),
-        // Persistence is best-effort: a serialization or storage failure must
-        // never fail the run nor block the visible write.
+        // 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)
 
-    // The projection the public store exposes: `AnyAsyncData`, memoized so a pure
-    // `isStale` change (which the projection ignores) returns the SAME reference
-    // and wakes no `AnyAsyncData` subscriber.
-    const projection = MutableRef.make<
-      { readonly state: QueryState<A, E>; readonly view: AnyAsyncData<A, E> } | undefined
-    >(undefined)
-    const project = (): AnyAsyncData<A, E> => {
-      const state = stateStore.get()
-      const prev = MutableRef.get(projection)
-      // The projection depends only on data/error/isFetching; writers preserve the
-      // refs of untouched axes, so reference identity on those three is exact.
-      if (
-        prev !== undefined &&
-        prev.state.data === state.data &&
-        prev.state.error === state.error &&
-        prev.state.isFetching === state.isFetching
-      ) {
-        return prev.view
-      }
-      const view = toAsyncData(state, options.gated)
-      MutableRef.set(projection, { state, view })
-      return view
-    }
-    const derived = makeDerivedStore(project, stateStore.subscribe, scheduler)
+    const derived = makeQueryProjection({ gated: options.gated, scheduler, stateStore })
     yield* Effect.addFinalizer(() => Effect.sync(derived.unsubscribe))
 
     interface Request {
@@ -258,8 +164,6 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       readonly generation: number
     }
 
-    // Commit a `Success` value: write the cell, report the generation, then persist
-    // (best-effort, trailing). A no-op when the query was disabled meanwhile.
     const commitSuccess = (produced: A, request: Request): Effect.Effect<void> => {
       if (disabledNow()) {
         return Effect.void
@@ -271,11 +175,6 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       })
     }
 
-    // One run of the query, folded into the cell. A failure becomes `Error`; an
-    // interrupt (latest-wins cancel) leaves the state untouched; a defect (a bug in
-    // the body) is logged and isolated. A `Success` reports its generation through
-    // `onSettled` after the write, then persists (best-effort, trailing). The
-    // `queryRun` span covers start → settle/cancel (`ensuring` fires on all three).
     const runQuery = (request: Request): Effect.Effect<void, never, R> =>
       Effect.sync(() => instrumentation.queryRun(options.name)).pipe(
         Effect.flatMap((endSpan) =>
@@ -289,7 +188,7 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
           onFailure: (cause): Option.Option<A> => {
             const failure = Cause.failureOption(cause)
             if (Option.isSome(failure) && !disabledNow()) {
-              settleError(failure.value)
+              settleError(failure.value, request.generation)
             }
             return Option.none()
           },
@@ -302,11 +201,6 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
         ),
       )
 
-    // The driver. `'switch'` (default): each new request cancels the in-flight run
-    // — the same latest-wins semantics a `latest` channel gives procedures.
-    // `'trailing'`: a strictly sequential consumer that, on wake, drains every
-    // request that piled up during the flight and runs the LATEST one — "exactly
-    // one trailing run after settle" by construction.
     const trailing = options.coalesce === 'trailing'
     const requests = yield* Queue.unbounded<Request>()
     const trailingConsumer = Effect.forever(
@@ -329,12 +223,12 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
     )
     yield* Effect.forkScoped(trailing ? trailingConsumer : switchConsumer)
 
-    // Enqueue a run of the current key, marking the flight. `force` skips the
-    // no-op-key guard (the refetch path); otherwise an unchanged key is ignored.
     const enqueue = (force: boolean) => {
       const args = sources.snapshot()
       if (disabledNow(args)) {
-        // Switched off: show Idle and forget the key so re-enabling always re-runs.
+        if (MutableRef.get(lastKey) !== undefined) {
+          MutableRef.update(sourceEpoch, (current) => current + 1)
+        }
         MutableRef.set(lastKey, undefined)
         stateStore.set(idle)
         return
@@ -344,6 +238,9 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       if (!force && previous !== undefined && sameKey(key, previous)) {
         return
       }
+      if (previous !== undefined && !sameKey(key, previous)) {
+        MutableRef.update(sourceEpoch, (current) => current + 1)
+      }
       MutableRef.set(lastKey, key)
       markFetching()
       Queue.unsafeOffer(requests, { args, generation: nextGeneration() })
@@ -351,10 +248,9 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
     const trigger = () => enqueue(false)
     const refetch = () => enqueue(true)
 
-    // `invalidate`: flip `isStale` only. A stale query with active readers then
-    // auto-refetches — the one place invalidation indirectly fetches.
     const maybeAutoRefetch = () => {
-      if (stateStore.get().isStale && MutableRef.get(readers) > 0) {
+      const hasCoveringRequest = MutableRef.get(generation) > MutableRef.get(staleAtGeneration)
+      if (stateStore.get().isStale && MutableRef.get(readers) > 0 && !hasCoveringRequest) {
         refetch()
       }
     }
@@ -363,38 +259,56 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       if (state.isStale) {
         return
       }
+      MutableRef.set(staleAtGeneration, MutableRef.get(generation))
       stateStore.set({ ...state, isStale: true })
       maybeAutoRefetch()
     }
 
-    const unsubscribe = subscribeAll(trigger)
+    const unsubscribe = subscribeQuerySources(sources, extraKey, trigger)
     yield* Effect.addFinalizer(() => Effect.sync(unsubscribe))
 
-    // Hydrate from the persisted value before the first kick: show it instantly,
-    // marked stale, so the kick refetches over it (stale-while-revalidate).
+    // Fork hydration so an asynchronous store never blocks layer acquisition.
+    // Epoch, key, and settled-state guards prevent a late cache from replacing newer truth.
     if (persist !== undefined && !disabledNow()) {
       const hydrateArgs = sources.snapshot()
-      const cached = yield* queryStore.get(persistKey(persist.key, hydrateArgs))
-      yield* Option.match(cached, {
-        onNone: () => Effect.void,
-        onSome: (raw) =>
-          Schema.decodeUnknown(persist.schema)(raw).pipe(
-            Effect.match({
-              // Corrupt/incompatible cache: ignore and fetch fresh.
-              onFailure: () => undefined,
-              onSuccess: (decoded) =>
-                stateStore.set({
-                  data: Option.some(decoded),
-                  error: Option.none(),
-                  isFetching: false,
-                  isStale: true,
-                }),
-            }),
-          ),
-      })
+      const hydrateSourceKey = keyOf(hydrateArgs)
+      const hydrateSourceEpoch = MutableRef.get(sourceEpoch)
+      const hydrateStaleAtGeneration = MutableRef.get(generation)
+      const hydrate = queryStore.get(persistKey(persist.key, hydrateArgs)).pipe(
+        Effect.flatMap((cached) =>
+          Option.match(cached, {
+            onNone: () => Effect.void,
+            onSome: (raw) =>
+              persist.codec.decode(raw).pipe(
+                Effect.tap((decoded) =>
+                  Effect.sync(() => {
+                    const state = stateStore.get()
+                    if (
+                      disabledNow() ||
+                      hydrateSourceEpoch !== MutableRef.get(sourceEpoch) ||
+                      !sameKey(hydrateSourceKey, keyOf(sources.snapshot())) ||
+                      Option.isSome(state.data) ||
+                      Option.isSome(state.error)
+                    ) {
+                      return
+                    }
+                    MutableRef.update(staleAtGeneration, (current) =>
+                      Math.max(current, hydrateStaleAtGeneration),
+                    )
+                    stateStore.set({ ...state, data: Option.some(decoded), isStale: true })
+                  }),
+                ),
+              ),
+          }),
+        ),
+        // Corrupt/incompatible cache: ignore and fetch fresh.
+        Effect.ignore,
+      )
+      const runtime = yield* Effect.runtime<never>()
+      const scope = yield* Effect.scope
+      Runtime.runFork(runtime)(hydrate, { immediate: true, scope })
     }
 
-    // Kick off the first fetch unless the query starts disabled.
     const initial = sources.snapshot()
     if (!disabledNow(initial)) {
       MutableRef.set(lastKey, keyOf(initial))
@@ -402,27 +316,12 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       Queue.unsafeOffer(requests, { args: initial, generation: nextGeneration() })
     }
 
-    // The public store: the projection, with reader-count tracking wrapped around
-    // `subscribe`, so a 0→1 transition can auto-refetch a stale query.
-    const store: Store<AnyAsyncData<A, E>> = {
-      ...derived.store,
-      subscribe: (listener) => {
-        const before = MutableRef.get(readers)
-        MutableRef.set(readers, before + 1)
-        const off = derived.store.subscribe(listener)
-        if (before === 0) {
-          maybeAutoRefetch()
-        }
-        return () => {
-          off()
-          MutableRef.update(readers, (count) => Math.max(0, count - 1))
-        }
-      },
-    }
+    const store = withReaderTracking({
+      store: derived.store,
+      readers,
+      onFirstReader: maybeAutoRefetch,
+    })
 
-    // Register the handle so `AsyncCalc.invalidate`/`.refetch` and provider layers
-    // can act on this query by name. Optional (`serviceOption`): an absent registry
-    // (a calc wired with no `Engine` in context) just means no imperative control.
     const handle: QueryHandle = {
       name: options.name,
       invalidate,
@@ -432,6 +331,11 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
     }
     const queries = Option.getOrUndefined(yield* Effect.serviceOption(Queries))
     if (queries !== undefined) {
+      if (queries.byName.has(handle.name)) {
+        yield* Effect.logWarning(
+          `reform: duplicate query name '${handle.name}' registered; previous registration is being replaced`,
+        )
+      }
       queries.register(handle)
       yield* Effect.addFinalizer(() => Effect.sync(() => queries.unregister(handle)))
     }

package/src/internal/queryDriverStore.ts

@@ -0,0 +1,156 @@
+import { Effect, MutableRef, Option, Schema } 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
+}
+
+export const subscribeQuerySources = (
+  sources: SubscribableSource,
+  extraKey: SubscribableSource | undefined,
+  listener: () => void,
+): (() => void) => {
+  const offSources = sources.subscribe(listener)
+  const offExtra = extraKey?.subscribe(listener)
+  return () => {
+    offSources()
+    offExtra?.()
+  }
+}
+
+export const settleQueryError = <A, E>(stateStore: Store<QueryState<A, E>>, error: E): void => {
+  const previous = stateStore.get()
+  stateStore.set({ ...previous, error: Option.some(error), isFetching: false })
+}
+
+export const incrementGeneration = (generation: MutableRef.MutableRef<number>): number => {
+  MutableRef.update(generation, (current) => current + 1)
+  return MutableRef.get(generation)
+}
+
+interface QueryProjectionOptions<A, E> {
+  readonly gated: boolean
+  readonly scheduler: Scheduler
+  readonly stateStore: Store<QueryState<A, E>>
+}
+
+export const makeQueryProjection = <A, E>(
+  options: QueryProjectionOptions<A, E>,
+): { readonly store: Store<AnyAsyncData<A, E>>; readonly unsubscribe: () => void } => {
+  const projection = MutableRef.make<
+    { readonly state: QueryState<A, E>; readonly view: AnyAsyncData<A, E> } | undefined
+  >(undefined)
+  const project = (): AnyAsyncData<A, E> => {
+    const state = options.stateStore.get()
+    const previous = MutableRef.get(projection)
+    if (
+      previous !== undefined &&
+      previous.state.data === state.data &&
+      previous.state.error === state.error &&
+      previous.state.isFetching === state.isFetching
+    ) {
+      return previous.view
+    }
+    const view = toAsyncData(state, options.gated)
+    MutableRef.set(projection, { state, view })
+    return view
+  }
+  return makeDerivedStore(project, options.stateStore.subscribe, options.scheduler)
+}
+
+interface ReaderStoreOptions<A, E> {
+  readonly store: Store<AnyAsyncData<A, E>>
+  readonly readers: MutableRef.MutableRef<number>
+  readonly onFirstReader: () => void
+}
+
+export const withReaderTracking = <A, E>(
+  options: ReaderStoreOptions<A, E>,
+): Store<AnyAsyncData<A, E>> => ({
+  ...options.store,
+  subscribe: (listener) => {
+    const before = MutableRef.get(options.readers)
+    MutableRef.set(options.readers, before + 1)
+    const off = options.store.subscribe(listener)
+    if (before === 0) {
+      options.onFirstReader()
+    }
+    return () => {
+      off()
+      MutableRef.update(options.readers, (count) => Math.max(0, count - 1))
+    }
+  },
+})