@playfast/reform 0.0.9 → 0.0.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform",
   "playbook": "./playbook",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "type": "module",
   "description": "The renderer-neutral core of the reform framework — typed, headless state, events, reducers, derived values, async/remote data, and compositions built on Effect.",
   "keywords": [

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

@@ -0,0 +1,166 @@
+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'
+
+// The data-oriented half of AsyncCalc: `invalidate` flips `isStale` only (no
+// fetch), `refetch` forces a run, a stale query with active readers (or a fresh
+// subscriber) refetches, and `persist` hydrates + writes through an optional
+// QueryStore. `isStale` is read off the `Queries` registry handle.
+
+const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
+
+const isStale = (name: string) =>
+  Effect.map(Queries, (q) => q.byName.get(name)?.snapshot().isStale ?? false)
+
+// An in-memory QueryStore, so persistence is exercised with no DOM.
+const fakeQueryStore = (seed: Record<string, unknown> = {}) => {
+  const map = new Map<string, unknown>(Object.entries(seed))
+  const layer = Layer.succeed(QueryStore, {
+    get: (key) => Effect.sync(() => Option.fromNullable(map.has(key) ? map.get(key) : undefined)),
+    set: (key, value) => Effect.sync(() => void map.set(key, value)),
+    remove: (key) => Effect.sync(() => void map.delete(key)),
+  })
+  return { map, layer }
+}
+
+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) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return count
+      }),
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Q.store
+    yield* tick()
+    expect(runs.n).toBe(1)
+
+    // No active readers: invalidate flips the flag but fetches nothing.
+    yield* AsyncCalc.invalidate(Q)
+    yield* tick()
+    expect(yield* isStale('Q')).toBe(true)
+    expect(runs.n).toBe(1)
+
+    // A reader arriving over a stale query (the resubscribe/mount analog) refetches.
+    store.subscribe(() => {})
+    yield* tick()
+    expect(runs.n).toBe(2)
+    expect(yield* isStale('Q')).toBe(false)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('invalidate with an active reader auto-refetches immediately, keeping the value', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return count
+      }).pipe(Effect.delay(Duration.millis(20))),
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 7 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* Q.store
+    store.subscribe(() => {}) // active reader
+    yield* tick(40)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
+    expect(runs.n).toBe(1)
+
+    // Stale + active ⇒ refetch now; the last value stays visible (SWR).
+    yield* AsyncCalc.invalidate(Q)
+    yield* tick(5)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: true })
+    yield* tick(40)
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 7, refetching: false })
+    expect(runs.n).toBe(2)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('refetch forces a run regardless of staleness', () => {
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  const runs = { n: 0 }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return count
+      }),
+  })
+  const TestLayer = QLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { count: 3 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    yield* tick()
+    expect(runs.n).toBe(1)
+    expect(yield* isStale('Q')).toBe(false)
+
+    // Not stale, no key movement — refetch still runs.
+    yield* AsyncCalc.refetch(Q)
+    yield* tick()
+    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) {}
+  class Inputs extends StateGroup.make(Count) {}
+  const store = fakeQueryStore({ P: 99 }) // a previously-persisted value
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const QLive = AsyncCalc.live(Q, {
+    query: ({ count }) => Effect.succeed(count * 2).pipe(Effect.delay(Duration.millis(25))),
+    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
+    // The persisted value shows instantly, marked refetching (stale-while-revalidate).
+    expect(view.get()).toMatchObject({ _tag: 'Success', value: 99, refetching: true })
+
+    // The fresh fetch lands and is written through to the store.
+    yield* tick(45)
+    expect(view.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
+    expect(store.map.get('P')).toBe(10)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/calc/asyncCalc.ts

@@ -18,6 +18,7 @@ import { type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 import * as Reducer from '../reducer/reducer'
 import { Reducers } from '../runtime/loop'
+import { Queries } from '../runtime/queries'
 import * as State from '../state/state'
 import { type AnySource } from '../state/token'
 import { type AsyncData, narrowStore } from './asyncData'
@@ -97,6 +98,15 @@ export type AsyncCalcLive<
    * `Calc`'s `reuse`; opt-in (one O(result) walk per settle).
    */
   readonly reuse?: boolean
+  /**
+   * Persist the `Success` value through an optional host `QueryStore` (e.g.
+   * `@playfast/reform-query-browser`'s localStorage layer): hydrate it on build
+   * so the value shows instantly (marked stale, so it still refetches) and write
+   * through on each settle. `true` keys it by the calc name; pass `{ key }` to
+   * override. Values (de)serialize through the calc's `output` schema. No host
+   * `QueryStore` in context ⇒ inert (no hard requirement added).
+   */
+  readonly persist?: boolean | { readonly key?: string }
 } & (Gated extends true
   ? { readonly disabled?: (inputs: InputsObject<Inputs>) => boolean }
   : { readonly disabled?: never })
@@ -214,8 +224,20 @@ export function live<
         readonly disabled?: (inputs: InputsObject<Inputs>) => boolean
         readonly coalesce?: 'switch' | 'trailing'
         readonly reuse?: boolean
+        readonly persist?: boolean | { readonly key?: string }
       }
 
+      // `persist: true` keys by the calc name; `{ key }` overrides. The driver
+      // (de)serializes through the calc's own `output` schema.
+      const persist =
+        cfg.persist === undefined || cfg.persist === false
+          ? undefined
+          : {
+              key:
+                cfg.persist === true ? calc.manifest.name : cfg.persist.key ?? calc.manifest.name,
+              schema: calc.manifest.output,
+            }
+
       // The hidden revision store, read requirement-free (`serviceOption`): the
       // assembly below always provides it alongside this driver, and feeding it
       // through `extraKey` (not `wireSources`) keeps it out of the snapshot —
@@ -236,6 +258,7 @@ export function live<
         disabled: cfg.disabled,
         coalesce: cfg.coalesce,
         reuse: cfg.reuse,
+        persist,
         extraKey:
           revision === undefined
             ? undefined
@@ -265,3 +288,24 @@ export function live<
     Layer.provide(State.live(revisionState, revisionZero)),
   )
 }
