foldkit-remote 0.20.0 → 0.22.0

package/README.md

@@ -22,8 +22,10 @@ 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).
+Remote is for facts the **server owns**. A write that must reach the server
+even if the page goes first is a durable write, which Remote's outbox sends
+later. An edit the client authors, which must converge with other devices'
+edits while offline, belongs to [`foldkit-sync`](../sync).
 
 ## If you know TanStack Query, TanStack DB or fate
 
@@ -53,9 +55,11 @@ 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)).
+Subscriptions), a devtools panel of its own (`Data.inspect`, `Data.why` and
+`Data.timeline` are the data one would show), and retries of a failed read (it
+stays failed until something asks again; see
+[When a read fails](#when-a-read-fails)). Only a durable write is sent again
+on its own, and only when nothing answered it.
 
 ### And TanStack DB, and fate
 
@@ -66,8 +70,9 @@ 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
+`matching` judge the rows a list already holds, a new list is a server query,
+and a list read `live` is kept current by the server's live source, not by
+the client. 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.
 
@@ -89,13 +94,19 @@ what you are doing:
 | --- | --- |
 | 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 read is `Loading` or `Refreshing` and you did not expect it | [Why is it `Loading`?](#why-is-it-loading) |
 | 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) |
+| A page I came back to reads `Refreshing` or `Loading` | [Why `Refreshing`?](#why-does-a-page-i-went-back-to-read-refreshing) |
+| Ask the Model why a read shows what it shows | [`Data.why`](#why-is-it-loading) |
+| Test that a list never blinks to `Loading`, without a browser | [`Trace`](#testing-what-a-reader-sees-trace) |
+| Test that what a write shows is what the server stores | [`Law`](#testing-that-a-prediction-is-the-truth-law) |
 | 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) |
+| Save a write that must reach the server across a reload or offline | [`Data.outbox`](#a-write-that-outlives-the-page-dataoutbox) |
+| Keep a list current as the server changes it | [Live data](#live-data) |
 | 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) |
@@ -109,6 +120,7 @@ One owner per datum:
 | --- | --- |
 | Route, selected item, local form state, transient UI errors | the application Model and `update` |
 | Server-derived facts that can be refetched | `foldkit-remote` |
+| A write the server decides, which must be sent even after a reload | `foldkit-remote`, `durable` (its outbox) |
 | 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` |
 
@@ -117,6 +129,7 @@ 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
+  outbox: send it later               converge
 ```
 
 A Surface may project all of these owners at once. Observation does not transfer
@@ -308,12 +321,13 @@ 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)),
+  Option.map(model.openProjectId, id => Data.get(Entity.select(Project, { name: true }), id)),
 )
 foldData.subscriptions({ detail })
 ```
 
-It belongs to the domain's application and sends no Messages. A domain bound
+Its `projectionOf(model)` gives back that read, with its value's type. 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.
 
@@ -351,8 +365,7 @@ const clientLayer = Layer.unwrap(
 Or, with no Effect RPC on the server, plain JSON over HTTP: each call a `POST`
 of `{ operation, payload }`, answered `{ result }` or `{ error }`.
 [`RemoteServer.answer`](../remote-server/README.md#over-plain-json) is the
-other end. `Remote.json(send)` is the same client over any other way of
-sending the request, a worker or a server running in the page:
+other end:
 
 ```ts
 const overHttp = Remote.clientLayer(
@@ -360,53 +373,13 @@ const overHttp = Remote.clientLayer(
 )
 ```
 
-`headers` is read for each request, so a token that changes reaches the next
-call. A 401 fails every call kind, a read, a query, a mutation or a live
-stream, with `_tag: 'Unauthenticated'` (and `reason` when the server gave
-one): the server could not tell who is asking. `RemoteData.denied(error)`
-reads a failure as that or a 403 (`Forbidden`), typed, and as none for any
-other, so a view tells "sign in again" from "could not load" without
-comparing tags. Remote treats it as any failure: a read or query is `Failed`, and a live stream restarts with its
-backoff, refused again each time, until the application signs in again and
-calls `Remote.forget`. A 403 whose body does not
-say `forbidden` itself, as Remote's server's does, comes from middleware in
-front of it refusing a session (a bare `{ error }` included): it fails a
-mutation as `Forbidden` and any other call with the status. A 401 is read the
-same whatever its body says. Neither carries live data. For live data over the same `POST`s,
-`Remote.httpWithLive` keeps reads, queries, and mutations as `http` sends
-them and streams live requirements as a `text/event-stream` of changes;
-[`serveFetch`](../remote-server/README.md#over-fetch-workers) is the other
-end. Abandoning the stream aborts the request, which interrupts the
-subscription server-side.
-
-For a server in a worker or in the page (a sandbox), `foldkit-remote/port`
-speaks Effect's own RPC worker protocol over a `MessagePort`, so live data,
-typed errors and interruption cross it too.
-[`servePort`](../remote-server/README.md#over-a-messageport) is the other end:
-
-```ts
-import { port } from 'foldkit-remote/port'
-
-// A new conversation each time the protocol connects: one port here, the other to the server.
-const overPort = port(() => {
-  const channel = new MessageChannel()
-  worker.port.postMessage({ open: 'remote' }, [channel.port2])
-  return channel.port1
-})
-```
-
-It is a `Layer<RemoteClient>` like the others; a port that cannot be set up is
-a defect, not a failed read.
-
-The stock client is accepted as it is. When its transport fails, the call
-fails with its own Remote error (`RemoteReadError`, `RemoteQueryError`,
-`RemoteMutationError`, `RemoteLiveError`), which the UI shows and retries like
-any other failure.
-
-Either is a Layer the runtime provides to `subscriptions` and Commands. The
+Each 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.
+for what the in-memory one can and cannot do, and
+[Clients and transports](#clients-and-transports) for the others (a worker or
+a `MessagePort`, live data over HTTP), what a refused or unreachable call
+does, and testing a server over HTTP.
 
 ### 6. Watch it arrive
 
@@ -461,8 +434,11 @@ function update(model: Model, message: Message): Update.Return<Model, Message, R
 }
 ```
 
-The rest of this guide uses the fold. With the spread, read `Data.subscriptions`
-for `foldData.subscriptions` and `Data.mutate` for `foldData.mutate`.
+The snippets below call the domain itself (`Data.subscriptions`,
+`Data.mutate`, `Data.retry`, `Data.preload`), as the spread form does. Under
+the fold, call the fold's members of the same names (`foldData.mutate`, …),
+which yield the wrapper Message; the members that only read or write the Model
+(`Data.get`, `Data.refresh`, `Data.overlay`, …) stay on the domain either way.
 
 ### One value with `foldkit-bundle`: `Data.wiring`
 
@@ -527,7 +503,8 @@ The states are:
 - **`Loading`** — required data is absent and a read, or a list's query, is in
   flight.
 - **`Ready`** — every selected field is present and decodes.
-- **`Refreshing`** — the current value remains visible while it is being refetched.
+- **`Refreshing`** — the current value remains visible while it is being
+  refetched, or, for a list, while some of its rows are still being read.
 - **`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
@@ -574,7 +551,8 @@ that failed does not throw away what the reader was already looking at. Only a
 `Failed` with nothing to show reaches `failed`.
 
 The `data` branch is told which it got, as a `Freshness` — exported, so a view
-helper that takes one can name it:
+helper that takes one can name it, and folds it with its exhaustive
+`Freshness.match`:
 
 | `Freshness` | What it means |
 | --- | --- |
@@ -605,22 +583,75 @@ 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. …' }
+// { state: 'Initial',
+//   because: [Why.NotFetching({ surfaces: ['ProjectPage'] }), Why.Fields({ … })],
+//   message: 'ProjectPage reads it and is active, yet nothing is fetching it. …',
+//   surfaces: Option.some(['ProjectPage']) }
 ```
 
+The first reason is the one that decides `Initial`:
+
 - `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.
+  you gave `Data.subscriptions`, or its `Surface.at` function returns none for
+  this Model (the route is not there yet).
+- `NotFetching`: an active Surface reads it and nothing started a request.
+  Right after a Message that is the moment before the read entry asks; if it
+  stays so, Remote's Subscriptions are not installed in the runtime.
+- `NoActiveRecord`: no `surfaces` were given, so it cannot tell which.
 
 `Data.plan(model, projection)` shows whether Remote believes anything is
 missing at all.
 
+### Why is it `Loading`?
+
+A list reads `Loading` when its page is missing and its query is out, and
+also when it holds its page and one row's field is being fetched. It reads
+`Refreshing` when the page is stale, a row is stale, or a row is left out
+until a field arrives. `Data.why` tells them apart. `because` lists every
+fact the Model holds about what the read reads, by typed reference, never by
+the store's internal marks. The reason that decides the state comes first.
+Match them with `Why.match`:
+
+| `Why` | What it says | What restarts it |
+| --- | --- | --- |
+| `List { list, held, inFlight }` | the list's own page is `Missing` or `Stale` | the read entry, while a Surface reads it |
+| `Fields { row, via, fields, held, inFlight }` | fields of one row are `Missing` or `Stale`; `via` is the relation path (`['owner']`) | the read entry |
+| `ListFailed`, `FieldsFailed` | a request failed | **nothing on its own**: `Data.refresh`, a write of the field, a new page |
+| `Unavailable`, `Undecodable`, `OverlayOnly` | the store holds what cannot be shown | a change of Selection or overlay |
+| `Deleted { row, by }` | the server deleted it (`by` none), or a pending write does | — |
+| `LiveReconnecting`, `LiveRefused` | a live stream of a Surface reading it broke, or was refused | the live entry, with backoff; nothing, for a refusal |
+| `Pending { row, fields, by }` | a pending write shows these fields | its answer |
+| `Joined`, `Left { list, row, by, terms }` | the list shows a row its pages do not hold, or hides one they do | its answer |
+
+`by` is a `ShownBy`: `Write { requestId, mutation }`, `Overlay { id }` or
+`Live { cursor }`. `terms` are the list body's `where` predicates judged over
+the row as the client placed it, so a row that joined says which term put it
+there, and one the client could not judge says what it lacked:
+
+```ts
+// a project archived optimistically, in a list of active ones
+Why.Left({
+  list: { query: 'ByStatus', identity },
+  row: { entity: 'Project', id: 'p1' },
+  by: Option.some(ShownBy.Write({ requestId: 'r7', mutation: Option.some('Archive') })),
+  terms: [{ term: 'Project.status = $status', truth: 'False', reason: Option.none() }],
+})
+```
+
+`truth` is `True`, `False`, `Null` (SQL's unknown, which keeps a row out) or
+`Unknown` (the store lacks what it rests on). `ReadWhy` is a Schema:
+`Schema.encodeSync(ReadWhy)(why)` is JSON for a log or a devtools client.
+`Data.why` reads the Model and nothing else: it plans nothing and fetches
+nothing.
+
+**Across a history.** `Data.timeline(start, history, { feed, post },
+{ surfaces })` takes the Messages `update` handled, each with the Model it
+left (what Foldkit's devtools records), and gives one step per change of a
+read's tag: the Message that made it, `why` at the Model it changed to, and
+`regression` when a read that showed a value stopped showing it with no
+reason a reader can see. Foldkit's devtools has no place for a panel of
+another package's, so the timeline is the data, not a panel.
+
 ### Why is it stale?
 
 Under the default `RemotePolicy.cacheFirst`, a present field is never asked for
@@ -634,8 +665,8 @@ server said last time. To see change:
   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).
+- **As it happens**: `Data.live` instead of `Data.get`, or `live: true` on a
+  `Data.query`, 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).
@@ -647,25 +678,42 @@ 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
+  requestId)` reads `Failed` with the error. Nothing retries it on its own
+  (`Data.retry` sends it again; see [When a write fails](#when-a-write-fails)).
+  A write survives a reload only when it is sent `durable`
+  ([`Data.outbox`](#a-write-that-outlives-the-page-dataoutbox)); an edit that
+  must converge with other devices' offline edits 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.
+- **It succeeded, but the answer did not name the row.** The answer carries
+  what the active Surfaces and the request's layer show of each row it names
+  ([What an answer carries](#what-an-answer-carries)); a row it changed
+  without naming (a post's count, after a like) keeps the old value until a
+  read writes the new one. Name the row in the answer.
 - **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
+### Why does a row leave its list for a frame after a mutation?
+
+The answer left out fields the row showed while the request was pending. Once
+the layer comes off, the store lacks them, so the read entry fetches them:
+until they arrive, a list leaves the row out (and reads `Refreshing`), and a
+read of that entity alone reads `Loading`. An answer carries what the active
+Surfaces read and the layer showed of every row it names, so this is a row
+the answer did not name, a field the server's read left out, or a server
+that answers without the read (one older than the client, or whose read
+failed). `Remote.make({ verifyPredictions: true })` names each one: see
+[Checking an answer against what was shown](#checking-an-answer-against-what-was-shown).
+
+### Why does a page I went back to read `Refreshing`?
+
+Remote keeps what the screens you most recently left reached: the last 16
+lists and 256 reads (`departedLimit`). A list left is held **stale**, so going
+back shows its rows at once and reads `Refreshing` while the planner refetches
+it; the page that answers replaces what was held. Only past those limits is a
+screen's data collected, and then coming back reads `Loading` and refetches.
+To keep something no screen reads, 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`?
@@ -780,6 +828,12 @@ const card = Data.get(ProjectCard, 'p1') // Projection<Model, RemoteData<{ name;
   A cursor is not part of the name: a page read from a cursor continues its page.
   The server refuses a request that pages one relation more than four ways, and
   a field's own name may not contain `@`.
+- A `many` relation read whole, with no window, is bounded on the server:
+  `foldkit-remote-drizzle`'s `source` reads at most `maxCollection` children of
+  one row (100 unless its Source says), and fails the read, naming the
+  relation, when a row has more, since a whole list cannot say it was cut
+  short. The read then reads `Failed`. Read a collection that can grow without
+  limit through `Entity.page`.
 
 `Entity.make` with `Entity.ref` keeps working, and both kinds can share one
 domain. Both packages export `Entity`; a module that needs `Entity.from` beside
@@ -817,8 +871,10 @@ becomes `Refreshing` without discarding the old value. Planning accepts `now`
 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.
+`now`. A mutation's answer is dated by another clock: Effect's `Clock`, read
+when the answer lands, so a test of how written rows age drives `TestClock`.
+`Data.mutate`'s `now` option is the write's time, sent to the server; it does
+not date the answer.
 
 A policy belongs to one `subscriptions` call, and covers every read in it. Reads
 under different policies take a call each:
@@ -924,20 +980,23 @@ of it.
 ### 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`:
+regained — hand `Data.refresh` the active record the wiring takes:
 
-```ts
-case 'ClickedRefresh': {
-  if (model.route._tag !== 'project') return { model }
-  const page = ProjectPage.projection({ projectId: model.route.projectId })
-  return { model: Data.refresh(model, page) }
-}
+```ts sketch
+case 'ClickedRefresh':
+  return { model: Data.refresh(model, actives) }
 ```
 
+Each entry is resolved for this Model as the read entries resolve it, so a
+`Surface.at` page reads with the params the route gives it, and an inactive
+entry asks for nothing. Add a Surface to `actives` and its refresh comes with
+it. One entry (`Data.refresh(model, actives.project)`), a Projection, or a
+Surface without params narrows it.
+
 `Data.refresh` performs no I/O and restates no request. It returns the Model
 with every selected field the store holds reading `Refreshing`, every entity it
-knew to be absent forgotten, so `NotFound` reads `Loading` and is asked for
-again, and every loaded connection invalidated; the `Data.subscriptions` read entries then refetch it,
+knew to be absent asked for again (it reads `NotFound`, and stays out of every
+list, until the answer says it exists), and every loaded connection invalidated; the `Data.subscriptions` read entries then refetch it,
 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`.
@@ -948,6 +1007,25 @@ 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.
 
+`{ failed: true }` asks again only what failed: each entity read whose fields
+(or a related row's) failed, and each list whose query did. That is a "Try
+again": what loaded keeps its value, and a list keeps its later pages, which a
+whole refresh would replace with one page.
+
+```ts sketch
+case 'ClickedTryAgain':
+  return { model: Data.refresh(model, actives, { failed: true }) }
+```
+
+One list can also be named by its query and input, with no select or window
+to restate: `Data.refresh(model, Everyone.ref({}))` invalidates that list for
+every window reading it. It marks no row's fields, since a ref names no
+selection; the refetched page carries what each read selects. That suits a
+list another page reads, after a write whose answer cannot say it changed: a
+list the Model never loaded is left alone, and one nothing observes now is
+fetched when it is next read. With `{ failed: true }` it is asked again only
+if its query failed. A query the domain does not register is refused.
+
 ### Forgetting everything: a change of principal
 
 Everything Remote knows, it knows for a principal: a value the server gave
@@ -956,7 +1034,7 @@ 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
+```ts sketch
 case 'SignedOut': {
   return { model: Data.forget({ ...model, session: Option.none() }) }
 }
@@ -999,7 +1077,8 @@ const Data = Remote.make({
 something the client should be able to state, declare it with a body instead:
 
 ```ts
-import { Entity, Expr, Order, Query } from 'foldkit-entity'
+import { Entity, Expr, Order } from 'foldkit-entity'
+import { Query } from 'foldkit-remote'
 
 const Task = Entity.define(
   'Task',
@@ -1031,6 +1110,23 @@ can compile that body rather than be told the same thing again in its own
 dialect; one that would rather answer the query its own way still can, and a
 descriptor from `Query.make` has no body at all.
 
+**Which to declare.** A list the client should keep right after a write needs
+a body: the body is what lets the client place a new or changed row in the
+pages it holds instead of fetching the list again. A `Query.make` list is
+invalidated by any change to its Entity, so it is fetched again after every
+write that touches one. A body can follow relations
+(`Expr.path`, `Expr.exists`, a path from `Expr.viewer`), so a feed of the
+people you follow is a body too. Keep `Query.make` for a list whose meaning
+only the server can state, such as a search ranking.
+
+When part of a filter is something a body cannot say, put what it can say in
+the body and the rest in the server's own `where`
+(`foldkit-remote-drizzle`'s `query(descriptor, { entity, where })`), which is
+conjoined with the body. The client judges rows by the body alone, so write
+the body to admit no row the client makes or moves that the server's `where`
+refuses: such a row is placed in the list and stays there until the list is
+read again.
+
 The body is built **once**, when the query is declared. Inside it `input.ownerId`
 is a placeholder for the value the query will be given, not the value — there is
 nothing there yet to branch on. A condition that depends on what was passed is a
@@ -1062,8 +1158,14 @@ flat array. That matters when page 1 and page 3 are loaded but page 2 is not:
 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. The `select` travels with the query: the server
+A query Projection is `Initial` until the page and the selected fields of at
+least one visible item are present. Then it shows the rows it can assemble: one
+whose fields have not arrived yet (a live insert, a row paged in without its
+fields) is left out, and the list reads `Refreshing` until it is, so the rows
+already shown stay on screen. A deleted row is left out too, so a list whose
+shown rows were all deleted shows none (`Refreshing` while others are read),
+never `Loading`. It reads
+`Ready` once every visible item is assembled. 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,
@@ -1115,6 +1217,12 @@ empty-and-complete and empty-and-partial stay different answers — one means
 answer (a search holding NUL, which the server refuses too) gives no items and
 `complete: false`, rather than throwing in `update`.
 
+A body that reads other rows (`Expr.path(Member.relations.team,
+Team.fields.name)`, a path from the viewer) is judged over the whole store: a
+row whose path the store can follow is judged, and one whose path reaches a row
+or field the store lacks is not judged either way, so the answer is
+`complete: false`.
+
 Nothing is created: no connection, nothing new to retain, nothing new to fetch.
 The server stays authoritative for which rows exist.
 
@@ -1122,13 +1230,14 @@ The server stays authoritative for which rows exist.
 
 A connection's rows are edges the server delivered, and a query body describes
 *which rows* — so until something evaluates the body on the client, nothing here
-can say whether a row belongs to a query. `Remote.matching` says:
+can say whether a row belongs to a query. `matching`, exported by
+`foldkit-remote`, says:
 
 ```ts
-const judged = Remote.matching(Data.storeOf(model), ProjectsByOwner, { ownerId: 'u1' })
+const judged = matching(Data.storeOf(model), ProjectsByOwner, { ownerId: 'u1' })
 
 judged.matched  // keys satisfying the body, in the order it asks for
-judged.skipped  // keys held, but missing a field the body reads
+judged.skipped  // keys held, but not judged either way
 ```
 
 It is pure, and it runs the **same interpreter the server checks itself
@@ -1145,7 +1254,9 @@ keys — so it is in the shape. A caller that knows it holds the whole populatio
 complete answer.
 
 **`skipped` is the honest half.** A row missing a field the body reads cannot be
-judged: it is neither a match nor a non-match. Dropping it silently would turn
+judged: it is neither a match nor a non-match. Nor can a row holding a value no
+interpreter answers for (text with a NUL); each row is judged alone, so one such
+row is skipped and the others are still answered. Dropping it silently would turn
 "I could not tell" into "no", so it is named instead, and the caller decides
 whether to fetch the field, ask the server, or say the answer is partial.
 
@@ -1238,8 +1349,10 @@ again every time some unrelated read restarted the entry. What failed is left
 out of the plan, and everything else is still fetched: the rows a failed list
 holds, the other fields of an entity. What asks again:
 
-- `Data.refresh(model, projection)` — the retry button. It works on something
-  that never loaded, too.
+- `Data.refresh(model, actives, { failed: true })` — the retry button. It
+  works on something that never loaded, too. A read with nothing to show reads
+  `Loading` while it is asked again, and `Failed` again if it fails again, so
+  the button does not blink away.
 - The value arriving anyway: a page for a list, or a read, live patch or
   mutation result that writes the field.
 - The server invalidating a list over a live stream, or deleting the entity.
@@ -1305,7 +1418,7 @@ const RenameProject = Mutation.make('RenameProject', {
 
 A mutation starts from ordinary application `update`:
 
-```ts
+```ts sketch
 case 'ClickedRename': {
   const { id, name } = message
 
@@ -1331,20 +1444,80 @@ case 'ClickedRename': {
 `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'`.
+against its fields in their wire shape, except a relation, which is a ref:
+`owner: Remote.ref(User, 'u1')`, an array of refs for a `many`, or `null`
+where it is optional. The patch holds the ref key the store keeps. A ref key
+typed by hand (`'User:u1'`) or a ref to another entity is refused, by the type
+and when the patch is made.
 
 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`.
 
+**Answers settle in the order their requests started, not the order they
+arrive.** The server applied the requests in that order, so an answer does not
+overwrite a field, or clear a row's deletion, that a request started after it
+has already settled; and an answer's `deleted` does not delete a row a later
+request has written. Two renames answered out of order keep the second name,
+and an edit answered after the row's delete leaves it deleted. Reads and live
+patches are the server's word at the time they arrive and land as they come.
+The ledger keeps each pending request's place in `mutations.order`, and the
+place of the last answer to write each field in `mutations.settled`, only
+while an earlier request is still pending.
+
 A mutation that deletes says so. The server's outcome carries
 `deleted: [{ entity, id }]`, and settling it tombstones those entities: they read
 `NotFound`, and they leave every connection and relation they were in, so the
 server names no list. Patches apply first, so an entity named both ways is
 deleted; a retry of the same request deletes nothing again.
 
-**Which lists a mutation changed is worked out from its answer.** Each patch
+A delete can show before the answer, with no list named either.
+`Remote.tombstone(entity, id)` in `optimistic` is a pending tombstone: while
+the request is in flight the row reads `NotFound` and leaves every list and
+every relation that lists it, as a settled delete does. It is a layer like a
+patch, so the server's store is untouched (`Data.confirmed` still reads the
+row), a failure brings the row back everywhere, and the answer's `deleted`
+keeps it gone. A pending delete wins over every pending patch of its row.
+
+```ts
+Data.mutate(model, DeletePost, { id }, { optimistic: [Remote.tombstone(Post, id)] })
+```
+
+A pending patch shows a field before the server has sent it, but does not stand
+in for it: a read still fetches a field of a row the server holds that only a
+layer shows, so a failure that takes the layer away leaves the server's value,
+not `Initial`. A row only a request holds (one the store has never read, or
+read as absent: a pending create) is not fetched while the request is pending,
+since the server has nothing of it yet; once the answer lands, the fields it
+did not carry (a guard's `may`) are.
+
+Optimistic entity patches are **layers over the base store**, not inverse
+patches. If multiple mutations overlap, the visible cache is recomputed as base
+plus the still-pending layers, so settling one does not require trying to undo
+its old value manually.
+
+Connections can be optimistic too:
+
+```ts
+import { ConnectionChange } from 'foldkit-remote'
+
+const { model: started, command } = Data.mutate(model, AddComment, input, {
+  optimistic: ({ tempId }) => [
+    Remote.patch(Comment, tempId, { id: tempId, body: input.body }),
+    ConnectionChange.prepend(
+      CommentsForPost.ref({ postId }),
+      Remote.ref(Comment, tempId),
+    ),
+  ],
+})
+```
+
+A successful server result can replace the request's temporary connection
+overlays with confirmed ones in place.
+
+### Which lists a write moves
+
+Which lists a mutation changed is worked out from its answer. Each patch
 says which row it wrote; the fields whose value differs from what the client
 held are what changed (an answer returning a whole row changes only what is
 new). Every loaded list over that Entity is judged by its query's body against
@@ -1371,6 +1544,10 @@ the store the answer left:
   it could answer with the rows before the write;
 - a list over a `Query.make` query, which declares no body, is invalidated by
   any change to its Entity;
+- a list whose body reads other rows (a path, an exists, a path from the
+  viewer) is invalidated by a change to any member those read, or a deletion
+  of such a row: a team renamed moves every member listed by its name. A
+  change to the link a path starts from re-judges that row alone;
 - a row a list does not hold that changes a member the server's own read rule
   filters on (an owner, a team: declared on the Entity as `ReadFilter`, which
   `foldkit-guard` attaches) invalidates it: whether the row now belongs is the
@@ -1389,12 +1566,13 @@ does not run is judged by the server, as any row the client cannot judge is:
 `Data.filtered` answers it incomplete and a change to it refetches.
 
 **A placement can be checked against the server.** `Remote.make({ ...,
-verifyPlacement: true })` places as usual, and also fetches each list it placed
+verifyPredictions: true })` places as usual, and also fetches each list it placed
 what the server said in (an answer, as above, or a read or a live patch, as
 below); when the server's first page arrives it is compared with the order
-placed, and a disagreement is kept in `model.remote.placementMismatches` (and
-`Data.inspect`): an order the page does not share, or a row placing took out
-that the page still lists. A pending edit is not checked: the server does not have it
+placed, and a disagreement is a `PredictionMismatch` [diagnostic](#diagnostics)
+whose `part` is a `Placement`:
+an order the page does not share, or a row placing took out that the page
+still lists. A pending edit is not checked: the server does not have it
 yet. Turn it on in development and tests: a collation the client
 and the server disagree on then fails an assertion instead of misplacing a row
 for a reader.
@@ -1425,6 +1603,8 @@ shown.
 `Data.refresh` stays for what an answer cannot say, such as a server-side
 effect on rows it did not return.
 
+### What became of a write
+
 `Data.mutation(model, requestId)` reads what became of it from the Model:
 `Pending`, `Applied`, `Failed` with the error the server or transport gave, or
 `Unknown` for an id never started here (or settled so long ago it left the
@@ -1439,8 +1619,65 @@ operation, and a retry with the same `requestId` (`Data.mutate(model, M, input,
 can recognise the retry. After a reload the record of it is gone, and the same
 request id is a new operation.
 
-A mutation can say what the server may refuse it with, as data rather than a
-message to parse:
+### When a write fails
+
+A write that fails releases its optimistic layer, so its change disappears.
+Remote keeps the failure in the ledger, with the mutation and the input it was
+started with, until the application answers it. The application reads it from
+the Model; it keeps no list of its own:
+
+```ts sketch
+// The view: a notice for each post that did not send, with its text to give back.
+Data.failedWrites(model, CreatePost) // ReadonlyArray<{ requestId, mutation, input, error, refusal }>
+
+// update
+case 'ClickedRetry':
+  return Option.match(Data.retry(model, message.requestId), {
+    onNone: () => ({ model }),
+    onSome: started => ({ model: started.model, commands: [started.command] }),
+  })
+case 'ClickedDiscard':
+  return { model: Data.dismiss(model, message.requestId) }
+```
+
+- `Data.failedWrites(model)` lists every failed write, oldest first, and
+  `Data.failedWrites(model, CreatePost)` only that mutation's, with its `input`
+  and `refusal` typed by it. A write in flight or applied is not listed.
+- `Data.retry(model, requestId)` sends a failed write again as itself: the same
+  input, request id and operation, with its optimistic change shown again. It
+  is `None` for a write that is not failed, so a second press does nothing.
+- `Data.dismiss(model, requestId)` forgets it.
+
+Only a write in flight can fail: a `MutationFailed` repeated, or arriving after
+the write applied, was dismissed or was settled by `forget`, returns the Model
+it was given, as a repeated `MutationSucceeded` does.
+
+A failed write stays listed until one of those, or `Data.forget` at a change of
+principal. Nothing drops one on a timer: that would hide a failure the reader
+has not seen. The ledger is bounded (the last 1024 failures), and is never
+persisted, so a reload forgets it.
+
+To act on a failure in `update` (log it, move focus, put text back), have the
+wiring share it. Remote reduces it first, then the application's own update
+receives it with a Model that already lists it:
+
+```ts
+Page.assemble(Data.wiring(actives, { shared: ['MutationFailed'] }))
+// own update: MutationFailed is now one of its Messages, so its match must answer it
+```
+
+A wiring that does not share it records each failed write as a `WriteUnheard`
+[diagnostic](#diagnostics), which by default logs it: the change went, and
+nothing in the application's update was told.
+
+**Refused for who asks.** A server may also refuse who is asking, whatever the mutation
+(`RemoteServer.forbid`). Then `Data.mutation(model, requestId)` is `Failed`
+with an error of `_tag: 'Forbidden'`, and `reason` when the server gave one,
+for the person who asked. Asking again as the same person is refused again,
+so show it rather than retry.
+
+**Refusals as data.** A mutation can say what the server may refuse it with,
+as data rather than a message to parse:
 
 ```ts
 const SetPrice = Mutation.make('SetPrice', {
@@ -1452,17 +1689,115 @@ const SetPrice = Mutation.make('SetPrice', {
 Data.refusal(model, requestId, SetPrice) // Option<{ _tag: 'Field', key: 'price', reason: string } | { _tag: 'Conflict' }>
 ```
 
-A mutation can also be a declared write: `Mutation.write(name, write)` over a
+`Refusal.field(key, reason)` names an input key and the Schema of why;
+`Refusal.conflict` says the row moved on, and `Refusal.unmet` that it does not
+hold what a [declared write](#declared-writes-what-the-client-predicts)'s
+`when` asks of it. A `Mutation.write` is refused as unmet only when its write
+has a `when`, and its `Refusal` type says so: without one it stays `Conflict`,
+so a match over it needs no `Unmet` arm. `Refusal.taken` says an insert's id
+is already a row's: its `entity` and `id`, the caller's own, and nothing of the
+row, which may be hidden from them. A `Mutation.write` over `Write.insert` is
+refused as taken and never as a conflict, since an insert expects no revision.
+`Refusal.invalid` says the row it
+would leave breaks an invariant of its Entity (`Entity.invariant`): its
+`entity` and `rule` (an id is unique only within its Entity, so the two name
+it) and its `path`, which a form shows the `message` beside, or none and empty
+when the invariant reads something the caller may not see. Every `Mutation.write` may be
+refused so, since the server's Entity may hold invariants the client's does not
+show. `Refusal.isInvalidBy(refusal, invariant)` asks whether it names one
+invariant, by its Entity and its id, given as `Entity.invariant` returned it
+(export it beside the Entity), so its id is never spelled again; an unnamed
+refusal matches none, and so does another Entity's invariant of the same id. The
+server sends the refusal encoded by this schema and `Data.refusal` decodes it
+by the same one; it is none while the mutation is pending or applied, or when
+it failed for another reason.
+
+### Declared writes: what the client predicts
+
+A mutation can be a declared write: `Mutation.write(name, write)` over a
 `foldkit-entity` `Write.update`, `Write.insert` or `Write.delete`. Its input is
 the write's, it answers nothing of its own, and `Data.mutate` shows an update's
 or an insert's row until the server answers, so it needs no `optimistic` list;
-a delete shows nothing until its answer removes the row everywhere. An update's
+a delete shows its row deleted, as `Remote.tombstone` does. An update's
 `increment` is shown as a prediction: its amount is added to the value the store
 holds whenever the row is read, so a change that reaches the store meanwhile is
-added to rather than hidden, and two pending increments add up. A field the
-client has not read is not guessed; it shows the server's sum when the answer
-comes. The prediction is never authority: the server decides, and its answer
-replaces it. The [declared writes guide](../../docs/declared-writes.md) follows
+added to rather than hidden, and two pending increments add up. A computed
+field is predicted the same way, by `Remote.make`'s `operators` over the row as
+it is read (`Write.apply`), so a live change to what it reads changes the
+prediction. So is a count another registered Entity derives over the written
+row's relation (`likeCount: Derived.count(Like.relations.post)`): inserting a
+Like adds one to the post it points at, deleting a Like the client holds takes
+one away from the post it pointed at, and pointing it elsewhere does both, each
+added as an increment is. Where the client does not hold where the row pointed,
+or holds no count on that post, nothing is predicted.
+
+A write shows what its Entity sets from the context (`Entity.sets`) as well,
+which no input sets: `Expr.viewer` as the viewer `Remote.make` is told of, and
+`Expr.now` as `Data.mutate`'s `now`, the time the reader acted. An insert sets
+every such member, an update those set `on: 'write'` (an `editedAt`). A new
+row's counts read 0 and its exists none.
+
+`update` reads no clock, so the time is read where the action is, by a
+Command, and carried in the Message that starts the write. `Remote.now(toMessage)`
+is that Command; it reads Effect's `Clock`, so a test pins it:
+
+```ts sketch
+// the action asks for the time…
+Posted: ({ post }) => ({ model, commands: [Remote.now(now => Message.Clocked({ post, now }))] }),
+// …and the Message it yields starts the write with it
+Clocked: ({ post, now }) => {
+  const sent = Data.mutate(model, PostChirp, post, { now })
+  return { model: sent.model, commands: [sent.command] }
+},
+```
+
+The request sends the same number, and the server takes it as the row's time
+when it lies within its `clockSkew` of the server's own clock (60 seconds
+unless `RemoteServer.make` says), so the answer agrees with what was shown.
+A retry (`Data.retry`) sends it again. Without `now`, a time the write sets is
+not predicted: the row reads as missing it until the server's answer brings the
+server's time. A supplied member declared with a `predict` (`Derived.make(schema,
+{ predict })`, as Guard's `may` is) is foreseen over the row the write leaves,
+the store's row with the write's values over it and a field the write moves
+unknown; where it foresees none, the row reads as missing it until the answer.
+An application that already mints the row's id in a Command can read the
+clock in the same one (`examples/reference`'s `NameNote`). The row then joins
+every loaded list whose body admits it, where the list's order puts it, while pending and once answered: a post
+set at its time goes to the top of a newest-first list. A list without a
+body, or one filtered by a read rule the client does not run, is the server's
+to place.
+
+A viewer-relative member is predicted for the viewer `Remote.make` is told of.
+With a `Like` pointing at a `Post` and a `User` (`examples/chirp` declares the
+whole domain, its writes and its server):
+
+```ts sketch
+const Post = Social.Post.pipe(
+  Entity.derived({
+    liked: Derived.exists(Social.Like.relations.post, { viewer: Social.Like.relations.user }),
+  }),
+)
+const Data = Remote.make({
+  model: App.model.remote,
+  entities: [User, Post, Like],
+  mutations: [LikePost, Unlike],
+  viewer: model => Option.some(Remote.ref(User, model.me)),
+})
+```
+
+`liked` is the id of the viewer's Like of the post, or none. Inserting a Like
+pointing at a post and at the viewer shows it on that post (where the post is
+held with `liked` read, and none yet); deleting a Like, or pointing it at
+another post or person, takes it from the post it is shown on. That post also
+says where the deleted Like pointed, so its count goes down with no Like row
+held: unliking is `Data.mutate(model, Unlike, { id })` with the id `liked`
+holds. The store holds one viewer's values, as it holds one principal's, so a
+change of viewer is a change of principal: `Data.forget`.
+
+A field the client has not read, or a computation by an operator its table
+lacks, is not guessed; it shows the server's value when the answer comes. The
+prediction is never authority: the server decides, and its answer replaces
+it. The [declared writes guide](../../docs/declared-writes.md) follows
 one write from here to the statement that lands it. `keys` names the input keys
 an author changed: only those are shown, and the request carries them for the
 server to write; the input is still sent and validated whole.
@@ -1475,51 +1810,106 @@ const EditProject = Mutation.write(
 Data.mutate(model, EditProject, { id: 'p1', name: 'Apollo II', status: 'active' }, { keys: ['name'] })
 ```
 
-`Refusal.field(key, reason)` names an input key and why; `Refusal.conflict`
-says the row moved on, and `Refusal.unmet` that it does not hold what a declared
-write's `when` asks of it. A `Mutation.write` is refused as unmet only when its
-write has a `when`, and its `Refusal` type says so: without one it stays
-`Conflict`, so a match over it needs no `Unmet` arm. `Refusal.invalid` says the
-row it would leave breaks an invariant of its Entity (`Entity.invariant`): its
-`rule` and `path`, which a form shows the `message` beside, or none and empty
-when the invariant reads something the caller may not see. Every
-`Mutation.write` may be refused so, since the server's Entity may hold
-invariants the client's does not show. `Refusal.isInvalidBy(refusal, invariant)`
-asks whether it names one invariant, given as `Entity.invariant` returned it
-(export it beside the Entity), so its id is never spelled again; an unnamed
-refusal matches none. The server sends the refusal encoded by this schema and
-`Data.refusal` decodes it by the same one; it is none while the mutation is
-pending or applied, or when it failed for another reason.
+### Refused where it is made
+
+Before it shows or sends a declared write, `Data.mutate` refuses the ones the
+client can already tell the server would refuse, in the order the server
+checks: who asks, then the row.
+
+**A write the held `may` says no to.** A supplied member may say which write
+its value forbids (`Derived.make(schema, { forbids })`); Guard's `may` does:
+the row's `Update` or `Delete`, a written member's own rule, or a relation's
+`Link` or `Unlink`, where it reads `false` for the row as the store holds it.
+`Data.mutate` asks each such member it holds before it judges the invariants,
+as the server refuses who asks first, and answers `MutationFailed` with `_tag:
+'Forbidden'` and the `explain`'s words as `reason`, showing and sending
+nothing. A `may` not held, or one that does not name the part, refuses nothing;
+a held `may` is the server's answer as of its read, so `Data.refresh` asks
+again.
+
+`may` is a UI hint, and the server enforces every write. A `may` that says
+yes, stale after a change of role, foreseen for a row the client wrote, or
+edited in the page's Model, decides nothing: the request carries no `may`,
+the server checks the write by its rules as the request's principal, and a
+refusal comes back as `Forbidden`, which takes the shown change back. The
+client's refusal only saves the round trip for a no it already holds. See
+[`foldkit-guard`](../guard/README.md#what-may-tells-a-reader-and-what-it-does-not)
+for what `may` tells a reader.
+
+**A write the client can tell is invalid.** `Data.mutate` judges a declared
+write's Entity invariants over the row it would leave, as the client holds it:
+the store's row with the write's values over it, a field it moves (an
+increment, a computed value) not held. Where one is definitely broken, it shows
+nothing and sends nothing; its Command answers `MutationFailed` at once with
+the very `Refusal.invalid` the server would send, so `Data.refusal`,
+`Data.failedWrites` and your `update` handle it as a server's. An invariant
+over a field the client lacks is undecided and refuses nothing: the server
+judges it. Passing `optimistic` yourself skips the check.
+
+### What an answer carries
+
+When the answer comes, the request's layer comes off, so the answer must hold
+everything the layer showed. The client says what that is: `Data.mutate` sends,
+with the request, what every active Surface reads of each entity (each
+`Data.get`'s fields and each `Data.query`'s `select`, relation targets
+included), and every field the layer itself shows. The second matters when
+a write moves a count no Surface reads now: a note deleted on its own page
+lowers its author's `noteCount`, which only the notebook page reads, and
+without it the answer would leave the count as it was before the write. The
+server reads, of each row its answer names, the fields it
+shows that the answer left out, after the write and as any read is, and sends
+that read with the answer (`foldkit-remote-server`'s
+[What an answer carries](../remote-server/README.md#what-an-answer-carries)).
+The client writes it in the reduction that releases the layer:
 
-A server may also refuse who is asking, whatever the mutation
-(`RemoteServer.forbid`). Then `Data.mutation(model, requestId)` is `Failed`
-with an error of `_tag: 'Forbidden'`, and `reason` when the server gave one,
-for the person who asked. Asking again as the same person is refused again,
-so show it rather than retry.
-
-Optimistic entity patches are **layers over the base store**, not inverse
-patches. If multiple mutations overlap, the visible cache is recomputed as base
-plus the still-pending layers, so settling one does not require trying to undo
-its old value manually.
-
-Connections can be optimistic too:
-
-```ts
-import { ConnectionChange } from 'foldkit-remote'
+```text
+answer (rows the write names) + read (what the Surfaces and the layer show of them) -> store, layer released
+```
 
-const { model: started, command } = Data.mutate(model, AddComment, input, {
-  optimistic: ({ tempId }) => [
-    Remote.patch(Comment, tempId, { id: tempId, body: input.body }),
-    ConnectionChange.prepend(
-      CommentsForPost.ref({ postId }),
-      Remote.ref(Comment, tempId),
-    ),
-  ],
-})
+So a created post lands with the count, the `may` and the author's name the
+feed reads, though the write stored none of them, and the feed never reads
+`Loading` for it. There is nothing to configure: the Surfaces already say what
+is shown. A row the answer does not name is not read; the server names the
+rows a write changed. Each `Data.subscriptions` call registers what it reads, so
+a `Data.mutate` with none registered sends nothing to show.
+
+### Checking an answer against what was shown
+
+When the answer comes, the request's layer comes off, and what the row shows
+is what the store holds. Two things can then differ from what was shown.
+`Remote.make({ ..., verifyPredictions: true })` settles every mutation as usual
+and records each as a `PredictionMismatch` [diagnostic](#diagnostics), its
+`part` naming which:
+
+- **`Value`:** a field the layer showed that the answer carries another value
+  of. The client's prediction and the server's write disagree: a count moved
+  by two, a time from another clock, a hand-written `optimistic` patch that
+  guessed. A field another pending request also shows is not judged, since
+  that request's value shows before and after.
+- **`Gap`:** a field the layer showed that the answer left out, and the store
+  does not hold. It is then missing: an active Surface that reads it fetches it
+  again, and the row reads `Loading` meanwhile.
+
+```ts sketch
+// requestId: the one Data.mutate returned; mutation: its name
+{ _tag: 'PredictionMismatch', part: { _tag: 'Value', requestId, mutation, entity: 'Post', id: 'p9', field: 'likeCount', shown: 3, answered: 4 }, … }
+{ _tag: 'PredictionMismatch', part: { _tag: 'Gap', requestId, mutation, entity: 'Post', id: 'p9', fields: ['editedAt', 'author'] }, … }
 ```
 
-A successful server result can replace the request's temporary connection
-overlays with confirmed ones in place.
+Match on the part with `PredictionPart.$match`. `Law.check`
+([below](#testing-that-a-prediction-is-the-truth-law)) is the same law, in a
+test, over every part rather than the ones an answer carries.
+
+A row's shown fields are those the request's optimistic patch wrote, added
+to or computed (a declared write's own included), plus those the active
+Surfaces (every `Data.subscriptions` call) read of a row the request patched
+or put in a list. A field the store still holds (an older value, or another
+pending request's) is not reported, nor is a row the answer deleted, or a
+temporary id it replaced. A repeated answer is not checked again. It changes
+nothing but `diagnostics`, so turn it on in development and tests, and assert
+in a test that `Data.inspect(model).diagnostics` is empty. With [the answer's read](#what-an-answer-carries),
+a gap is a row the answer did not name: name it in the answer's `entities`
+(`Remote.patch(Post, id, {})` asks the server for all it shows of it).
 
 ### Showing a change nobody has made
 
@@ -1572,7 +1962,14 @@ capability that must not claim success before the server reflects it:
 ```ts
 Agent.when({
   projection: Data.confirmed(Data.get(ProjectSummary, projectId)),
-  predicate: (project, request) => project.name === request.name,
+  // The projection reads a RemoteData: only a value the server holds can match.
+  predicate: (project, request: { readonly name: string }) =>
+    RemoteData.render(project, {
+      loading: () => false,
+      notFound: () => false,
+      failed: () => false,
+      data: value => value.name === request.name,
+    }),
 })
 ```
 
@@ -1583,22 +1980,113 @@ Sync draws the same line over its replica, with the same words and a different
 mechanism: see [what a reader sees while a change is in
 flight](../../docs/state-model.md#what-a-reader-sees-while-a-change-is-in-flight).
 
+### A write that outlives the page: `Data.outbox`
+
+A like pressed on a train, a post written in a tunnel: the write must reach the
+server, but nothing needs to converge, since the server decides it once. Make
+it durable, and assemble the outbox beside `Data.wiring`:
+
+```ts
+const outbox = Data.outbox({
+  key: model => `outbox:${model.userId}`,
+  scope: model => model.userId,
+})
+const placements = Page.assemble(Data.wiring(actives), outbox)
+
+// update: queued, not sent; its layer shows at once
+const sent = Data.mutate(model, PostChirp, post, { now, durable: true })
+return { model: sent.model, commands: [sent.command] }
+
+// the view
+const { waiting } = Data.outboxStatus(model) // "3 changes waiting"
+```
+
+`outbox.restore(model)` is `persistence.restore`'s twin: resolve it as the
+runtime's `flags` and start `init` from it. It reads back what a reload left and
+mints the page's session, which names its writes; `Data.mutate` with `durable`
+before it has run throws.
+
+```text
+Data.mutate(…, { durable }) → queued in the Model, layer shown   (its Command answers MutationQueued)
+outbox.save  → the queue written to the store, merged with other tabs' → OutboxRead (stored)
+outbox.send  → the oldest stored write sent, one at a time, by one tab  → MutationSucceeded | MutationFailed
+reload       → outbox.restore: the queue back, layers shown → sent again, same operation id, same now
+```
+
+- **Stored before sent.** A write is sent only once the store holds it, so a
+  reload while it is on its way finds it and sends it again. Its request id is
+  its operation id, so the writer's ledger answers the second send from its
+  record: a durable Mutation needs a ledgered writer (`RemoteServer.write`, or
+  remote-drizzle's `writer`), or a handler that answers by operation id.
+- **In order, one at a time.** A post and the like of it, made offline, reach
+  the server in that order. A refused write, or one this version cannot read,
+  does not hold back the rest.
+- **Sent again only when nothing answered.** A send that fails with
+  `Unreachable` (the request did not go, or what came back was no Remote answer) keeps the
+  write waiting and sends it again after 1 second doubling to 30 (`retry: {
+  base, max }`), and as soon as the browser is `online`; each attempt is
+  `OutboxDelayed`. A refusal, `Forbidden` or a server error settles it as
+  `Failed`, as for any write: `Data.failedWrites`, `Data.retry` (queued again)
+  and `Data.dismiss` (gone from the store too) work on it unchanged. A write
+  still waiting cannot be dismissed: it may be on its way.
+- **One tab sends; every tab shows.** The store is shared by every tab on the
+  key. A Web Lock picks the one that sends, which reads the store again first
+  so a write another tab settled is not sent twice; a `BroadcastChannel` tells
+  the others, which show each other's waiting writes and settle them with the
+  sender's answer. Without Web Locks each tab sends what it holds.
+- **`now` is the reader's, still.** A stored write is sent with the time it was
+  made at. Past the server's `clockSkew`, the server writes its own time and
+  reports `ClockSkewed`, and the answer moves the row there: the bound that
+  stops a client backdating rows cannot tell an honest wait from a forged one.
+- **After a deploy.** A stored write naming a Mutation this version lacks, or
+  whose input no longer decodes, is kept as `Unreadable` in `outboxStatus`,
+  never sent, reported once as `OutboxUnreadable`, and removed by
+  `Data.dismiss`. A store that cannot be written reports `OutboxUnsaved`, and
+  the writes are sent anyway.
+- **A change of principal** is `Data.forget` and another `key`, as for
+  persistence: one person's waiting writes are never sent as another's. The
+  page holds the queue it read for one `key` and `scope`; when either moves,
+  it sends none of it and reads the new one's. A store holding another
+  scope's waiting writes is not written over, so a `key` shared by
+  principals reports `OutboxUnsaved` rather than losing them.
+
 ### Remote mutation vs Sync operation
 
-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.
+A durable Remote write is still Remote's: the server decides it once, a
+refusal is final, and the client never reads its own effects before the server
+has answered. If edits must merge with other devices' edits made offline, or
+the application must build on its own unsent edits as if they were committed,
+that is [`foldkit-sync`](../sync)'s journal (see [which state belongs
+here](#which-state-belongs-here)). An optimistic overlay stays a temporary view
+of server-owned data: the outbox stores the operation, never the overlay as a
+queue of edits.
 
 ## Live data
 
 `Data.live` marks a Projection so active `Data.subscriptions` follow server
-changes for it.
+changes for it. A list is marked by its read: `live: true` on `Data.query`
+follows the rows that join, change or leave it, with no row of its own to
+subscribe to:
+
+```ts
+Data.query(Notes, {}, { select: NoteRow, first: 50, live: true })
+```
+
+A Surface's live entry (`<key>.live`) subscribes the rows and the lists its
+reads mark live in one stream, sending each list as its read sends it (query,
+input, window, `select`). A list read live needs `first`, since a server reads
+it again for every change it checks; `Data.query` throws without one. The
+server admits a stream before it asks any live source: its lists' `first`
+count toward `maxIdsPerEntity` with the rows it follows, and it may carry at
+most `MAX_LIVE_QUERIES` (32) lists; past either it is refused
+(`RemoteLiveRefused`, below). A live
+source that watches lists (`foldkit-remote-drizzle`'s `pollLive`) diffs it;
+`RemoteServer.liveHub` watches none, so on a server with only a hub a live
+list changes only when read again.
 
 The Remote Model owns each stream's cursor. Live events carry monotonically
-ordered cursors:
+ordered cursors, counting on from the cursor the stream was opened after (`0`
+for a new stream, so its first event is `1`):
 
 - an old/repeated cursor is a duplicate and is ignored;
 - the next cursor is applied;
@@ -1629,10 +2117,9 @@ break -> gap marked, restarts + 1 -> backoff
 - **A gap stays until the restart.** An in-order event that a broken stream
   still delivers is applied, but does not clear it. The event that arrived
   ahead was dropped, and only the refetch brings back what it said.
-- **What a stream covers is its requirements.** A list the server watches
-  for it (a `ConnectionInvalidate` it sends) is the source's to re-send when
-  the stream opens; the cloudflare example's poll invalidates its list on
-  every open for this reason.
+- **What a stream covers is its requirements.** A list read live is the
+  live source's to re-send when the stream opens: `pollLive` sends a
+  `ConnectionInvalidate` for each list on every open for this reason.
 
 `Data.liveStatus(model, active)` says how what one active entry reads live is
 doing, for a view that shows it:
@@ -1643,15 +2130,26 @@ Match.value(Data.liveStatus(model, Watched)).pipe(
     Idle: () => 'not live',
     Live: () => 'live',
     Reconnecting: ({ attempt }) => `reconnecting (attempt ${attempt})`,
+    Refused: ({ error }) => `not live: ${error.message}`,
   }),
 )
 ```
 
 `Reconnecting` lasts from the break until the stream has resubscribed, and
-carries the error, which is none for a gap. `RemoteModel.streams` holds each
+carries the error, which is none for a gap. `Refused` is a stream the server
+would not open for what it asks (`RemoteLiveRefused`: more rows of one Entity
+than its `maxIdsPerEntity`, or more than 32 lists). Asking again would be refused again, so it is
+not restarted until the entry's live requirements change, which opens a new
+stream; a `LiveRefused` diagnostic records it once. `RemoteModel.streams` holds each
 stream's restarts, its breaks in a row and its last error. `forget` clears it
 with every other server-derived fact.
 
+The live ledger (`live`, `streams`, `gaps`) keeps the 256 streams most
+recently heard from. Retention cannot prune it by what is shown: its roots
+merge every Surface's requirements, and a stream is one Surface's. A stream
+dropped while still open has no cursor, so its next event, past `1`, is a
+gap: it restarts from the start and refetches what it covers.
+
 ## Retention and garbage collection
 
 Remote is a cache, so it should be allowed to forget facts no active feature
@@ -1667,9 +2165,21 @@ reads; `connections` given to any call are kept the same way. A root keeps:
 - data touched by pending optimistic work.
 
 After the configured grace period, `RetentionChanged` enters the Model and the
-pure Remote reducer collects unreachable cache data. An inactive Surface that is
-not otherwise retained may therefore lose its cache, which is safe because the
-server remains authoritative and the planner can refetch it.
+pure Remote reducer collects what no root reaches. The roots it keeps are the
+active ones and those of the Surfaces most recently left, up to
+`departedLimit` (16 lists and 256 entity reads, oldest dropped first), so going
+back to a page shows what it held rather than reading `Loading`:
+
+```text
+Surface left      -> its lists held stale, its reads held
+Surface again     -> rows read Refreshing; the planner refetches the stale list
+page arrives      -> it replaces the held rows; Ready
+past the limit    -> collected; going back reads Loading and refetches
+```
+
+A value nothing reached when retention ran, such as a prefetch no Surface
+showed, is still collected at once. Collecting is safe because the server
+remains authoritative and the planner can refetch.
 
 This is another important difference from Sync: **Remote recovery may discard
 and refetch; Sync recovery must preserve unsent client intent.**
@@ -1683,6 +2193,7 @@ cursors, optimistic layers, mutation bookkeeping, gaps, retention roots) is
 never in one.
 
 ```ts
+import { Option } from 'effect'
 import { RemotePersistence } from 'foldkit-remote'
 
 // A cache carried in the page: prefetch on the server, embed, then hydrate.
@@ -1693,8 +2204,11 @@ const text = RemotePersistence.dehydrate(
   { scope: userId },
 )
 
-const restored =
-  RemotePersistence.hydrate(text, { scope: userId }) ?? RemotePersistence.emptySnapshot
+// None when the text is refused (another scope, version, or a corrupt text).
+const restored = Option.getOrElse(
+  RemotePersistence.hydrate(text, { scope: userId }),
+  () => RemotePersistence.emptySnapshot,
+)
 
 Data.reduce(model, {
   _tag: 'Hydrated',
@@ -1740,13 +2254,33 @@ const persistence = Data.persistence({
 const placements = Page.assemble(Data.wiring(actives), persistence)
 ```
 
-The restore and the save each run as Subscriptions, when the key changes or the
-cache does:
+The first restore belongs before the first frame, or a reload draws `Loading`
+until a Subscription brings the stored rows. `persistence.restore(model)` is
+that restore as an Effect: resolve it as the runtime's `flags`, which the
+runtime runs with its `resources` before `init`, and start `init` from the
+Model it gives (`examples/cloudflare/src/browser.ts` does):
+
+```ts
+Runtime.makeElement(
+  placements.runtime({
+    Model,
+    Flags: Model,
+    flags: persistence.restore(initial(actor)),
+    initial: (model: Model) => ({ model }),
+    // …
+  }),
+)
+```
+
+After that the wiring restores only a key the Model is not restored from (a
+change of principal), and saves as the cache changes:
 
 ```text
 key -> restore -> Hydrated { from: key } -> restoredFrom = key -> save on each change
 ```
 
+Without `restore` in `init`, the wiring restores at start too, a frame late.
+
 - **A restore keeps what the Model already holds.** It hydrates with
   `merge: 'preserve-existing'`, so a fact resumed from the server, or read since
   the page started, wins over the older snapshot.
@@ -1755,6 +2289,11 @@ key -> restore -> Hydrated { from: key } -> restoredFrom = key -> save on each c
   then saved under their key; `forget` clears it as the key changes. The
   `scope` check refuses a snapshot written for another reader; it cannot see
   facts that are only in memory.
+- **`forget` never brings back what it forgot.** It keeps `restoredFrom`, so
+  a key that does not change (a sign-out that keeps the key) is not restored
+  again; the emptied cache is saved over its snapshot after the debounce
+  instead. A key that changes is restored as any new key is, so both
+  `forget` alone and `forget` with a new key are safe at a change of principal.
 - **Nothing is saved before its own key is restored.** `Hydrated` records the
   key it came from in `model.remote.restoredFrom`. Until that key is restored,
   nothing is saved, so the empty store at startup cannot overwrite the
@@ -1854,12 +2393,92 @@ See [`foldkit-remote-server`](../remote-server) for Source and authorization
 rules, and [`examples/kitchen-sink`](../../examples/kitchen-sink) for the real
 server packages together.
 
+## Clients and transports
+
+Every client is a `Layer<RemoteClient>`, and Remote's semantics do not change
+with it: a read, a query, a write and a live stream mean the same over Effect
+RPC, JSON or a port. What differs is how each reports a request that did not
+get an answer.
+
+`Remote.json(send)` is the JSON client over any way of sending the request
+text; `Remote.http(url, { headers, fetch })` is it over `fetch`. `headers` is
+read for each request, so a token that changes reaches the next call.
+
+**Who is asking.** A 401 fails every call kind, a read, a query, a mutation or
+a live stream, with `_tag: 'Unauthenticated'` (and `reason` when the server
+gave one): the server could not tell who is asking. A 401 is read so whatever
+its body says. A 403 whose body does not say `forbidden` itself, as Remote's
+server's does, comes from middleware in front of it refusing a session (a
+bare `{ error }` included): it fails a mutation as `Forbidden` and any other
+call with the status. `RemoteData.denied(error)` reads a failure as
+`Unauthenticated` or `Forbidden`, typed, and as none for any other, so a view
+tells "sign in again" from "could not load" without comparing tags. Remote
+treats either as any failure: a read or query is `Failed`, and a live stream
+restarts with its backoff, refused again each time, until the application
+signs in again and calls `Data.forget`.
+
+The JSON clients carry no live data. For live data over the same `POST`s,
+`Remote.httpWithLive` keeps reads, queries, and mutations as `http` sends
+them and streams live requirements as a `text/event-stream` of changes;
+[`serveFetch`](../remote-server/README.md#over-fetch-workers) is the other
+end. Abandoning the stream aborts the request, which interrupts the
+subscription server-side.
+
+For a server in a worker or in the page (a sandbox), `foldkit-remote/port`
+speaks Effect's own RPC worker protocol over a `MessagePort`, so live data,
+typed errors and interruption cross it too.
+[`servePort`](../remote-server/README.md#over-a-messageport) is the other end:
+
+```ts
+import { port } from 'foldkit-remote/port'
+
+// A new conversation each time the protocol connects: one port here, the other to the server.
+const overPort = port(() => {
+  const channel = new MessageChannel()
+  worker.port.postMessage({ open: 'remote' }, [channel.port2])
+  return channel.port1
+})
+```
+
+It is a `Layer<RemoteClient>` like the others; a port that cannot be set up is
+a defect, not a failed read.
+
+**Nothing answered.** The client `RpcClient.make(RemoteRpc)` builds is
+accepted as it is. When its transport fails, a read, a
+query or a live stream fails with its own Remote error (`RemoteReadError`,
+`RemoteQueryError`, `RemoteLiveError`), which the UI shows and retries like any
+other failure. A mutation fails with `RemoteUnreachable` (`_tag:
+'Unreachable'`): nothing answered, so the server may or may not have run it.
+`RemoteData.isUnreachable(error)` asks that of a failure without comparing tags.
+`Remote.json`, `Remote.http` and `Remote.httpWithLive` say the same of a
+request they could not send, and of a response that is no Remote answer: a
+body that is not JSON, JSON that is not `{ result }` or `{ error }` (a
+gateway's `{}`), or a response with status 408, 429, 502, 503 or 504, which
+Remote's server never answers with. Each is a `RemoteJsonClient`, a
+`RemoteRpcClient` whose transport error is `RemoteUnreachable`. A mutation the
+server failed is a `RemoteMutationError`. The difference matters for a [durable write](#a-write-that-outlives-the-page-dataoutbox):
+an `Unreachable` one is sent again, a refused one is settled `Failed`.
+
+**Testing a server over HTTP.** Call it as the application does: give
+`` Remote.http(`${origin}/remote`, { headers, fetch }) `` the server's address
+(miniflare's `(await mf.ready).origin` for a Worker) and call
+`FoldkitRemoteRead`, `FoldkitRemoteQuery` and `FoldkitRemoteMutate` on it, as
+`examples/cloudflare/src/client.ts` does over its local stack. To speak the
+wire yourself, each `POST` body is one of these, `version` being
+`REMOTE_PROTOCOL_VERSION`:
+
+```json
+{ "operation": "read", "payload": { "version": 5, "requests": [{ "entity": "Post", "id": "p1", "fields": ["title"] }] } }
+{ "operation": "query", "payload": { "query": "PostsByAuthor", "input": { "authorId": "a1" }, "window": { "first": 20 } } }
+{ "operation": "mutate", "payload": { "requestId": "r1", "mutation": "RenamePost", "input": { "id": "p1", "title": "Hello" } } }
+```
+
 ## Introspection
 
 Remote exposes its decisions as data rather than requiring DevTools to reach
 into private state:
 
-```ts
+```ts sketch
 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
@@ -1886,6 +2505,52 @@ asked. That is deliberate. Runtime activity is not a second source of truth
 here, and a view that rendered from it would stop being reproducible from the
 Model.
 
+### Diagnostics
+
+What Remote meets and keeps going past is recorded in the Model, typed, as
+`model.remote.diagnostics` (and `Data.inspect(model).diagnostics`), oldest
+first, the newest 256 kept:
+
+| `_tag` | When |
+| --- | --- |
+| `PredictionMismatch` | Under `verifyPredictions`, an answer disagreed with what the client predicted: a field's value (`Value`), a list's order (`Placement`), or a field left out (`Gap`). |
+| `WriteUnheard` | A write failed, and the wiring does not share `MutationFailed`. |
+
+Each carries its facts, `source: 'foldkit-remote'`, a `level` and a `message`
+to log. The reducer only records them, since it is pure. The wiring's route and
+`Remote.fold` report what each update recorded, with a Command that hands them
+to the `Diagnostics.Reporter` in the runtime's Effect context and answers
+`CompletedReportDiagnostics`, which changes nothing. With no reporter given,
+that is Effect's log in the browser's console: `console.error` for an `error`
+diagnostic, `console.log` for a `warning`, as all of Remote's are. An
+application that reduces Remote's Messages by hand (`Data.reduce`) has them in the Model, and
+nothing reports them.
+
+`Diagnostics` is `foldkit-surface`'s, re-exported here; server packages report
+into the same channel. Another reporter goes in the runtime's resources:
+
+```ts
+const resources = Layer.mergeAll(
+  Remote.clientLayer(Remote.http('/remote')),
+  // Logged as by default, and sent on to the server.
+  Layer.succeed(Diagnostics.Reporter, diagnostic =>
+    Effect.andThen(
+      Diagnostics.log(diagnostic),
+      Effect.sync(() => navigator.sendBeacon('/diagnostics', diagnostic.message)),
+    ),
+  ),
+)
+```
+
+In a test, assert on the Model, `[]` included:
+
+```ts
+expect(Data.inspect(model).diagnostics).toEqual([])
+```
+
+Nothing a diagnostic records changes what Remote does: a read, a write and a
+placement behave the same whether one is recorded or not.
+
 ### Explaining one query read
 
 A query read is assembled from more pieces than it looks like: a definition, an
@@ -1935,6 +2600,115 @@ There is still no **executor**, because what answers a query is a
 purity that lets this be replayed from a recorded Model is what keeps it out of
 reach.
 
+## Testing what a reader sees: `Trace`
+
+"A list on screen never blinks to `Loading`" depends on the reducer, the read
+entries and the order answers land in. `foldkit-remote/testing` checks it in
+Vitest, with no browser. `Trace.run` runs your `update` and the domain's own
+Subscriptions from a Model. It **holds** every request they make. Each step is
+one of your Messages, or a `Respond` that lets one held request go on, answered
+by the `RemoteClient` you pass. Every Model in between is recorded, so a
+regression that lasts one Message cannot fall between samples.
+
+```ts
+import { Respond, Trace } from 'foldkit-remote/testing'
+
+const trace = await Trace.run(Data, {
+  start: loaded, // a Model showing the list
+  update,
+  active,
+  client: server, // a fake, or your server's in-process client
+  steps: [
+    Message.Created({ id: 'p2', name: 'Two' }),
+    Respond.mutation(Create), // the answer lands first
+    Respond.read(Project, 'p2'), // then the new row's fields
+  ],
+})
+
+expect(Trace.regressions(trace, { list })).toEqual([])
+expect(Trace.tags(trace, list)).toEqual(['Ready', 'Refreshing', 'Ready'])
+```
+
+- **The trace decides when; the client decides what.** `Respond.query(ref)`,
+  `Respond.read(Entity, id)` and `Respond.mutation(M)` each answer the oldest
+  held request of their kind, and each takes `{ fail }` to answer with an
+  error instead. `Respond.all` answers everything held, and what that leads
+  to, until nothing is. Reorder the steps to try another interleaving.
+- **`Trace.regressions`** names each time a read that showed a value read
+  `Loading`, `Initial`, or `Failed` without it. It gives the step, the Message
+  and `Data.why`; it is `Data.timeline` over the trace, kept to its
+  regressions. `NotFound` is not a regression, since the server said the row
+  is gone. **`Trace.tags`** is each change of a read's tag.
+- **It fails loudly.** A `Respond` that matches nothing held throws and lists
+  what is held. A request abandoned by a restart is no longer held. A
+  Subscription or Command that dies throws. An `update` that does not take
+  Remote's Messages is a type error.
+- **What it leaves out.** Its clock stands still, at `now` (0 unless given):
+  every Command it runs and every answer it asks for reads that time
+  (`Remote.now`, an answer's date), and a retention `grace`, an age-out and a
+  live restart never fire. A live stream sends nothing, so
+  script its events as `LiveReceived` Messages. Only Remote's Commands run,
+  and `entry.skipped` names the others. It drives a domain whose Messages are
+  in your union, not a `Remote.fold`.
+- **Durable writes need the outbox.** Pass `outbox` (your `Data.outbox`
+  wiring) and the trace starts from its `restore`, over an empty store of its
+  own, and runs its Subscriptions as one tab: a durable write is stored and
+  sent by it, and `Respond.mutation` answers that send.
+
+## Testing that a prediction is the truth: `Law`
+
+A declared write is interpreted twice: by `Data.mutate`, in memory, over what
+the client holds (what it shows while the write is pending), and by the
+server, in SQL (what it stores). The law between them: **where the client
+predicts a part, the server's answer equals it**, while the write is pending
+and again once its answer has landed and the prediction is released.
+`Law.check` runs one operation through both, as an application does, and
+compares:
+
+```ts
+import { Law } from 'foldkit-remote/testing'
+
+const report = await Effect.runPromise(
+  Law.check(Data, {
+    model: { remote: Remote.initial, me: 'u1' }, // whom Remote.make's viewer reads
+    holds: [{ entity: Card, ids: ['c1', 'c2'] }], // read whole, as the principal
+    lists: [ByRank.ref({})], // loaded whole; their placements compared
+    mutation: AddCard,
+    input: { id: 'c9', title: 'delta', rank: 3, votes: 0 },
+    now: 1_000_000,
+  }).pipe(
+    Effect.provide(Remote.clientLayer(RemoteServer.handlers(server, 'u1')).pipe(Layer.provide(db))),
+  ),
+)
+expect(report.disagreed).toEqual([])
+expect(report.agreed).toEqual(expect.arrayContaining(['Card:c9.createdAt', ByRank.ref({}).identity]))
+```
+
+- **Nothing is stubbed.** The rows in `holds` are read through the server as
+  its principal sees them and reduced into the Model, so the client holds what
+  the server would send it; the lists are queried and merged; `Data.mutate`
+  predicts; its own Command sends the write. Each row the request's layer
+  changed is read back, every list queried again, and compared twice: with
+  the Model as it showed the write (`when: 'pending'`) and with the Model
+  once the answer is reduced into it (`when: 'answered'`). A part is agreed
+  only when both agree. A field the answer left out, which the client would
+  read again, is not compared once answered; a list the answer left stale is
+  fetched again, and is not either.
+- **A part is `Entity:id.field`, `Entity:id`** (whether the row is there) **or
+  a list's identity.** What the client left to the server (a field it could not
+  work out, a list with a row it could not judge) is in `unknown`, and is not
+  compared.
+- **Pin the server's clock to `now`** (a `Clock` service, or `TestClock`), or a
+  `now` outside the server's `clockSkew` is replaced by its own, and every time
+  the write sets disagrees.
+- **A refusal is a part too.** A write the client refused itself (a broken
+  invariant) is still sent to the server, which must refuse it alike; one the
+  server refuses after the client showed it is a disagreement.
+- **It fails when it compared nothing**, as for a mutation the client foresees
+  nothing of: two sides that both said nothing agree, and that is no evidence.
+  Name the parts you expect compared, as above, so a prediction that silently
+  stops is caught too.
+
 ## Advanced: the kernel
 
 Everything above compiles to the lower-level exports below; there is not a
@@ -1949,7 +2723,9 @@ place in an application Model. It exposes the Remote `Model`, `initial`,
 `RemoteServer.validate`.
 
 `Remote.at(definition, modelRef)` binds that domain to a `ModelRef`;
-`Remote.make` combines definition and binding in one step.
+`Remote.make` combines definition and binding in one step. Either one's
+`store` is the ref's `Focus` (`ModelRef.focus(modelRef)`): its `get`, `set`
+and `dependency`, which `foldkit-sync` and the law checks read.
 
 `Entity.make(name, schema)` is Remote's own entity descriptor, and what a
 `foldkit-entity` Entity is compiled to (`Entity.from`). Remote accepts either
@@ -2087,11 +2863,15 @@ and orders by, so the rows it holds can be compared with one that changed.
 
 ```ts
 // Schematic: `ProjectsByRank` is a Query.define ordered by a number, and
-// `connection` one of `remote.connections`. test/placement.test.ts runs it.
-placeIn(remote.entities, connection, ProjectsByRank.body!, {}, 'Project:p7')
+// `connection` one of `remote.connections`; `Operators` is foldkit-entity's.
+// test/placement.test.ts runs it.
+placeIn(remote.entities, connection, ProjectsByRank.body!, {}, 'Project:p7', Operators.kernel)
 // Before { segment, edge } | End { segment } | Outside | Unknown { reason }
 ```
 
+The last argument is the operator table the body's calls run by, the one
+`Remote.make`'s `operators` names (`Operators.kernel` by default).
+
 - `Before` and `End` are positions among loaded edges: before an edge, or at
   the end of a segment that ends the list (`Terminal`).
 - `Outside` is a row that sorts past a `Cursor` boundary or into a gap between
@@ -2116,8 +2896,9 @@ a request passes the one it first sent.
 `MutationSucceeded` reconciles at most once per `requestId`; an unknown or
 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.
+freshness policy ages them from then. `Data.mutate`, `Remote.mutateInto` and
+the outbox stamp it from Effect's `Clock` when the answer lands, never from the
+`now` option, which is the write's time sent to the server.
 
 ### The transport seam
 
@@ -2147,6 +2928,7 @@ Remote owns:
 - the `Remote.Model` Submodel and its reducer;
 - query connections and pagination boundaries;
 - optimistic mutation overlays and idempotent settlement bookkeeping;
+- the outbox of durable writes: stored, sent in order by one tab, sent again;
 - live cursors, duplicate suppression, and gap detection;
 - retention/garbage collection of disposable cache data;
 - deterministic, scoped cache snapshots;
@@ -2157,26 +2939,30 @@ Remote does **not** own:
 
 - your source database or authoritative server records;
 - local UI/application state outside `Remote.Model`;
-- durable offline client intent or replica convergence;
+- client-authored state that converges across devices, or replica convergence;
 - HTTP/WebSocket deployment details;
 - authentication; server-side authorization belongs at the Source boundary;
 - a background scheduler or general-purpose database/query engine.
 
 ## Limits
 
-- Effect RPC is the wire contract; the application supplies deployment layers.
-  `ReadBatch` and `LiveRequirement` carry `REMOTE_PROTOCOL_VERSION`, and a
-  mismatched version fails with `RemoteProtocolError` rather than silently
-  drifting.
+- `RemoteRpc`'s schemas are the wire contract, carried by Effect RPC, by JSON
+  over `POST` (`Remote.http`), or over a `MessagePort`; the application
+  supplies deployment layers. `ReadBatch` and `LiveRequirement` carry
+  `REMOTE_PROTOCOL_VERSION`, and a mismatched version fails with
+  `RemoteProtocolError` rather than silently drifting.
 - One request may name at most `MAX_FIELDS_PER_REQUEST` (256) fields of one
   entity and nest relations at most `MAX_RELATION_DEPTH` (8) levels; the wire
-  rejects larger inputs.
+  rejects larger inputs. A live stream carries at most `MAX_LIVE_QUERIES` (32)
+  lists, and a `many` relation read whole is bounded by the server's Source
+  (`maxCollection` in `foldkit-remote-drizzle`).
 - The wire `LiveChange` union carries entity patches/deletes and connection
   insert/remove/invalidate changes; `RemoteServer.live` serves them as a stream.
 - Coalescing is scoped to one `RemoteClient` layer. Separate layers do not share
   batches.
-- Retention keeps what active Surfaces (and explicit retain entries) reach. An
-  inactive/unretained Surface may lose its cache on `RetentionChanged`.
+- Retention keeps what active Surfaces (and explicit retain entries) reach, and
+  what the most recently left ones reached, up to `departedLimit`. Past it, an
+  inactive Surface loses its cache on `RetentionChanged`.
 - Two applications with the same Model type are not distinguishable by TypeScript
   alone; `Data.subscriptions` also checks the Surface owner token at runtime.
 - `staleWhileRevalidate({ maxAge })` ages entity data. Connections have no age;
@@ -2189,6 +2975,9 @@ Remote does **not** own:
 
 - [Server-derived state](../../docs/remote.md) — the deeper architectural guide
   and ownership model.
+- [Errors and failures](../../docs/errors.md) — how a read's, a write's and
+  every other package's failures fit together: who owns each, what the reader
+  sees, what the application does.
 - [`foldkit-remote-server`](../remote-server) — server Sources, resolution, and
   semantic-field authorization.
 - [`foldkit-remote-drizzle`](../remote-drizzle) — optional compilation of Remote