foldkit-remote 0.7.0 → 0.9.0

package/README.md

@@ -1,50 +1,109 @@
 # `foldkit-remote`
 
-Server-owned data, cached **inside the Foldkit Model**.
+Server data, cached inside the Foldkit Model. A screen says what it needs;
+the view gets what the cache knows.
 
-A feature declares the server facts it needs. `foldkit-remote` compares those
-requirements with what the Model already knows, fetches only what is missing or
-stale, normalizes the result so every consumer shares one copy, and returns new
-facts to the application as ordinary Messages.
+```ts
+const ProjectPage = App.surface('ProjectPage', {
+  params: { projectId: Schema.String },
+  model: ({ params }) => ({ project: Data.get(ProjectSummary, params.projectId) }),
+})
 
-The central rule is:
+RemoteData.render(project, {
+  loading: () => ProjectSkeleton(),
+  notFound: () => NoSuchProject(),
+  failed: error => ErrorView(error),
+  data: project => ProjectView(project),
+})
+```
 
-> **A Remote Projection does not fetch. It declares what server-owned facts a
-> consumer requires. I/O happens outside render, and its results reduce back into
-> the Model.**
+No fetch call, no cache object, no loading flag. While the page is active,
+Remote fetches only the fields the Model lacks, stores each entity once, and
+hands the view one of six states rather than an `undefined`. Every result is a
+Message through one reducer, so a screen replays from a recorded Model.
+
+Remote is for facts the **server owns**. An edit the client authors, which
+must survive being offline, belongs to [`foldkit-sync`](../sync).
 
-There is no hidden mutable cache beside the application. A read result, query
-page, mutation result, live event, hydration, and retention change all become
-Remote Messages and move the same Model through one pure reducer.
+## If you know TanStack Query, TanStack DB or fate
 