+
+/**
+ * Mark a query's value stale (`isStale := true`) — without fetching. A stale
+ * query with active readers (a mounted view) refetches; an unread one refetches
+ * when next subscribed. The imperative counterpart of `invalidateOn`, and what a
+ * focus/online provider layer calls. A no-op if the calc isn't live; resolves the
+ * `Queries` registry (part of `Engine`).
+ */
+export const invalidate = (calc: { readonly name: string }): Effect.Effect<void, never, Queries> =>
+  Effect.flatMap(Queries, (queries) =>
+    Effect.sync(() => queries.byName.get(calc.name)?.invalidate()),
+  )
+
+/**
+ * Force an immediate refetch of the current key, bypassing the no-op-key guard
+ * and independent of `isStale`. A no-op if the calc isn't live or is disabled.
+ */
+export const refetch = (calc: { readonly name: string }): Effect.Effect<void, never, Queries> =>
+  Effect.flatMap(Queries, (queries) =>
+    Effect.sync(() => queries.byName.get(calc.name)?.refetch()),
+  )

package/src/calc/queryState.ts

@@ -0,0 +1,52 @@
+import { Option } from 'effect'
+import { type AnyAsyncData, AsyncData } from './asyncData'
+
+// `QueryState` is the data-oriented value an `AsyncCalc` is driven by: the four
+// axes of a query, stored *flat and independent* so each can move on its own.
+// `data`/`error` survive a refetch (stale-while-revalidate for free); `isFetching`
+// (activity) and `isStale` (freshness) are orthogonal to both — which is exactly
+// what lets `invalidate` (flip `isStale`) and `refetch` (drive `isFetching`) be
+// separate operations. The matchable `AsyncData` union is *derived* from this
+// (`toAsyncData`), so view code and `RemoteState` keep their arm dispatch.
+
+export interface QueryState<A, E> {
+  /** Last resolved value — kept across a refetch. */
+  readonly data: Option.Option<A>
+  /** Last failure — kept across a refetch. */
+  readonly error: Option.Option<E>
+  /** Activity axis: a run is in flight. */
+  readonly isFetching: boolean
+  /** Freshness axis: the value has been marked invalid (drives auto-refetch). */
+  readonly isStale: boolean
+}
+
+/** The empty cell. `fetching` seeds the first-kick `Loading` for an enabled query. */
+export const empty = (fetching: boolean): QueryState<never, never> => ({
+  data: Option.none(),
+  error: Option.none(),
+  isFetching: fetching,
+  isStale: false,
+})
+
+/**
+ * Project the flat state onto the public `AsyncData` union (the view contract) —
+ * the single `Match`-able view of a query, so call sites keep `Match.tag`-ing the
+ * arms. `error` wins over `data` so a failed refetch surfaces the `Error` arm,
+ * matching the pre-`QueryState` driver; `isFetching` becomes the arm's
+ * `refetching` flag. The data-less case is `Loading` while fetching (or for a
+ * non-gated query, which always fetches) and `Idle` only for a switched-off
+ * gateable query.
+ */
+export const toAsyncData = <A, E>(s: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> =>
+  Option.match(s.error, {
+    onSome: (error) => AsyncData.error(error, s.isFetching),
+    onNone: () =>
+      Option.match(s.data, {
+        onSome: (value) => AsyncData.success(value, s.isFetching),
+        onNone: () => (s.isFetching || !gated ? AsyncData.loading : AsyncData.idle),
+      }),
+  })
+
+/** `Loading` in the React-Query sense: fetching with nothing to show yet. */
+export const isLoading = <A, E>(s: QueryState<A, E>): boolean =>
+  s.isFetching && Option.isNone(s.data)

package/src/index.ts

@@ -31,6 +31,23 @@ export {
   type AsyncLoading,
   type AsyncSuccess,
 } from './calc/asyncData'
+// The flat, data-oriented query value (`data`/`error`/`isFetching`/`isStale`) an
+// `AsyncCalc` is driven by; `toAsyncData` projects it onto the matchable arms.
+export { isLoading, type QueryState, toAsyncData } from './calc/queryState'
+// Optional host seams an `AsyncCalc` consults — persistence and lifecycle signals.
+// Concrete implementations live in edge packages (e.g. `@playfast/reform-query-browser`).
+export {
+  noopQueryStore,
+  QueryStore,
+  type QueryStoreApi,
+  resolveQueryStore,
+} from './internal/queryStore'
+export {
+  noopQueryEvents,
+  QueryEvents,
+  type QueryEventsApi,
+  resolveQueryEvents,
+} from './internal/queryEvents'
 export * as RemoteState from './remote/remoteState'
 // Direct type re-exports alongside the namespace (TS2742 nameability): an app
 // layer's inferred type references these (`Store<ReadonlyArray<PendingIntent<…>>>`),
@@ -146,10 +163,14 @@ export { type SlotChild } from './compose/slot'
 // A scene bundles a composition with the closed wiring that runs it — the single
 // handle the react host, proofs, and the dev tool all consume.
 export { isScene, type MountedServices, type Scene, scene, seedScene } from './scene/scene'
+export type { SeedsOf } from './state/stateGroup'
 
 // Runtime surface for hosts (`@reform/react`) and headless tests.
 export { Bus, type Envelope, type Priority, publish, type Tagged } from './runtime/bus'
 export { Engine, type ReducerEntry, Reducers } from './runtime/loop'
+// The runtime-wide registry of live query handles. `AsyncCalc.invalidate` /
+// `AsyncCalc.refetch` and provider layers act on a query by name through it.
+export { Queries, type QueryHandle, type QueryRegistry } from './runtime/queries'
 export {
   type ChannelClass,
   type ChannelPolicy,

package/src/internal/queryDriver.ts

@@ -10,8 +10,11 @@ import {
   type Scope,
   Stream,
 } from 'effect'
-import { type AnyAsyncData, AsyncData } from '../calc/asyncData'
+import { type AnyAsyncData } from '../calc/asyncData'
+import { empty, type QueryState, toAsyncData } from '../calc/queryState'
+import { Queries, type QueryHandle } from '../runtime/queries'
 import { reuse } from './reuse'
+import { resolveQueryStore } from './queryStore'
 import { resolveScheduler } from './scheduler'
 import {
   type InputsObject,
@@ -20,14 +23,17 @@ import {
   sameKey,
   wireSources,
 } from './sources'
-import { makeStore, type Store } from './store'
+import { makeDerivedStore, 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), fold the
-// result into an `AnyAsyncData` store with stale-while-revalidate semantics.
-// Extracted so both primitives run the exact same machinery — the asyncCalc
-// test suite is the driver's regression suite.
+// 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
@@ -52,7 +58,7 @@ export const revisionZero: Revision = Revision(0)
 export const bumpRevision = (r: Revision): Revision => Revision(r + 1)
 
 export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A, E, R> {
-  /** The owning definition's name — only for the defect log line. */
+  /** 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
@@ -75,6 +81,13 @@ export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A,
         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.
+   */
+  readonly persist?: { readonly key: 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
@@ -85,7 +98,7 @@ export interface QueryDriverOptions<Inputs extends ReadonlyArray<AnySource>, A,
 }
 
 export interface QueryDriver<A, E> {
-  /** The lifecycle store (the full union — callers narrow to their arms). */
+  /** 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).
@@ -97,12 +110,13 @@ export interface QueryDriver<A, E> {
 }
 
 /**
- * Build the driver: store + 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 `Success`/`Error` is kept with
- * `refetching: true`.
+ * 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).
  */
 export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R>(
   options: QueryDriverOptions<Inputs, A, E, R>,
@@ -111,6 +125,8 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
     const scheduler = yield* resolveScheduler
     const sources = yield* wireSources(options.inputs, options.invalidateBy)
     const extraKey = options.extraKey
+    const persist = options.persist
+    const queryStore = yield* resolveQueryStore
 
     const keyOf = (args: InputsObject<Inputs>): ReadonlyArray<unknown> =>
       extraKey === undefined ? sources.keyOf(args) : [...sources.keyOf(args), extraKey.read()]
@@ -125,74 +141,128 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
     const disabledNow = (args: InputsObject<Inputs> = sources.snapshot()): boolean =>
       options.gated && options.disabled !== undefined ? options.disabled(args) : false
 
-    const store = makeStore<AnyAsyncData<A, E>>(
-      disabledNow() ? AsyncData.idle : AsyncData.loading,
-      scheduler,
-    )
-    // The last requested key, so a change that doesn't move it (or only churns
-    // an input `invalidateBy` ignores) doesn't re-fetch.
+    // 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)
-    // The run-generation counter: bumped when a run is REQUESTED (enqueued), so
-    // `requested()` names the newest run that could possibly be in flight.
     const generation = MutableRef.make(0)
     const nextGeneration = (): number => {
       MutableRef.update(generation, (n) => n + 1)
       return MutableRef.get(generation)
     }
 
-    // Mark a re-fetch in flight without dropping the visible value (SWR).
-    const markRefetching = () => {
-      const prev = store.get()
-      if (prev._tag === 'Success') store.set(AsyncData.success(prev.value, true))
-      else if (prev._tag === 'Error') store.set(AsyncData.error(prev.error, true))
-      else store.set(AsyncData.loading)
+    // ── 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 markFetching = () => {
+      const s = stateStore.get()
+      if (!s.isFetching) stateStore.set({ ...s, isFetching: true })
+    }
+    const settleSuccess = (value: A): A => {
+      const prev = stateStore.get()
+      const shared =
+        options.reuse === true && Option.isSome(prev.data) ? reuse(prev.data.value, value) : value
+      stateStore.set({
+        data: Option.some(shared),
+        error: Option.none(),
+        isFetching: false,
+        isStale: false,
+      })
+      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 })
     }
 
-    // One run of the query, folded into the store. A failure becomes `Error`; an
-    // interrupt (latest-wins cancel) leaves the state untouched; a defect (a bug
-    // in the body) is logged and isolated — the driver keeps running. A `Success`
-    // additionally reports its generation through `onSettled`, after the write,
-    // so settle-driven consequences observe the converged value.
+    const persistWrite = (value: A): Effect.Effect<void> =>
+      persist === undefined
+        ? Effect.void
+        : Schema.encode(persist.schema)(value).pipe(
+            Effect.flatMap((encoded) => queryStore.set(persist.key, encoded)),
+            // Persistence is best-effort: a serialization or storage failure must
+            // never fail the run nor block the visible write.
+            Effect.ignore,
+          )
+
+    // 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)
+    yield* Effect.addFinalizer(() => Effect.sync(derived.unsubscribe))
+
+    interface Request {
+      readonly args: InputsObject<Inputs>
+      readonly generation: number
+    }
+
+    // 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.tapDefect((defect) =>
           Effect.logError(`reform: ${options.label} '${options.name}' query defect`, defect),
         ),
         Effect.matchCause({
-          onSuccess: (value) => {
-            if (!disabledNow()) {
-              // `reuse`: share unchanged subtrees with the previous Success
-              // value, so a refetch that barely moved keeps identities stable.
-              const prev = store.get()
-              const shared =
-                options.reuse === true && prev._tag === 'Success'
-                  ? reuse(prev.value, value)
-                  : value
-              store.set(AsyncData.success(shared, false))
-              options.onSettled?.(request.generation)
-            }
-          },
-          onFailure: (cause) => {
+          onSuccess: (value): Option.Option<A> => Option.some(value),
+          onFailure: (cause): Option.Option<A> => {
             const failure = Cause.failureOption(cause)
-            if (Option.isSome(failure) && !disabledNow()) {
-              store.set(AsyncData.error(failure.value, false))
-            }
+            if (Option.isSome(failure) && !disabledNow()) settleError(failure.value)
+            return Option.none()
           },
         }),
+        Effect.flatMap((ok) =>
+          Option.match(ok, {
+            onNone: () => Effect.void,
+            onSome: (value) =>
+              disabledNow()
+                ? Effect.void
+                : Effect.suspend(() => {
+                    const shared = settleSuccess(value)
+                    options.onSettled?.(request.generation)
+                    return persistWrite(shared)
+                  }),
+          }),
+        ),
       )
 
-    interface Request {
-      readonly args: InputsObject<Inputs>
-      readonly generation: number
-    }
-
-    // The driver. `'switch'` (default): each new request cancels the in-flight
-    // run — the same latest-wins semantics a `latest` channel gives procedures.
+    // 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. The trailing
-    // run's generation is the max drained (the latest request's), so it
-    // vouches for every request it conflated.
+    // 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>()
     yield* Effect.forkScoped(
@@ -202,14 +272,9 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
               const first = yield* Queue.take(requests)
               const queued = yield* Queue.takeAll(requests)
               const request = Option.getOrElse(Chunk.last(queued), () => first)
-              // A disable that landed while the request waited: skip the run.
               if (!disabledNow()) yield* runQuery(request)
-              // The settle may have written a stale-key result with
-              // `refetching: false`; if a newer request is already waiting,
-              // restore the syncing flag before the next take — both writes
-              // coalesce into one scheduler flush for subscribers.
               const pending = yield* Queue.size(requests)
-              if (pending > 0 && !disabledNow()) yield* Effect.sync(markRefetching)
+              if (pending > 0 && !disabledNow()) yield* Effect.sync(markFetching)
             }),
           )
         : Stream.fromQueue(requests).pipe(
@@ -218,30 +283,103 @@ export const makeQueryDriver = <Inputs extends ReadonlyArray<AnySource>, A, E, R
           ),
     )
 
