@playfast/reform 0.1.0 → 1.1.1

package/src/internal/errors.ts

@@ -1,28 +1,14 @@
 import { Cause, Data, Option, Runtime } from 'effect'
 
-/**
- * Tagged errors for the framework's synchronous boundaries. Even when thrown
- * (React render, layer build, reflection), an error carries a `_tag` and its
- * structured fields — never a bare `Error` — so callers and tooling can match on
- * it. `Data.TaggedError` subclasses are real `Error`s, so `throw` still works.
- */
-
-/**
- * The constructor shape `Data.TaggedError(tag)<A>` produces, named so the
- * generated `.d.ts` can describe the `extends` base under `isolatedDeclarations`
- * (which forbids an inferred expression in an extends clause).
- */
 type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = new (
   args: A,
 ) => Cause.YieldableError & { readonly _tag: Tag } & Readonly<A>
 
-/** The fieldless variant — a `Data.TaggedError(tag)<{}>` constructor. */
 type EmptyTaggedErrorClass<Tag extends string> = new () => Cause.YieldableError & { readonly _tag: Tag }
 
 const InvalidProvideTargetBase: EmptyTaggedErrorClass<'reform/InvalidProvideTarget'> =
   Data.TaggedError('reform/InvalidProvideTarget')<{}>
 