-Use Remote when the **server owns the truth** and the client needs a normalized,
-disposable view of it. If an edit is client-authored and must survive offline,
-restart, or network failure until it converges, that belongs to
-[`foldkit-sync`](../sync) and [`foldkit-durable`](../durable), not Remote.
+The same job, done from the other side of the Model:
+
+| TanStack Query | `foldkit-remote` |
+| --- | --- |
+| `useQuery({ queryKey, queryFn })` in a component | `Data.get(Selection, id)` in a Surface; the active Surface fetches |
+| a `queryKey` you design | the entity, its id and the fields selected; there is no key to design |
+| one cache entry per key | one entity per id, shared by every selection of it |
+| `staleTime`, `refetchOnWindowFocus` | `RemotePolicy`, `Data.refresh` from `update` |
+| `gcTime` | retention: what no active Surface reaches is collected |
+| `onMutate` + `setQueryData` | `optimistic: [Remote.patch(...)]`, a layer the settlement removes |
+| `invalidateQueries` | not needed for overlap: a result updates the one copy |
+| `isPending`, `isError`, `data` | `RemoteData`: six states, one exhaustive fold |
+| a `QueryClient` beside your state | `Remote.Model`, a field of your Model, changed only by Messages |
+
+Two differences change how you build. **There are no keys.** A TanStack cache
+is a map from keys you design to results you shape, so two components that
+want overlapping data either share a key and over-fetch, or hold two copies
+and invalidate by hand. Remote stores fields by entity and id, and a Surface
+declares which fields it selects, so overlap is the normal case and a
+mutation's result is seen everywhere at once. **The cache is Model.** A
+`QueryClient` lives beside your state and is updated by effects; `Remote.Model`
+is a field of your Model, changed by the same reducer as everything else, so a
+screen is a function of the Model, replays from a recording, and is tested
+without a network.
+
+What Remote does not have: a component hook (it has Surfaces and Foldkit
+Subscriptions), a devtools panel of its own (`Data.inspect` and `Data.why` are
+the data one would show), and retries on failure (a failed read stays failed
+until something asks again; see [When a read fails](#when-a-read-fails)).
+
+### And TanStack DB, and fate
+
+[TanStack DB](https://tanstack.com/db) is a local database: collections
+populated eagerly (or on demand) from a REST API or a sync engine, live queries
+that update incrementally, and optimistic transactions rolled back on failure.
+Its unit is the collection; a screen queries what is already local. Remote's
+unit is the field: a screen declares which fields of which entities it reads,
+and only those are fetched, so there is no collection to load first and a page
+carries what it shows. Remote has no live query engine: `Data.filtered` and
+`Remote.matching` judge the rows a list already holds, and a new list is a
+server query. Where TanStack DB syncs client-authored writes through a sync
+engine, that job here belongs to [`foldkit-sync`](../sync), and Remote stays
+the disposable cache of what the server owns.
+
+[fate](https://fate.technology) is the nearest cousin: components declare
+views of exactly the data they need, composed into one request per screen,
+with a normalized cache that masks what a component did not ask for, and
+actions with optimistic rollback. Remote's Selections are that strictness, and
+its store is that cache. The differences are where it lives and what runs it:
+fate is a React data client, driven by Suspense and Actions; Remote is a
+Submodel of a Foldkit Model, driven by which Surfaces are active, with no view
+framework in it.
 
 ## Find what you need
 
-This README is long because it covers everything Remote does. Read the
-[sixty-second example](#sixty-seconds-one-entity-one-surface) first, then jump
-to what you are doing:
+Read the [first run](#the-first-run-one-entity-one-surface) once, then jump to
+what you are doing:
 
 | Task | Start here |
 | --- | --- |
-| See it work before there is a server | [A backend held in memory](../remote-server/README.md#a-backend-held-in-memory) |
-| Understand `Initial`, `Loading`, or a stale value | [`RemoteData`](#remotedata-what-does-the-model-know-right-now) |
-| Find out why a read stays `Initial` | [`Data.why`](#remotedata-what-does-the-model-know-right-now) |
+| See it work before there is a server | [Step 5](#5-provide-a-client) |
+| A read stays `Initial` | [Why is it still `Initial`?](#why-is-it-still-initial) |
+| A list shows old rows | [Why is it stale?](#why-is-it-stale) |
+| A saved change showed, then vanished | [Why did my change disappear?](#why-did-my-change-disappear) |
+| Data was gone when I came back | [Why is it gone?](#why-is-it-gone-after-navigating-away) |
 | Show a failed read, and let the user retry | [When a read fails](#when-a-read-fails) |
 | Load an ordered, paged list | [Queries and pagination](#queries-and-pagination) |
 | Filter a list already on screen | [Filtering a loaded list](#filtering-a-loaded-list-without-asking-the-server) |
 | Save, and show the result before the server answers | [Mutations](#mutations-and-optimistic-state) |
 | Fetch outside an active screen | [Policies and prefetch](#reading-policies-and-prefetch) |
-| Keep data across a reload, or seed it from SSR | [Hydration](#persistence-and-hydration) |
-| Release data no active feature needs | [Retention](#retention-and-garbage-collection) |
+| Keep data across a reload | [Hydration](#persistence-and-hydration) |
+| Hand a server render's data to the browser | [Server rendering](#server-rendering-remoteresume) |
 | Answer the requests on the server | [How the server packages fit](#how-the-server-packages-fit) |
 
 ## Which state belongs here?
 
-A useful rule across Foldkit Plus is **one owner per datum**:
+One owner per datum:
 
 | State | Owner |
 | --- | --- |
@@ -53,23 +112,13 @@ A useful rule across Foldkit Plus is **one owner per datum**:
 | Client-authored state that must survive offline and converge | `foldkit-sync` |
 | Local state represented in the URL or another store | the Model, observed by `foldkit-mirror` |
 
-The distinction between Remote and Sync is especially important:
-
 ```text
-Remote
-  server owns the fact
-  cache is disposable
-  refetch is recovery
-
-Sync
-  client owns the edit
-  intent must survive offline/restart
-  replay + reconciliation is recovery
+Remote                              Sync
+  server owns the fact                client owns the edit
+  cache is disposable                 intent must survive offline/restart
+  refetch is recovery                 replay + reconciliation is recovery
 ```
 
-A Remote mutation is therefore an immediate request against server-owned data.
-Its result updates the cache. It is **not** a durable local intent queue.
-
 A Surface may project all of these owners at once. Observation does not transfer
 ownership.
 
@@ -87,9 +136,11 @@ requirements with the cache, then requests missing or stale fields. The
 result returns as a Message; only reducing it changes what the next read sees.
 Rendering the same Projection twice starts no work by itself.
 
-## Four pieces to remember
+> **A Remote Projection does not fetch. It declares what server-owned facts a
+> consumer requires. I/O happens outside render, and its results reduce back into
+> the Model.**
 
-Most application code only needs four roles:
+Four roles carry the loop, and most application code needs no more:
 
 | Piece | Responsibility |
 | --- | --- |
@@ -98,7 +149,11 @@ Most application code only needs four roles:
 | `Data.reduce` | reduce returned Remote Messages into the application's `Remote.Model` |
 | `RemoteClient` | perform the actual read/query/mutate/live I/O |
 
-Everything else builds on those four pieces.
+One rule keeps the cache coherent: **`Data.reduce` is the only writer.** Local
+application state changes with `modifyFields` inside `update`, like anywhere
+else; a server fact only enters the cache as a Remote Message. Never install
+cache state with a ref `set`: requirements, staleness and tombstones stay
+consistent only because every fact arrives through the reducer.
 
 ## Install
 
@@ -109,9 +164,12 @@ pnpm add foldkit-remote foldkit-entity
 `foldkit` and `effect` are peer dependencies; `foldkit-surface` comes with the
 package. The server-side interpreter is [`foldkit-remote-server`](../remote-server).
 
-## Sixty seconds: one entity, one Surface
+## The first run: one entity, one Surface
+
+Six steps take a project's name from a server to a screen. Each says what it
+does, and what it deliberately does not.
 
-Start with one server entity and one selection:
+### 1. Declare an entity and what this screen needs of it
 
 ```ts
 import { Schema } from 'effect'
@@ -137,9 +195,10 @@ The entity comes from [`foldkit-entity`](../entity), which declares a domain
 without Remote in it, so the same declaration can serve the server's database
 binding and your forms too. It is also what gives an entity
 [relations](#entities-declared-with-foldkit-entity), derived members, and a
-[query body](#queries-and-pagination) to point at.
+[query body](#queries-and-pagination) to point at. Nothing here touches a
+network.
 
-Embed Remote's Submodel in the application and bind the domain to that field:
+### 2. Give Remote a place in the Model, and route its Messages
 
 ```ts
 import { defineMessageUnion } from 'foldkit/message'
@@ -162,19 +221,10 @@ const Model = Schema.Struct({
 type Model = typeof Model.Type
 
 const Message = defineMessageUnion({
-  ...Remote.messages,
+  GotRemoteMessage: { message: Remote.Message },
 })
 type Message = typeof Message.Type
 
-function update(
-  model: Model,
-  message: Message,
-): Update.Return<Model, Message, RemoteClient> {
-  // Remote owns the `remote` Submodel, so all Remote Messages go through its reducer.
-  if (Remote.reduces(message)) return { model: Data.reduce(model, message) }
-  return { model }
-}
-
 const App = Surface.application({
   Model,
   Message,
@@ -189,13 +239,30 @@ const Data = Remote.make({
   model: App.model.remote,
   entities: [Project],
 })
+
+// Remote under one variant of the union, the shape Foldkit gives a Submodel.
+const foldData = Remote.fold(Data, message => Message.GotRemoteMessage({ message }))
+
+function update(
+  model: Model,
+  message: Message,
+): Update.Return<Model, Message, RemoteClient> {
+  return Message.match(message, {
+    // Remote owns the `remote` Submodel: everything it says goes through its reducer.
+    GotRemoteMessage: ({ message }) => foldData(model, message),
+  })
+}
 ```
 
-`Remote.Model` is not a second application store. It is a Submodel **inside** the
-application Model. `Data` is the bound API for this domain: it knows where that
-Submodel lives and which descriptors this application registered.
+`Remote.Model` is not a second store. It is a Submodel **inside** the
+application Model, and `Data` is the bound API for this domain: it knows where
+that Submodel lives and which entities this application registered. `update`
+matches the union exhaustively; Remote's own Messages arrive inside
+`GotRemoteMessage` and go straight to Remote's reducer. (There is a shorter
+form for an `update` that only reduces; see
+[Routing Remote's Messages](#routing-remotes-messages).)
 
-Now declare what a feature needs:
+### 3. Declare what the screen reads
 
 ```ts
 const ProjectPage = App.surface('ProjectPage', {
@@ -210,19 +277,21 @@ const ProjectPage = App.surface('ProjectPage', {
 ```
 
 `ProjectPage` reads a `RemoteData<{ id: string; name: string }>` from the Model.
-If those fields are absent, the Projection still does not fetch them.
+If those fields are absent, the Projection still does not fetch them: it says
+what it needs, and something else decides whether to ask.
 
-The active Surface drives I/O through a Foldkit Subscription:
+### 4. Let the active screen drive the fetching
 
 ```ts
+import { Option } from 'effect'
 import * as Subscription from 'foldkit/subscription'
 
 const subscriptions = Subscription.make<Model, Message, RemoteClient>()(() =>
-  Data.subscriptions({
+  foldData.subscriptions({
     project: Surface.at(ProjectPage, model =>
       model.route._tag === 'project'
-        ? { projectId: model.route.projectId }
-        : undefined,
+        ? Option.some({ projectId: model.route.projectId })
+        : Option.none(),
     ),
   }),
 )
@@ -230,9 +299,51 @@ const subscriptions = Subscription.make<Model, Message, RemoteClient>()(() =>
 
 `Surface.at` makes activation a fact of the Model. When the route activates the
 page, Remote sees its requirements, diffs them against the cache, and fetches
-only what is missing. When the page is inactive, it creates no read work.
+only what is missing. When the page is inactive, it creates no read work. This
+is the one step that causes I/O, and it does so only while the screen is on.
+
+A read that is not a Surface's, such as the record a detail pane shows, is made
+active with `Data.active`: its function of the Model returns the read, or none
+while there is nothing to read.
+
+```ts
+const detail = Data.active('ProjectDetail', model =>
+  Option.map(model.openProjectId, id => Data.get(Project.select({ name: true }), id)),
+)
+foldData.subscriptions({ detail })
+```
+
+It belongs to the domain's application and sends no Messages. A domain bound
+to a raw optic (`ModelRef.fromOptic`) names no application, so `Data.active`
+throws for one rather than guess.
 
-The complete loop is:
+### 5. Provide a client
+
+The Subscription needs a `RemoteClient`. Before there is a server, a backend
+held in memory answers through the same handlers a real one uses:
+
+```ts
+import { RemoteServer } from 'foldkit-remote-server'
+
+const clientLayer = RemoteServer.memory({
+  domain: Data,
+  rows: { Project: [{ id: 'p1', name: 'Apollo', status: 'active' }] },
+}).layer
+```
+
+With a server, adapt your configured Effect RPC client instead; the
+[server guide](../remote-server/README.md) supplies the other side:
+
+```ts
+const clientLayer = Remote.clientLayer(rpcClient)
+```
+
+Either is a Layer the runtime provides to `subscriptions` and Commands. The
+transport itself is not owned by Remote. See
+[`RemoteServer.memory`](../remote-server/README.md#a-backend-held-in-memory)
+for what the in-memory one can and cannot do.
+
+### 6. Watch it arrive
 
 ```text
 ProjectPage Projection
@@ -259,43 +370,39 @@ Remote.Model
 ProjectPage now reads Ready(...)
 ```
 
-The first example starts on the `home` route, so no project read runs yet.
-Your route update must activate `{ _tag: 'project', projectId: 'p1' }`, and the
-runtime must install `subscriptions`. Expect `Initial` until work starts,
-`Loading` during the first request, and `Ready` once its result is reduced.
-
-Finally, provide the client implementation to the runtime. Here `rpcClient`
-is your configured Effect RPC client, not a value created by the declarations
-above; the [server guide](../remote-server/README.md) supplies the other side:
+The first run starts on the `home` route, so no project read runs yet. Your
+route update must activate `{ _tag: 'project', projectId: 'p1' }`, and the
+runtime must install `subscriptions`. The page then reads `Initial` until work
+starts, `Loading` during the first request, and `Ready` once its result is
+reduced. If it stays `Initial`, see [Why is it still `Initial`?](#why-is-it-still-initial).
 
-```ts
-const clientLayer = Remote.clientLayer(rpcClient)
-```
+## Routing Remote's Messages
 
-`Remote.clientLayer` adapts an Effect RPC client for `RemoteRpc` into the
-`RemoteClient` service used by subscriptions and Commands. The transport itself
-is not owned by Remote.
+The first run folds Remote's Messages under one variant of the application's
+union, the shape Foldkit gives a Submodel. The fold's `fetch`, `mutate`, and
+`subscriptions` yield that variant too, with the lift recorded so a Story
+resolves a fetch or a mutation by Remote's own answer.
 
-To see the page work before you have a server, give it rows instead. A backend
-held in memory answers through the same handlers a real server uses:
+The shorter path, for an `update` that only reduces, spreads Remote's cases
+into the union and narrows by tag; the rest of `update` is then a partial
+match over tags the application never handles:
 
 ```ts
-import { RemoteServer } from 'foldkit-remote-server'
+const Message = defineMessageUnion({ ...Remote.messages })
 
-const clientLayer = RemoteServer.memory({
-  domain: Data,
-  rows: { Project: [{ id: 'p1', name: 'Apollo', status: 'active' }] },
-}).layer
+function update(model: Model, message: Message): Update.Return<Model, Message, RemoteClient> {
+  if (Remote.reduces(message)) return { model: Data.reduce(model, message) }
+  return { model }
+}
 ```
 
-It is for a first run, a test or a demo. See
-[`RemoteServer.memory`](../remote-server/README.md#a-backend-held-in-memory).
+The rest of this guide uses the fold. With the spread, read `Data.subscriptions`
+for `foldData.subscriptions` and `Data.mutate` for `foldData.mutate`.
 
-## One list per application with `Data.wiring`
+### One value with `foldkit-bundle`: `Data.wiring`
 
-The integration steps above — spread `Remote.messages`, reduce by tag, derive
-`Data.subscriptions`, provide the client — are one value when the application
-uses `foldkit-bundle`:
+The integration steps above — fold or reduce, derive the Subscriptions,
+provide the client — are one value when the application uses `foldkit-bundle`:
 
 ```ts
 import { Bundle } from 'foldkit-bundle'
@@ -304,7 +411,9 @@ const Page = Bundle.parent({ Model, Message })
 const wiring = Page.assemble(
   Data.wiring({
     project: Surface.at(ProjectPage, model =>
-      model.route._tag === 'project' ? { projectId: model.route.projectId } : undefined,
+      model.route._tag === 'project'
+        ? Option.some({ projectId: model.route.projectId })
+        : Option.none(),
     ),
   }),
 )
@@ -354,14 +463,16 @@ The states are:
   flight.
 - **`Ready`** — every selected field is present and decodes.
 - **`Refreshing`** — the current value remains visible while it is being refetched.
-- **`Failed`** — stored server data does not decode against the Selection, or
-  the read or query behind it failed. A value that was already shown is kept as
-  `previous`.
+- **`Failed`** — stored server data does not decode against the Selection, the
+  read or query behind it failed, or the server settled a selected field
+  without a value (an `Unavailable` error; see
+  [When a field is withheld](#when-a-field-is-withheld)). A value that was
+  already shown is kept as `previous`.
 - **`NotFound`** — the entity is represented by a tombstone: a live event
-  deleted it, or the server was asked for it by id and answered without it. That
-  id is then known absent, whether it never existed, is gone, or is not this
-  principal's to see. It is not planned again until `Data.refresh` forces it or a
-  write brings it back. The target of a returned ref is not marked this way: a
+  deleted it, or the server was asked for it by id and answered with nothing
+  about it. That id is then known absent, whether it never existed, is gone, or
+  is hidden whole from this principal. It is not planned again until
+  `Data.refresh` forces it or a write brings it back. The target of a returned ref is not marked this way: a
   server need not expand a relation that rides on a request, and the planner asks
   for such a target by id next, which is when its absence is learned.
 
@@ -370,20 +481,8 @@ no active Surface may remain `Initial` forever. Rendering a spinner for
 `Initial` can therefore hide an activation/wiring mistake; `Loading` is the
 state that actually means "wait for this request."
 
-When a read sits at `Initial` and you expected data, ask the Model why:
-
-```ts
-Data.why(model, projection, { surfaces }) // the record you give Data.subscriptions
-// { state: 'Initial', reason: 'NotFetching', surfaces: ['ProjectPage'],
-//   message: 'ProjectPage reads it and is active, yet nothing is fetching it. …' }
-```
-
-`NotObserved` means no active Surface reads it: the Surface is not in the
-record, or its params are `undefined` for this Model. `NotFetching` means one
-does, and nothing started a request, which almost always means Remote's
-Subscriptions are not installed in the runtime. Without `surfaces` it can only
-say `Unknown`. For every other state it says what the state means in words,
-and a failed request's message says that nothing retries it on its own.
+When a read sits at `Initial` and you expected data, ask the Model why with
+`Data.why`; see [Why is it still `Initial`?](#why-is-it-still-initial).
 
 `RemoteData.match` is exhaustive, so adding or omitting a state is visible at
 compile time.
@@ -428,6 +527,102 @@ spinner that never ends or an error nobody can act on.
 Reach for `match` instead when the six states really do draw differently — it
 stays the exhaustive fold, and `render` does not replace it.
 
+## When it does not do what you expect
+
+Each of these is a design of the package showing through, not a fault. The
+symptom names the section; the cure is one call.
+
+### Why is it still `Initial`?
+
+`Initial` means required data is absent and **nothing is fetching it**, so a
+spinner here hides a wiring mistake. Ask the Model:
+
+```ts
+Data.why(model, projection, { surfaces }) // the record you give Data.subscriptions
+// { state: 'Initial', reason: 'NotFetching', surfaces: ['ProjectPage'],
+//   message: 'ProjectPage reads it and is active, yet nothing is fetching it. …' }
+```
+
+- `NotObserved`: no active Surface reads it. The Surface is not in the record
+  you gave `Data.subscriptions`, or its params are `undefined` for this Model
+  (the route is not there yet).
+- `NotFetching`: an active Surface reads it and nothing started a request,
+  which almost always means Remote's Subscriptions are not installed in the
+  runtime.
+- Without `surfaces` it can only say `Unknown`. For every other state it says
+  what the state means in words.
+
+`Data.plan(model, projection)` shows whether Remote believes anything is
+missing at all.
+
+### Why is it stale?
+
+Under the default `RemotePolicy.cacheFirst`, a present field is never asked for
+again. That is the point of a cache, and the reason a list shows what the
+server said last time. To see change:
+
+- **On demand**: `Data.refresh(model, projection)` from `update` marks what the
+  screen reads `Refreshing` and the active Subscription fetches it again, old
+  value still on screen. A refresh button, a window regaining focus.
+- **By age**: `RemotePolicy.staleWhileRevalidate({ maxAge })` refetches a value
+  older than `maxAge` the next time it is planned.
+- **Always**: `RemotePolicy.networkOnly` requests every selected field, cached
+  value visible meanwhile.
+- **As it happens**: `Data.live` instead of `Data.get`, with a server that
+  publishes changes; see [Live data](#live-data).
+
+Connections have no age: a list re-queries when invalidated, refreshed, or
+under `networkOnly`. See [Reading, policies, and prefetch](#reading-policies-and-prefetch).
+
+### Why did my change disappear?
+
+A mutation's `optimistic` patches are layers over the store while the request
+is in flight. When the server answers, the layers come off and the cache shows
+what the server said:
+
+- **It failed.** `MutationFailed` removes the layers; `Data.mutation(model,
+  requestId)` reads `Failed` with the error. Nothing retries it: the mutation
+  is not a durable queue, and if losing it is data loss the edit belongs to
+  [`foldkit-sync`](../sync).
+- **It succeeded, but the server's result did not include the field.** The
+  layer came off and the store still holds the old value, until a read or the
+  result writes the new one. A mutation `Output` that returns the changed
+  entity settles this at once.
+- **A preview** shown with `Data.overlay` stays until `Data.lift`; a settled
+  mutation never takes it along.
+
+See [Mutations and optimistic state](#mutations-and-optimistic-state).
+
+### Why is it gone after navigating away?
+
+Remote is a cache, and it forgets facts no active feature needs. Retention
+roots come from the active Surfaces; after the grace period, `RetentionChanged`
+collects everything they do not reach. A screen you left, and nothing else
+reads, loses its rows, which is safe because coming back refetches them. To
+keep something a screen does not read, name it in a retain entry or a
+`connections` list; see [Retention](#retention-and-garbage-collection).
+
+### Why does a value the server has read `Failed`?
+
+`Failed` with no `previous` and no request error means the stored value did not
+**decode** against the Selection: the server's shape and the entity's Schema
+disagree; the error is a `DecodeError` with the Schema's message. An
+`Unavailable` error means the server answered without a field the Selection
+names and will not answer with it; see
+[When a field is withheld](#when-a-field-is-withheld). A failed request reads
+the same way, with the request's error; see
+[When a read fails](#when-a-read-fails). A
+`RemoteProtocolError` means the client and server disagree on
+`REMOTE_PROTOCOL_VERSION`, and nothing is silently accepted.
+
+### Why did a live update not show?
+
+Live events carry cursors. One behind the Model's is a duplicate and is
+dropped; one ahead of the next is a **gap**, recorded in `RemoteModel.gaps`
+and not applied, so the screen keeps what the server last said rather than
+a history with a hole in it. The host resynchronizes and clears the gap; see
+[Live data](#live-data).
+
 ## Normalized entities and selections
 
 Remote stores an entity once by identity, regardless of how many Surfaces read
@@ -553,7 +748,49 @@ What Remote should do when the Model already contains the selected fields is a
 
 A refreshing policy emits `RefreshStarted` before the read, so the Projection
 becomes `Refreshing` without discarding the old value. Planning accepts `now`
-(default `Date.now`) as an input, so tests can control time.
+as an input, so tests can control time. It defaults to `Date.now`, read at each
+use, so fake timers (`vi.useFakeTimers`) move it; Effect's `TestClock` does not,
+because a plan runs outside Effect, so a test that drives `TestClock` passes
+`now`. A mutation's answer is dated the same way, by `Data.mutate`'s `now`
+option.
+
+A policy belongs to one `subscriptions` call, and covers every read in it. Reads
+under different policies take a call each:
+
+```ts
+const projectPage = Surface.at(ProjectPage, model =>
+  model.route._tag === 'project' ? Option.some({ projectId: model.route.projectId }) : Option.none(),
+)
+const owner = Data.active('Owner', () => Option.some(Data.get(UserSummary, 'u1')))
+
+const pageEntries = Data.subscriptions({ page: projectPage })
+// Retention is the domain's: one `retain` roots every read, so the second
+// call's is left out rather than spread over the first's.
+const { retain: _domainRetain, ...ownerEntries } = Data.subscriptions(
+  { owner },
+  { policy: RemotePolicy.staleWhileRevalidate({ maxAge: 5_000 }) },
+)
+
+const subscriptions = Subscription.make<Model, Message, RemoteClient>()(() => ({
+  ...pageEntries,
+  ...ownerEntries,
+}))
+```
+
+Retention stays the domain's: a call's `retain` entry roots every read any call
+of the domain names, so neither call collects what the other reads. Keeping one
+`retain` entry is all it takes; it waits for its own call's `grace`.
+
+**Time reaches Remote only as a Message.** The plan is a function of the Remote
+model, what is asked, and `now`, and it runs again only when one of those
+changes; a page that sits still past its
+`maxAge` would otherwise never be looked at again. So a read entry under
+`staleWhileRevalidate` knows when the earliest value it holds ages out, sleeps
+until then under the Effect clock, and emits `RefreshStarted` for what is due.
+That marks the fields stale in the Model, and the plan that follows fetches
+them, the same path a refresh button takes. Nothing reads the clock while a
+Projection is read, so a Model reads the same twice, and a recorded one
+replays.
 
 For SSR, route prefetch, hover prefetch, and tests, run the same plan explicitly:
 
@@ -571,25 +808,25 @@ const loaded = await Effect.runPromise(
 Remote Messages reduced into it. It never changes the semantics of the
 Projection itself.
 
-### Refreshing from `update`
-
-### Showing a change nobody has made
-
-A mutation's `optimistic` operations show over the store while it is in flight.
-`Data.overlay` shows operations the same way with no request behind them, until
-`Data.lift`: a preview, in every Selection and view, of something not yet sent.
+A render that fetches nothing (SSR, a prerender) needs everything a page's
+active Surfaces read, and one read can decide what another asks for: a page's
+Blocks are known once its document is. `Data.satisfy` prefetches every active
+Surface, cache-first, pass after pass until a pass plans nothing:
 
 ```ts
-const previewed = Data.overlay(model, 'post-preview', [Remote.patch(Project, id, { name: draft })])
-const back = Data.lift(previewed, 'post-preview')
+const ready = await Effect.runPromise(
+  Data.satisfy(model, actives).pipe(Effect.provide(clientLayer)),
+)
 ```
 
-- Both are called from `update`, and neither performs I/O or touches what the
-  server said: the store beneath is as it was.
-- Showing an id again replaces what it showed. Lifting what was never shown
-  returns the same Model.
-- An overlay's id is apart from every request's, so a mutation that settles does
-  not take a preview with it.
+`actives` is the record `Data.wiring` takes. The passes are bounded (8 by
+default, `{ passes }` to change it); a Surface still reading after the last
+fails the Effect with `RemoteUnsatisfied`, which names it, rather than
+rendering it loading. A read the server leaves unanswered settles as missing,
+so it ends the loop; what runs out the passes is a chain whose every read
+reveals one more.
+
+### Refreshing from `update`
 
 To revalidate what a screen already declares — a refresh button, a focus
 regained — hand its Projection (or a Surface without params) to `Data.refresh`:
@@ -610,12 +847,37 @@ since stale data is planned again under every policy, so the page is requested
 once. The Projection must be observed, as it is while it is on screen; for data
 nothing observes, use `Data.prefetch` with `RemotePolicy.networkOnly`.
 
-- A refreshed connection's first page replaces its loaded pages, so items the
-  server removed or reordered follow it; later pages are fetched again with
-  `Data.next`.
+- A refreshed connection is asked for again as one page the size of the widest
+  window reading it (including what "load more" grew), which replaces what it
+  held, so items the server removed or reordered follow it.
 - A read already in flight restarts instead of landing after the refresh.
 - Refreshing what is already refreshing, or nothing, returns the same Model.
 
+### Forgetting everything: a change of principal
+
+Everything Remote knows, it knows for a principal: a value the server gave
+this session, a tombstone for an id it answered nothing about, a field it
+settled as unavailable, the rows of a list. Log in, log out, switch
+organization, and none of it is trustworthy. `Data.forget` is the one
+boundary:
+
+```ts
+case 'SignedOut': {
+  return { model: Data.forget({ ...model, session: Option.none() }) }
+}
+```
+
+It performs no I/O and returns the Model with every server-derived fact gone:
+values, tombstones, unavailable fields, connections, live cursors, failures,
+and the reads in flight. Every active Surface's read and live entries restart,
+so the screen asks again as whoever the client now is; a read or stream begun
+before is interrupted rather than landing after. A mutation in flight is
+treated as applied, so its answer writes nothing into the new store, and the
+mutation sequence is kept, so request ids stay unique.
+
+Who the client is belongs to the `RemoteClient` layer or the server's session,
+not to Remote. `forget` only says that what was known no longer is.
+
 ## Queries and pagination
 
 Entities answer "which fields of this known thing?" A Query answers "which
@@ -694,11 +956,10 @@ const projects = Data.query(
 )
 
 projects.read(model)
-// RemoteData<Page<ProjectSummary>>
+// RemoteData<Page<ProjectSummary>>: at most 25 items
 
-Data.next(model, projects)      // QueryRef | undefined
-Data.previous(model, projects)  // QueryRef | undefined
-Data.fetch(ref)                 // Command whose Message merges the page
+Data.more(model, projects)
+// Option<Model>: "load more", the window grown to 50; none when all are shown
 ```
 
 The connection stores entity references and explicit boundaries rather than one
@@ -707,13 +968,32 @@ Remote represents an honest gap instead of pretending the visible rows are
 adjacent.
 
 A query Projection is `Initial` until the page **and every selected field of its
-visible items** are present. Once a page lands, those items become ordinary
-entity requirements and can be fulfilled in the same planning loop.
-
-Two Projections of the same connection plan one query and select the union of
-their required fields. `Data.next` / `Data.previous` preserve the page size and
-use the loaded boundaries; `hasNext` / `hasPrevious` come from those boundaries,
-not from guessing based on row counts.
+visible items** are present. The `select` travels with the query: the server
+returns the selected fields of the page's items with the edges, and one
+`ConnectionMerged` merges the page and writes them, so a fresh list usually
+lands `Ready` in one response. What the server leaves out (withheld fields,
+nested targets it does not expand) becomes ordinary entity requirements and
+is fetched next, as before; a server that predates payloads sends edges only
+and the list reads the old two-round-trip way.
+
+**A read shows at most its window.** Remote keeps one connection per query and
+input, whatever window asks for it, so a picker's `first: 50` and a card's
+`first: 3` of the same query share the rows, and each read is cut to its own
+window: `first` from the start, `last` from the end. `hasNext` / `hasPrevious`
+are true when the read cut rows or the connection's boundary says there are
+more; they are never guessed from a row count.
+
+Two Projections of the same connection plan one query, for the wider window,
+and select the union of their fields. When a connection holds fewer rows than a
+window asks for, the read entry asks only for the rows it lacks, after the
+loaded end (or before the loaded start).
+
+**"Load more" grows the window.** `Data.more(model, projection)` is the Model
+with that read's window one page larger, called from `update`; the read entry
+then fetches what the connection lacks. It is kept in Remote's store, under the
+query, input and window first asked for, so a list holds no state of its own,
+and it is forgotten when retention drops the connection. Another window of the
+same query does not grow with it.
 
 ### Filtering a loaded list without asking the server
 
@@ -783,6 +1063,15 @@ the binding's `visible` rule; there is no `visible` here. This is safe only
 because the client holds only rows the server already released to it, and a
 local filter is not an access decision.
 
+**Local execution is not a second authority.** `matching` and `filtered` derive
+conclusions from facts the server gave; they never promote those conclusions
+into knowledge of the server's whole dataset. Knowing `p1.ownerId = u7` says
+that `p1` matches `ProjectsByOwner(u7)`; it does not say that
+`ProjectsByOwner(u7)` is `[p1]`, and nothing here will say so unless a
+connection's boundaries, terminal at both ends, independently prove it. That
+line is what keeps Remote a cache of what the server owns rather than a local
+database with opinions of its own.
+
 ### An input that changes as fast as someone types
 
 A connection's identity is its query plus its **input**, which is exactly right
@@ -804,13 +1093,13 @@ the query reads** — which is ordinary application state, and
 import { debounce } from 'foldkit-primitives/time'
 
 const SearchInput = debounce({ name: 'PostSearch', value: Schema.String })
-const SearchBox = Bundle.declare(SearchInput, 'search')
 
 // `latest` is what the box shows, so typing stays immediate.
 // The settled OutMessage is what moves the field the query reads.
-Page.at(SearchBox, {
+// A step of the page's Bundle.compose(...).pipe(...):
+Bundle.withChild('search', SearchInput, {
   args: { delayMs: 250 },
-  onOut: out => model => ({ model: evo(model, { postSearch: () => out.value }) }),
+  onOut: out => model => ({ model: modifyFields(model, { postSearch: () => out.value }) }),
 })
 ```
 
@@ -868,6 +1157,41 @@ A broken live stream is not a failed read. Its `ReadFailed` carries the
 field: nothing was being read, and the values on screen are still what the
 server last said.
 
+### When a field is withheld
+
+A server may answer a read without a field it was asked for, and mean it: the
+Source's `authorize` withheld it from this principal, or the record it returned
+had no such field. The read result says so, in `settled`: the fields it asked
+for that this answer does not carry and a later one would not either. Why is
+not on the wire. The client records each as **unavailable**, one more kind of
+knowledge beside a value and a tombstone:
+
+```text
+missing      not established; the planner asks
+present      known
+stale        known, and being asked again
+unavailable  asked, and answered without: the planner does not ask again
+tombstone    the whole entity is known absent
+```
+
+A Selection that names an unavailable field reads `Failed` with an
+`Unavailable` error naming the field, not `Loading` (nothing is fetching it)
+and not `NotFound` (the entity is there). What it is not is a seventh state:
+the remedy is the one a failed read has. Select without the field, in a
+Selection of its own if some principals may read it, or show the error. A
+Selection that does not name it is unaffected: `name` reads `Ready` while
+`privateNotes` is unavailable beside it.
+
+The mark is forgotten by what forgets a failure: `Data.refresh` asks again,
+and a read, live patch or mutation result that writes the field clears it.
+It survives persistence and a server render's `Remote.resume`, so the browser
+does not ask once more for what the server already declined.
+
+An id the server answers with nothing about, neither values nor settled fields,
+is a tombstone as before. A server settles a withheld field without reading
+its Source for an id whose every field is withheld, so an absent id and a
+hidden one answer alike, and existence is not told.
+
 ## Mutations and optimistic state
 
 Register mutations on the domain:
@@ -951,6 +1275,29 @@ const { model: started, command } = Data.mutate(model, AddComment, input, {
 A successful server result can replace the request's temporary connection
 overlays with confirmed ones in place.
 
+### Showing a change nobody has made
+
+A mutation's `optimistic` operations show over the store while it is in flight.
+`Data.overlay` shows operations the same way with no request behind them, until
+`Data.lift`: a preview, in every Selection and view, of something not yet sent.
+
+```ts
+const previewed = Data.overlay(model, 'post-preview', [Remote.patch(Project, id, { name: draft })])
+const back = Data.lift(previewed, 'post-preview')
+```
+
+- Both are called from `update`, and neither performs I/O or touches what the
+  server said: the store beneath is as it was.
+- Showing an id again replaces what it showed. Lifting what was never shown
+  returns the same Model.
+- An overlay's id is apart from every request's, so a mutation that settles does
+  not take a preview with it.
+- A preview of an entity the server has not seen, such as an unsaved post, has
+  only the fields the overlay holds. A Selection that reads more reads
+  `Failed`, with an `Overlaid` error naming what is missing, since nothing will
+  fetch it. Overlay every field the Selection reads, or preview through a
+  smaller Selection.
+
 ### Reading past what is only pending
 
 Every projection reads the **visible** cache: the server-derived store under
@@ -988,25 +1335,12 @@ flight](../../docs/state-model.md#what-a-reader-sees-while-a-change-is-in-flight
 
 ### Remote mutation vs Sync operation
 
-Do not use Remote mutation as a durable offline-write mechanism:
-
-```text
-Remote mutation
-  request server now
-  server owns truth
-  result updates disposable cache
-  no durable outbox
-
-Sync operation
-  client authored the durable fact/intent
-  survives offline/restart
-  enters an ordered log
-  converges with other replicas
-```
-
-If losing an unsent edit would be data loss, it belongs to Sync rather than
-Remote. For the same reason, an optimistic overlay is only a temporary view of
-server-owned data: do not persist one and treat it as a queue of edits.
+A Remote mutation requests the server now; its result updates a disposable
+cache, and there is no durable outbox. If losing an unsent edit would be data
+loss, it belongs to [`foldkit-sync`](../sync), not here (see [which state
+belongs here](#which-state-belongs-here)). For the same reason, an optimistic
+overlay is only a temporary view of server-owned data: do not persist one and
+treat it as a queue of edits.
 
 ## Live data
 
@@ -1033,8 +1367,9 @@ failure Message rather than mutating anything out of band.
 Remote is a cache, so it should be allowed to forget facts no active feature
 needs.
 
-`Data.subscriptions` derives retention roots from the active Surfaces. A root
-keeps:
+`Data.subscriptions` derives retention roots from the active Surfaces of every
+call on the domain, so a call's `retain` entry never collects what another call
+reads; `connections` given to any call are kept the same way. A root keeps:
 
 - the entities and fields its Projection requires;
 - referenced targets reached by nested selections;
@@ -1060,8 +1395,9 @@ never in one.
 ```ts
 import { RemotePersistence } from 'foldkit-remote'
 
-// SSR: prefetch on the server, embed, then hydrate on the client.
-// `snapshotOf` names the connections that survive; none, here.
+// A cache carried in the page: prefetch on the server, embed, then hydrate.
+// `snapshotOf` names the connections that survive; none, here. For a page
+// the browser resumes with foldkit-ssr, see Server rendering below.
 const text = RemotePersistence.dehydrate(
   RemotePersistence.snapshotOf(loaded.remote),
   { scope: userId },
@@ -1096,6 +1432,40 @@ snapshot from another version/scope, an oversized snapshot, or malformed data is
 discarded and the planner refetches. `Hydrated` is itself a Remote Message, so
 hydration still changes the application through the reducer.
 
+## Server rendering: `Remote.resume`
+
+A snapshot is built for a cache that survived a reload: it keeps the whole
+entity store and deliberately no cursors. A page rendered a moment ago wants
+the opposite. `Remote.resume(Data)` is a resume part for
+[`foldkit-ssr`](../ssr/README.md) (in development), which sends exactly what
+the page's active Surfaces read, and resumes it in the browser:
+
+```ts
+const Page = SSR.plan(App, {
+  id: 'project',
+  state: Projection.pick(App.model.route),
+  surfaces: [ProjectPageAt],
+  parts: [Remote.resume(Data)],
+})
+```
+
+- **Only what is read crosses.** For each requirement, the fields it names,
+  following its relations through the refs the store holds; for each
+  connection, the fields its selection reads of each item. A field in the
+  server's store that no Surface selects, such as a user's email, is not in the
+  page.
+- **Connections cross whole**, with their boundaries, so "load more" knows
+  where the server stopped.
+- **Live cursors cross with the entities they follow**, so a live
+  subscription started in the browser asks from where the server's left off.
+- **Nothing else crosses.** Loading marks, failures, the mutation ledger,
+  optimistic layers, gaps and retention start at their initial values.
+
+The browser's read entry plans against the restored store, so it asks for
+none of it again. The capture is JSON through its own Schema, and a page whose
+capture does not decode is refused whole by `foldkit-ssr`. Give a second domain
+in one application its own `id`: `Remote.resume(Catalog, { id: 'catalog' })`.
+
 ## How the server packages fit
 
 `foldkit-remote` owns **client cache semantics**, not your source database or
@@ -1150,15 +1520,20 @@ into private state:
 ```ts
 Data.inspect(model)            // serializable cache/domain summary
 Data.plan(model, projection)   // the entity plan a read would execute
+Data.meta(model, projection)   // when what is shown was received, stale/loading
 Data.explain(model, query)     // what one query read is, and currently is
 Remote.planQueries(...)        // missing/stale query work
 Remote.inspectEntity(...)      // one normalized entity
 ```
 
-These are pure and useful in tests, tooling, and debugging. A particularly
-useful question is: **"Why is this Projection still Initial?"** `Data.plan`
-shows whether Remote believes anything is actually missing; active Surface
-wiring determines whether that plan is being executed.
+`Data.meta` is for views, not debugging: `updatedAt` is the newest server
+write among what the projection shows (`undefined` when nothing shown was
+received), with `stale` and `loading` beside it, so "updated 5s ago" reads
+the Model like any other render.
+
+These are pure and useful in tests, tooling, and debugging. For a read that
+stays `Initial`, `Data.why` and `Data.plan` are the tools; see
+[Why is it still `Initial`?](#why-is-it-still-initial).
 
 `Data.inspect(model).loading` answers the other one — **"what is Remote doing
 right now?"** — with the `entity\0id\0field` marks of the reads in flight,
@@ -1262,8 +1637,16 @@ requirements for the concrete target.
 options.
 
 `Remote.storeOf` is the visible store after pending optimistic layers. Reads are
-memoized per visible store (and connection where applicable), so equal reads of
-one Model state assemble/decode once and return one value.
+memoized per visible store (and, for a list, its connection and overlays), so
+equal reads of one Model state assemble/decode once and return one value.
+
+Across Model states, an entity's or row's decoded value stays the same object
+while its entity's fields are equal: a refetch or live patch that brought equal
+data hands the view the value it already rendered, so a keyed row's lazy view
+does not re-run. A write to any field of the entity, even one the row does not
+select, or a pending optimistic patch on it while other writes land, gives the
+row a new value. When the store changed, the `RemoteData` around a value and a
+page's `items` array are new.
 
 `Remote.prefetch(bound, model, projection, options?)` runs the same plans
 imperatively and reduces their results into a new Model.
@@ -1272,7 +1655,10 @@ imperatively and reduces their results into a new Model.
 
 `updateRemote(remote, message)` is the pure reducer over Remote facts;
 `Data.update` applies it to a bound Remote state and `Data.reduce` applies it to
-the application Model.
+the application Model. The common Messages that change nothing (a duplicate live
+event, a repeated `ReadStarted`, an empty `Hydrated`, a retention pass that
+collects nothing) return the Model they were given, so Foldkit neither renders
+nor recomputes Subscription dependencies.
 
 Its Messages cover reads and refreshes, mutations, live events/gaps, query
 connections, retention, and hydration. `Remote.messages` is the case record for
@@ -1297,21 +1683,30 @@ Remote.retain(projections, toMessage?, { connections?, grace? })
   active roots -> RetentionChanged
 ```
 
-The observe entry's dependencies are the current plan and the Model's refresh
-generation (`{ requirements, queries, refresh }`), so `Data.refresh` restarts
+The observe entry's dependencies are the current plan, the Model's refresh
+generation, and when a held value next ages out
+(`{ requirements, queries, refresh, expires }`), so `Data.refresh` restarts
 it. If entity requirements and queries are both empty, it performs no I/O. A
 refreshing read emits `RefreshStarted` first, then a result Message.
 
-Every emitted Message changes the Model, so Foldkit recomputes Subscription
+A Message that changes the Model makes Foldkit recompute Subscription
 dependencies. For example, after a query page lands, the next computation sees
 the page's entity ids and plans any selected fields those entities still lack.
 An interrupted identical read is joined by the client coalescer instead of
 needlessly restarted.
 
+The live entry's dependencies are what the Surface reads live, the refresh
+floor, and the stream's cursor. The stream stays open as events advance the
+cursor; the cursor is only where a stream restarted for another reason resumes.
+
 Retention uses the Projection requirements/connections as roots and eventually
 emits `RetentionChanged`; the reducer's pure `gc` keeps everything reachable
 from those roots plus pending work and collects the rest.
 
+The entries `Data.subscriptions` returns carry these dependencies in their
+types: `ReadDependencies` for `<key>.read`, `LiveDependencies` for
+`<key>.live`, and `RetentionRoots` for `retain`.
+
 ### Connections by hand
 
 A connection stores entity references in segments with explicit boundaries, so
@@ -1340,7 +1735,7 @@ them.
 
 ### Mutations by hand
 
-`Remote.mutateInto(bound, model, mutation, input, requestId, { optimistic })` is
+`Remote.mutateInto(bound, model, mutation, input, requestId, { optimistic, now })` is
 the one-step imperative start/run/settle form for SSR and tests.
 
 `Remote.mutate(mutation, input, requestId)` is the transport call itself. It
@@ -1348,7 +1743,10 @@ decodes the typed `Output` and returns normalized entity patches and confirmed
 connection changes for a caller to reduce through `updateRemote`.
 
 `MutationSucceeded` reconciles at most once per `requestId`; an unknown or
-already-applied settlement is a no-op.
+already-applied settlement is a no-op. It carries `now`, the clock reading of
+the answer, which dates the entities it writes as a read's `now` does, so a
+freshness policy ages them from then. `Data.mutate` and `Remote.mutateInto`
+stamp it from their `now` option, `Date.now` by default.
 
 ### The transport seam
 
@@ -1391,15 +1789,6 @@ Remote does **not** own:
 - authentication; server-side authorization belongs at the Source boundary;
 - a background scheduler or general-purpose database/query engine.
 
-## How state changes here
-
-Local application state uses `evo` inside `update`, like anywhere else.
-Remote Messages go through `Data.reduce` into the embedded `Remote.Model`
-submodel — Remote owns that reducer, and it is the only writer of the
-cache. Never install cache state with a ref `set`; the requirements,
-staleness, and tombstones only stay coherent when every fact arrives as a
-Remote Message.
-
 ## Limits
 
 - Effect RPC is the wire contract; the application supplies deployment layers.