-    const trigger = () => {
+    // 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)
-        store.set(AsyncData.idle)
+        stateStore.set(idle)
         return
       }
       const key = keyOf(args)
       const previous = MutableRef.get(lastKey)
-      if (previous !== undefined && sameKey(key, previous)) return
+      if (!force && previous !== undefined && sameKey(key, previous)) return
       MutableRef.set(lastKey, key)
-      markRefetching()
+      markFetching()
       Queue.unsafeOffer(requests, { args, generation: nextGeneration() })
     }
+    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()
+    }
+    const invalidate = () => {
+      const s = stateStore.get()
+      if (s.isStale) return
+      stateStore.set({ ...s, isStale: true })
+      maybeAutoRefetch()
+    }
+
     const unsubscribe = subscribeAll(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 cached = yield* queryStore.get(persist.key)
+      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: (value) =>
+                stateStore.set({
+                  data: Option.some(value),
+                  error: Option.none(),
+                  isFetching: false,
+                  isStale: true,
+                }),
+            }),
+          ),
+      })
+    }
+
     // Kick off the first fetch unless the query starts disabled.
     const initial = sources.snapshot()
     if (!disabledNow(initial)) {
       MutableRef.set(lastKey, keyOf(initial))
+      markFetching()
       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, (n) => Math.max(0, n - 1))