-/** `provide(target, …)` was handed something that is neither a ui contract nor a slot. */
 export class InvalidProvideTarget extends InvalidProvideTargetBase {
   override get message(): string {
     return 'reform: provide target is neither a ui contract nor a slot'
@@ -32,7 +18,6 @@ export class InvalidProvideTarget extends InvalidProvideTargetBase {
 const UnknownGroupStateBase: TaggedErrorClass<'reform/UnknownGroupState', { readonly name: string }> =
   Data.TaggedError('reform/UnknownGroupState')<{ readonly name: string }>
 
-/** `StateGroup.select(group, name)` named a state the group does not contain. */
 export class UnknownGroupState extends UnknownGroupStateBase {
   override get message(): string {
     return `reform: unknown state '${this.name}' in group`
@@ -42,12 +27,6 @@ export class UnknownGroupState extends UnknownGroupStateBase {
 const FeatureLoadFailedBase: TaggedErrorClass<'reform/FeatureLoadFailed', { readonly cause: unknown }> =
   Data.TaggedError('reform/FeatureLoadFailed')<{ readonly cause: unknown }>
 
-/**
- * A lazy `Feature`'s `load` Effect failed — the dynamic `import()` rejected (a
- * missing chunk, a network failure, a module-eval throw). Surfaced as a typed
- * failure the host hands to the feature's `placeholder.failed`, never a bare
- * rejection. `cause` is the original rejection value.
- */
 export class FeatureLoadFailed extends FeatureLoadFailedBase {
   override get message(): string {
     return `reform: a feature failed to load (${String(this.cause)})`
@@ -57,7 +36,6 @@ export class FeatureLoadFailed extends FeatureLoadFailedBase {
 const AsyncReducerBase: EmptyTaggedErrorClass<'reform/AsyncReducer'> =
   Data.TaggedError('reform/AsyncReducer')<{}>
 
-/** A reducer fold returned a thenable — folds must be pure synchronous writes. */
 export class AsyncReducer extends AsyncReducerBase {
   override get message(): string {
     return 'reform: a reducer fold must be synchronous (it returned a Promise)'
@@ -67,14 +45,6 @@ export class AsyncReducer extends AsyncReducerBase {
 const AsyncSceneLayerBase: EmptyTaggedErrorClass<'reform/AsyncSceneLayer'> =
   Data.TaggedError('reform/AsyncSceneLayer')<{}>
 
-/**
- * A scene layer performed async work during reform's synchronous layer build.
- * Reform materialises a scene's layer graph with `runSync` so the first frame
- * renders synchronously (D2); a `Layer.effect`/`scoped` whose acquire suspends
- * (HTTP, opening a DB, `Effect.sleep`) makes that `runSync` throw Effect's opaque
- * `AsyncFiberException`. `forceSync` catches it and rethrows this, which names the
- * cause and the sanctioned fix instead of pointing at Effect internals.
- */
 export class AsyncSceneLayer extends AsyncSceneLayerBase {
   override get message(): string {
     return (
@@ -87,12 +57,6 @@ export class AsyncSceneLayer extends AsyncSceneLayerBase {
   }
 }
 
-/**
- * Whether a thrown value is Effect's "ran async under runSync" defect. `runSync`
- * throws the bare `AsyncFiberException`; a `ManagedRuntime.runSync` whose layer
- * build suspends instead throws a `FiberFailure` carrying it as a `Die`, so both
- * shapes are checked.
- */
 const isAsyncBuildDefect = (error: unknown): boolean => {
   if (Runtime.isAsyncFiberException(error)) {
     return true
@@ -104,12 +68,6 @@ const isAsyncBuildDefect = (error: unknown): boolean => {
   return Option.isSome(die) && Runtime.isAsyncFiberException(die.value)
 }
 
-/**
- * Run a synchronous runtime read (the scene layer build / context capture) and
- * translate Effect's async-fiber defect into `AsyncSceneLayer`; any other throw
- * passes through unchanged. The single home for the sync-build boundary, shared by
- * the React host and the remote server.
- */
 export const forceSync = <A>(thunk: () => A): A => {
   // oxlint-disable-next-line reform-rules/no-try-catch -- sync-build boundary must throw the exact value, which Effect.runSync would re-wrap in a FiberFailure
   try {
@@ -125,14 +83,22 @@ const DuplicateRegistrationBase: TaggedErrorClass<
   { readonly kind: string; readonly name: string }
 > = Data.TaggedError('reform/DuplicateRegistration')<{ readonly kind: string; readonly name: string }>
 
-/**
- * Two distinct primitives were registered under one name into the same runtime —
- * a silent footgun, since names key DI tags and channel lanes. Thrown for a
- * channel name reused with a different policy (the second would otherwise be
- * dropped). Reducer/procedure name clashes are warned (logged), not thrown.
- */
 export class DuplicateRegistration extends DuplicateRegistrationBase {
   override get message(): string {
     return `reform: duplicate ${this.kind} registered under name '${this.name}'`
   }
 }
+
+const EventLoopOverflowBase: TaggedErrorClass<
+  'reform/EventLoopOverflow',
+  { readonly count: number; readonly limit: number }
+> = Data.TaggedError('reform/EventLoopOverflow')<{ readonly count: number; readonly limit: number }>
+
+export class EventLoopOverflow extends EventLoopOverflowBase {
+  override get message(): string {
+    return (
+      `reform: ${this.count} events processed without yielding to the event loop ` +
+      `(limit ${this.limit}) — likely an infinite event feedback loop; the runtime has been halted`
+    )
+  }
+}

package/src/internal/inspect.test.ts

@@ -3,24 +3,18 @@ import { Schema as S } from 'effect'
 import { State } from '../index'
 import { makeStore } from './store'
 
-// Every reform value should print like an Effect value (an `_id`-tagged JSON),
-// not `[object Object]` — via `toJSON`/`toString`/the Node inspect symbol.
-
 describe('Inspectable', () => {
   it('a Store reports its current value as tagged JSON', () => {
     const store = makeStore(41)
     expect(store.toJSON()).toEqual({ _id: 'reform/Store', value: 41 })
     store.set(42)
     expect(store.toJSON()).toEqual({ _id: 'reform/Store', value: 42 })
-    // toString and JSON.stringify route through the same toJSON.
     expect(JSON.parse(JSON.stringify(store))).toEqual({ _id: 'reform/Store', value: 42 })
     expect(store.toString()).toContain('reform/Store')
   })
 
   it('a definition reports its manifest', () => {
     class Count extends State.make('count', S.Number) {}
-    // Inspectable is attached at runtime (definitions are reflected via their
-    // manifest); reach the method through a typed view.
     const inspectable = Count as unknown as { toJSON(): unknown }
     expect(inspectable.toJSON()).toBe(Count.manifest)
     expect(String(Count)).toContain('"kind": "State"')

package/src/internal/inspect.ts

@@ -2,24 +2,12 @@ import { format, type Inspectable, NodeInspectSymbol } from 'effect/Inspectable'
 
 export { type Inspectable, NodeInspectSymbol }
 
-/**
- * The `Inspectable` trio built around a `toJSON`, so every reform value prints
- * like an Effect value — `_id`-tagged JSON under `console.log`, Node's
- * inspector, `JSON.stringify`, and `String(...)` — instead of `[object Object]`.
- * Mirrors Effect's `BaseProto` / `Inspectable.Class` (`Inspectable.ts:170`).
- */
 export const inspectable = (toJSON: () => unknown): Inspectable => ({
   toJSON,
   toString: () => format(toJSON()),
   [NodeInspectSymbol]: () => toJSON(),
 })
 
-/**
- * Attach the `Inspectable` trio to an existing object as *non-enumerable* own
- * properties (so they don't show up in `Object.keys`/`for…in` over a definition
- * class). Used where the value is built by other means — the definition classes,
- * whose statics are merged in separately.
- */
 export const attachInspectable = <T extends object>(target: T, toJSON: () => unknown): T => {
   const trio = inspectable(toJSON)
   Reflect.ownKeys(trio).forEach((key) => {

package/src/internal/queryDriver.ts

@@ -1,144 +1,56 @@
 import {
-  Brand,
   Cause,
   Chunk,
   Effect,
   MutableRef,
   Option,
   Queue,
-  Schema,
   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 type { QueryDriver, QueryDriverOptions } from './queryDriverTypes'
+import {
+  hydrateQuery,
+  incrementGeneration,
+  makePersistWriter,
+  makeQueryProjection,
+  subscribeQuerySources,
+  settleQueryError,
+  withReaderTracking,
+} from './queryDriverStore'
 import { resolveScheduler } from './scheduler'
 import {
   type InputsObject,
   type InputStores,
-  type InvalidateBy,
   sameKey,
   wireSources,
 } from './sources'
-import { makeDerivedStore, makeStore, type Store } from './store'
+import { makeStore } 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
-
-/** 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)
-
-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>
-      }
-    | 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
-}
+export {
+  bumpRevision,
+  gatedFlag,
+  type GatedOf,
+  type QueryDriver,
+  type QueryDriverOptions,
+  Revision,
+  RevisionSchema,
+  revisionZero,
+} from './queryDriverTypes'
 
-/**
- * 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>,
 ): Effect.Effect<QueryDriver<A, E>, never, InputStores<Inputs> | R | Scope.Scope> =>
   Effect.gen(function* () {
     const scheduler = yield* resolveScheduler
+    const instrumentation = yield* resolveInstrumentation
     const sources = yield* wireSources(options.inputs, options.invalidateBy)
     const extraKey = options.extraKey
     const persist = options.persist
@@ -146,44 +58,17 @@ 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 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)
     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)
     const markFetching = () => {
       const state = stateStore.get()
       if (!state.isFetching) {
@@ -204,51 +89,9 @@ 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 persistWriteTo = (
-      target: NonNullable<typeof persist>,
-      produced: A,
-      args: InputsObject<Inputs>,
-    ): Effect.Effect<void> =>
-      Schema.encode(target.schema)(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.
-        Effect.ignore,
-      )
-    const persistWrite = (produced: A, args: InputsObject<Inputs>): Effect.Effect<void> =>
-      persist === undefined ? Effect.void : persistWriteTo(persist, produced, args)
+    const persistWrite = makePersistWriter<Inputs, A>({ persist, queryStore })
 
-    // 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 {
@@ -256,8 +99,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
@@ -269,12 +110,11 @@ 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).
     const runQuery = (request: Request): Effect.Effect<void, never, R> =>
-      options.query(request.args).pipe(
+      Effect.sync(() => instrumentation.queryRun(options.name)).pipe(
+        Effect.flatMap((endSpan) =>
+          options.query(request.args).pipe(Effect.ensuring(Effect.sync(endSpan))),
+        ),
         Effect.tapDefect((defect) =>
           Effect.logError(`reform: ${options.label} '${options.name}' query defect`, defect),
         ),
@@ -283,7 +123,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)
+              settleQueryError(stateStore, failure.value)
             }
             return Option.none()
           },
@@ -296,11 +136,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(
@@ -323,12 +158,9 @@ 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.
         MutableRef.set(lastKey, undefined)
         stateStore.set(idle)
         return
@@ -345,8 +177,6 @@ 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) {
         refetch()
@@ -361,34 +191,19 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
       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).
     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,
-                }),
-            }),
-          ),
+      yield* hydrateQuery({
+        cacheKey: typeof persist.key === 'function' ? persist.key(hydrateArgs) : persist.key,
+        queryStore,
+        schema: persist.schema,
+        stateStore,
       })
     }
 
-    // Kick off the first fetch unless the query starts disabled.
     const initial = sources.snapshot()
     if (!disabledNow(initial)) {
       MutableRef.set(lastKey, keyOf(initial))
@@ -396,27 +211,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,
@@ -426,6 +226,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)))
     }