foldkit-remote 0.6.0 → 0.8.0

package/README.md

@@ -1,30 +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) }),
+})
+
+RemoteData.render(project, {
+  loading: () => ProjectSkeleton(),
+  notFound: () => NoSuchProject(),
+  failed: error => ErrorView(error),
+  data: project => ProjectView(project),
+})
+```
 
-The central rule is:
+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.
 
-> **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.**
+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
+
+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 | [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 | [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 |
 | --- | --- |
@@ -33,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.
 
@@ -67,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 |
 | --- | --- |
@@ -78,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
 
@@ -89,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
 
-Start with one server entity and one selection:
+Six steps take a project's name from a server to a screen. Each says what it
+does, and what it deliberately does not.
+
+### 1. Declare an entity and what this screen needs of it
 
 ```ts
 import { Schema } from 'effect'
@@ -114,14 +192,13 @@ const ProjectSummary = Entity.select(Project, {
 ```
 
 The entity comes from [`foldkit-entity`](../entity), which declares a domain
-without Remote in it. Remote also has an `Entity.make` of its own, and accepts
-either — but only a `foldkit-entity` entity has addressable `fields`, so only
-that one can be given [relations](#entities-declared-with-foldkit-entity),
-derived members, or a [query body](#queries-and-pagination). Reach for
-`Entity.make` when a domain is small enough that Remote is all it will ever
-need; reach for `Entity.define` otherwise, which is most of the time.
+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. 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'
@@ -144,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,
@@ -168,16 +236,33 @@ const App = Surface.application({
 })
 
 const Data = Remote.make({
-  model: App.fields.remote,
+  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', {
@@ -192,15 +277,16 @@ 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 * 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 }
@@ -212,9 +298,36 @@ 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.
+
+### 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'
 
-The complete loop is:
+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
@@ -241,28 +354,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.
+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).
+
+## Routing Remote's Messages
 
-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 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.
+
+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
-const clientLayer = Remote.clientLayer(rpcClient)
+const Message = defineMessageUnion({ ...Remote.messages })
+
+function update(model: Model, message: Message): Update.Return<Model, Message, RemoteClient> {
+  if (Remote.reduces(message)) return { model: Data.reduce(model, message) }
+  return { model }
+}
 ```
 
-`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 rest of this guide uses the fold. With the spread, read `Data.subscriptions`
+for `foldData.subscriptions` and `Data.fetch` for `foldData.fetch`.
 
-## 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'
@@ -321,14 +445,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.
 
@@ -337,6 +463,9 @@ 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 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.
 
@@ -380,6 +509,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
@@ -507,6 +732,16 @@ 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.
 
+**Time reaches Remote only as a Message.** The plan is a function of the Model
+and `now`, and it runs when the Model 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:
 
 ```ts
@@ -525,24 +760,6 @@ 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.
-
-```ts
-const previewed = Data.overlay(model, 'post-preview', [Project.patch(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.
-
 To revalidate what a screen already declares — a refresh button, a focus
 regained — hand its Projection (or a Surface without params) to `Data.refresh`:
 
@@ -568,6 +785,31 @@ nothing observes, use `Data.prefetch` with `RemotePolicy.networkOnly`.
 - 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
@@ -584,7 +826,7 @@ const ProjectsByOwner = Query.make('ProjectsByOwner', {
 })
 
 const Data = Remote.make({
-  model: App.fields.remote,
+  model: App.model.remote,
   entities: [User, Project],
   queries: [ProjectsByOwner],
 })
@@ -735,6 +977,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
@@ -756,13 +1007,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 }) }),
 })
 ```
 
@@ -820,6 +1071,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:
@@ -844,7 +1130,7 @@ case 'ClickedRename': {
     RenameProject,
     { id, name },
     {
-      optimistic: [Project.patch(id, { name })],
+      optimistic: [Remote.patch(Project, id, { name })],
     },
   )
 
@@ -858,6 +1144,12 @@ case 'ClickedRename': {
 2. it returns the Command that calls `RemoteClient` and eventually emits
    `MutationSucceeded` or `MutationFailed`.
 
+`Remote.patch(entity, id, values)` builds one entity's patch, and
+`Remote.ref(entity, id)` names one row. Both take the entity you declared,
+whether with `foldkit-entity` or Remote's `Entity.make`, and check `values`
+against its fields in their wire shape: a relation is written as its ref key,
+such as `'User:u1'`.
+
 Those settlement Messages go through `Data.reduce` like every other Remote fact.
 The request id comes from the Remote Model's sequence, so `update` stays pure.
 Settling is idempotent per `requestId`.
@@ -885,10 +1177,10 @@ import { ConnectionChange } from 'foldkit-remote'
 
 const { model: started, command } = Data.mutate(model, AddComment, input, {
   optimistic: ({ tempId }) => [
-    Comment.patch(tempId, { id: tempId, body: input.body }),
+    Remote.patch(Comment, tempId, { id: tempId, body: input.body }),
     ConnectionChange.prepend(
       CommentsForPost.ref({ postId }),
-      Comment.ref(tempId),
+      Remote.ref(Comment, tempId),
     ),
   ],
 })
@@ -897,6 +1189,24 @@ 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.
+
 ### Reading past what is only pending
 
 Every projection reads the **visible** cache: the server-derived store under
@@ -934,24 +1244,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.
+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
 
@@ -1005,8 +1303,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 },
@@ -1041,6 +1340,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
@@ -1087,22 +1420,6 @@ See [`foldkit-remote-server`](../remote-server) for Source and authorization
 rules, and [`examples/kitchen-sink`](../../examples/kitchen-sink) for the real
 server packages together.
 
-## Finding the next API
-
-| Task | Start here |
-| --- | --- |
-| Explain `Initial`, `Loading`, or a stale value | [`RemoteData`](#remotedata-what-does-the-model-know-right-now) |
-| Fetch outside an active screen | [Policies and prefetch](#reading-policies-and-prefetch) |
-| Load an ordered list | [Queries and pagination](#queries-and-pagination) |
-| Save and show an optimistic result | [Mutations](#mutations-and-optimistic-state) |
-| Release data no active feature needs | [Retention](#retention-and-garbage-collection) |
-| Seed a cache after reload or SSR | [Hydration](#persistence-and-hydration) |
-
-A successful mutation and an optimistic overlay have different guarantees:
-the overlay is only a temporary view of server-owned data. Use Sync when the
-operation itself must survive offline, rather than persisting an optimistic
-Remote cache and treating it as an outbox.
-
 ## Introspection
 
 Remote exposes its decisions as data rather than requiring DevTools to reach
@@ -1116,10 +1433,9 @@ 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.
+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,
@@ -1193,6 +1509,11 @@ place in an application Model. It exposes the Remote `Model`, `initial`,
 `Remote.at(definition, modelRef)` binds that domain to a `ModelRef`;
 `Remote.make` combines definition and binding in one step.
 
+`Entity.make(name, schema)` is Remote's own entity descriptor, and what a
+`foldkit-entity` Entity is compiled to (`Entity.from`). Remote accepts either
+wherever it takes an entity. Declaring one directly skips `foldkit-entity`,
+and with it relations, derived members and query bodies, which is only worth
+it for a domain that Remote is all it will ever need.
 `Selection.make(Entity, { ... })`, `Selection.connection(...)`, and
 `Entity.patch(ref, values)` are the kernel constructors behind the entity
 helpers. `Remote.select(bound, selection)(id)` is the lower-level form of
@@ -1347,15 +1668,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.