+        }
+      },
+    }
+
+    // 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,
+      refetch,
+      snapshot: () => stateStore.getSnapshot(),
+      subscribe: (listener) => stateStore.subscribe(listener),
+    }
+    const queries = Option.getOrUndefined(yield* Effect.serviceOption(Queries))
+    if (queries !== undefined) {
+      queries.register(handle)
+      yield* Effect.addFinalizer(() => Effect.sync(() => queries.unregister(handle)))
+    }
+
     return { store, requested: () => MutableRef.get(generation) }
   })

package/src/internal/queryEvents.ts

@@ -0,0 +1,34 @@
+import { Context, Effect, Option } from 'effect'
+
+// `QueryEvents` is the optional host-signal seam invalidation *sources* subscribe
+// to — window focus/visibility and network reconnect. It carries no DOM itself:
+// the concrete `window.addEventListener` implementation lives in an edge package
+// (`@playfast/reform-query-browser`); core only declares the shape. Resolved via
+// `serviceOption` with a no-op fallback, so its absence (SSR, native, proofs) is
+// inert. The subscriptions return an unsubscribe thunk — the synchronous,
+// React-facing shape the rest of reform uses (see `Store.subscribe`).
+
+export interface QueryEventsApi {
+  /** Fires when the window/tab regains focus or visibility. */
+  readonly subscribeFocus: (listener: () => void) => () => void
+  /** Fires when the network comes back online. */
+  readonly subscribeOnline: (listener: () => void) => () => void
+}
+
+const QueryEventsBase: Context.TagClass<QueryEvents, 'reform/QueryEvents', QueryEventsApi> =
+  Context.Tag('reform/QueryEvents')<QueryEvents, QueryEventsApi>()
+export class QueryEvents extends QueryEventsBase {}
+
+const noop = (): (() => void) => () => {}
+
+/** A source that never fires — the fallback when no host provides `QueryEvents`. */
+export const noopQueryEvents: QueryEventsApi = {
+  subscribeFocus: noop,
+  subscribeOnline: noop,
+}
+
+/** Resolve the host's `QueryEvents`, or the no-op source when none is in context. */
+export const resolveQueryEvents: Effect.Effect<QueryEventsApi> = Effect.map(
+  Effect.serviceOption(QueryEvents),
+  Option.getOrElse(() => noopQueryEvents),
+)

package/src/internal/queryStore.ts

@@ -0,0 +1,36 @@
+import { Context, Effect, Option } from 'effect'
+
+// `QueryStore` is the optional persistence seam an `AsyncCalc` writes through and
+// hydrates from — a key→value cache provided by the host (localStorage,
+// IndexedDB, AsyncStorage, …). Like `Notifications`, it is resolved through
+// `serviceOption`, so a calc that opts into `persist` imposes NO hard requirement:
+// absent host ⇒ the no-op store ⇒ the feature is simply inert (SSR, native,
+// proofs). Values cross the boundary as `unknown` and are (de)serialized through
+// the calc's own `output` schema by the driver, never trusted structurally.
+
+export interface QueryStoreApi {
+  readonly get: (key: string) => Effect.Effect<Option.Option<unknown>>
+  readonly set: (key: string, value: unknown) => Effect.Effect<void>
+  readonly remove: (key: string) => Effect.Effect<void>
+}
+
+const QueryStoreBase: Context.TagClass<QueryStore, 'reform/QueryStore', QueryStoreApi> =
+  Context.Tag('reform/QueryStore')<QueryStore, QueryStoreApi>()
+export class QueryStore extends QueryStoreBase {}
+
+/** A store that persists nothing — the fallback when no host provides `QueryStore`. */
+export const noopQueryStore: QueryStoreApi = {
+  get: () => Effect.succeedNone,
+  set: () => Effect.void,
+  remove: () => Effect.void,
+}
+
+/**
+ * Resolve the host's `QueryStore`, or the no-op store when none is in context.
+ * `serviceOption` keeps it requirement-free — a calc wired as a sibling of the
+ * runtime that provides no persistence simply gets the inert store.
+ */
+export const resolveQueryStore: Effect.Effect<QueryStoreApi> = Effect.map(
+  Effect.serviceOption(QueryStore),
+  Option.getOrElse(() => noopQueryStore),
+)

package/src/runtime/loop.ts

@@ -7,6 +7,7 @@ import {
 } from '../channel/channel'
 import { notificationsLayer } from '../internal/scheduler'
 import { Bus, busLayer, type Envelope, type Tagged } from './bus'
+import { Queries, queriesLayer } from './queries'
 
 /**
  * A registered reducer, with its target store(s) already captured at
@@ -162,10 +163,16 @@ const drain = Effect.gen(function* () {
  * drain loop. Registration mutates the live collections, so reducers/procedures/
  * channels merged alongside are picked up before the first dispatch (boot).
  */
-export const Engine: Layer.Layer<Bus | Reducers | Channels | Procedures> = Layer.scopedDiscard(
-  drain,
-).pipe(
-  Layer.provideMerge(
-    Layer.mergeAll(busLayer, reducersLayer, channelsLayer, proceduresLayer, notificationsLayer),
-  ),
-)
+export const Engine: Layer.Layer<Bus | Reducers | Channels | Procedures | Queries> =
+  Layer.scopedDiscard(drain).pipe(
+    Layer.provideMerge(
+      Layer.mergeAll(
+        busLayer,
+        reducersLayer,
+        channelsLayer,
+        proceduresLayer,
+        notificationsLayer,
+        queriesLayer,
+      ),
+    ),
+  )

package/src/runtime/queries.ts

@@ -0,0 +1,53 @@
+import { Context, Layer } from 'effect'
+import { type QueryState } from '../calc/queryState'
+
+// The `Queries` registry: the runtime-wide index of live query handles, the same
+// shape as `Reducers`/`Channels`/`Procedures` (`loop.ts`, `channel.ts`). Each
+// `AsyncCalc.live` driver registers its handle here scoped — so `AsyncCalc.invalidate`
+// / `AsyncCalc.refetch` (and any provider layer) can act on a calc by name without
+// holding its store tag. A base in-memory registry ships in `Engine`; provider
+// layers (persistence, focus/online managers) build on top by calling the handles.
+//
+// The per-calc generics are erased through function signatures (reads are
+// covariant; `subscribe` is uniform), so the heterogeneous registry needs no cast.
+
+export interface QueryHandle {
+  readonly name: string
+  /** Mark the query's value stale (`isStale := true`). Does not fetch. */
+  readonly invalidate: () => void
+  /** Force a run of the current key, bypassing the no-op-key guard. */
+  readonly refetch: () => void
+  /** Read the current state (erased to the open value type). */
+  readonly snapshot: () => QueryState<unknown, unknown>
+  /** Subscribe to state changes; returns an unsubscribe thunk. */
+  readonly subscribe: (listener: () => void) => () => void
+}
+
+export interface QueryRegistry {
+  readonly byName: Map<string, QueryHandle>
+  readonly register: (handle: QueryHandle) => void
+  readonly unregister: (handle: QueryHandle) => void
+}
+
+const QueriesBase: Context.TagClass<Queries, 'reform/Queries', QueryRegistry> = Context.Tag(
+  'reform/Queries',
+)<Queries, QueryRegistry>()
+export class Queries extends QueriesBase {}
+
+const makeQueryRegistry = (): QueryRegistry => {
+  const byName = new Map<string, QueryHandle>()
+  return {
+    byName,
+    register: (handle) => {
+      byName.set(handle.name, handle)
+    },
+    // Only drop the entry if it is still the one we registered: a same-named
+    // re-registration (re-mount before the old scope's finalizer runs) must not
+    // be clobbered by the stale handle's unregister.
+    unregister: (handle) => {
+      if (byName.get(handle.name) === handle) byName.delete(handle.name)
+    },
+  }
+}
+
+export const queriesLayer: Layer.Layer<Queries> = Layer.sync(Queries, makeQueryRegistry)