foldkit-remote 0.4.0 → 0.6.0

package/README.md

@@ -55,67 +55,17 @@ ownership.
 
 ## The mental model
 
-The client side is a Foldkit Submodel:
-
-```text
-                         pure
-                    Projection read
-                         |
-                         v
-+-------------+     +---------+      +------+
-| Foldkit     |---->| Surface |----->| View |
-| Model       |     +---------+      +------+
-|             |
-| Remote.Model|
-| normalized  |
-| cache       |
-+------+------+ 
-       ^
-       | Remote Message
-       |
-+------+-------+
-| Data.reduce |
-+------+-------+
-       ^
-       |
-       | read/query/mutate/live
-       |
-+------+--------+
-| RemoteClient |
-+------+--------+
-       |
-       v
-     server
-```
-
-The other half of the model is the **requirement planner**:
-
 ```text
-Surface says:
-  "I need Project p1: id, name, owner.name"
-
-                    |
-                    v
-Remote compares that requirement
-with the normalized cache in Model
-
-                    |
-                    v
-missing:
-  Project:p1.name
-  User:u7.name
-
-                    |
-                    v
-active subscription performs one read
-
-                    |
-                    v
-result -> Remote Message -> Data.reduce -> Model
+Surface Projection → requirements → active Subscription → RemoteClient I/O
+        ↑                                                    |
+        └──────── read Model ← Data.reduce ← Remote Message ──┘
 ```
 
-That separation is why reading stays pure. Rendering a Surface never starts a
-request.
+A Projection reads the current cache and carries requirements such as
+`Project:p1.name` and `User:u7.name`. An active Subscription compares those
+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
 
@@ -133,7 +83,7 @@ Everything else builds on those four pieces.
 ## Install
 
 ```bash
-pnpm add foldkit-remote
+pnpm add foldkit-remote foldkit-entity
 ```
 
 `foldkit` and `effect` are peer dependencies; `foldkit-surface` comes with the
@@ -145,9 +95,9 @@ Start with one server entity and one selection:
 
 ```ts
 import { Schema } from 'effect'
-import { Entity } from 'foldkit-remote'
+import { Entity } from 'foldkit-entity'
 
-const Project = Entity.make(
+const Project = Entity.define(
   'Project',
   Schema.Struct({
     id: Schema.String,
@@ -157,12 +107,20 @@ const Project = Entity.make(
 )
 
 // A Selection is the exact server-owned shape this consumer needs.
-const ProjectSummary = Project.select({
+const ProjectSummary = Entity.select(Project, {
   id: true,
   name: true,
 })
 ```
 
+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.
+
 Embed Remote's Submodel in the application and bind the domain to that field:
 
 ```ts
@@ -283,7 +241,14 @@ Remote.Model
 ProjectPage now reads Ready(...)
 ```
 
-Finally, provide the client implementation to the runtime:
+The first example starts on the `home` route, so no project read runs yet.
+Your route update must activate `{ _tag: 'project', projectId: 'p1' }`, and the
+runtime must install `subscriptions`. Expect `Initial` until work starts,
+`Loading` during the first request, and `Ready` once its result is reduced.
+
+Finally, provide the client implementation to the runtime. Here `rpcClient`
+is your configured Effect RPC client, not a value created by the declarations
+above; the [server guide](../remote-server/README.md) supplies the other side:
 
 ```ts
 const clientLayer = Remote.clientLayer(rpcClient)
@@ -346,15 +311,19 @@ missing ------------------------------------------------> Loading
 
 server says entity is absent ---------------------------> NotFound
 stored value fails Selection decoding -----------------> Failed
+a read or a list's query fails ------------------------> Failed (with the old value, if any)
 ```
 
 The states are:
 
 - **`Initial`** — required data is absent and **nothing is currently fetching it**.
-- **`Loading`** — required data is absent and a read is in flight.
+- **`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.
-- **`Failed`** — stored server data does not decode against the Selection.
+- **`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`.
 - **`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
@@ -371,6 +340,46 @@ state that actually means "wait for this request."
 `RemoteData.match` is exhaustive, so adding or omitting a state is visible at
 compile time.
 
+### Drawing one: `RemoteData.render`
+
+Most views draw these six states three ways, under one policy: useful data
+stays on screen. `RemoteData.render` is that fold.
+
+```ts
+RemoteData.render(project, {
+  loading: () => ProjectSkeleton(),
+  notFound: () => NoSuchProject(),
+  failed: error => ErrorView(error),
+  data: (value, freshness) =>
+    ProjectView({ project: value, dimmed: freshness._tag !== 'Fresh' }),
+})
+```
+
+`Initial` and `Loading` reach `loading`; `Ready` and `Refreshing` reach `data`;
+a `Failed` that still carries the value it had reaches `data` too, so a read
+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:
+
+| `Freshness` | What it means |
+| --- | --- |
+| `Fresh` | This is the current answer. |
+| `Refreshing` | A newer answer is on its way; this one is still good. |
+| `Stale` | A read failed; this is what was last known good, with its `error`. |
+
+It is one tag rather than a pair of booleans because a value cannot be both
+refreshing and stale, and a type that can say so invites a view to handle a
+state that never arrives.
+
+`notFound` is its own branch and not optional. A row the server answered for
+and does not have is neither loading nor a failure; drawing it as either is a
+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.
+
 ## Normalized entities and selections
 
 Remote stores an entity once by identity, regardless of how many Surfaces read
@@ -444,7 +453,9 @@ const card = Data.get(ProjectCard, 'p1') // Projection<Model, RemoteData<{ name;
 
 - A relation becomes a ref field: `one` a ref, an optional `one` a nullable ref,
   `many` an array of refs. A derived member becomes a field the server supplies.
-- The Entity needs an `id` field; Remote keys the store by it.
+- The Entity needs an `id` field; Remote keys the store by it. When that field
+  is branded, `Data.get` and `Data.live` take that type for an Entity Selection:
+  another Entity's id, or plain text, does not compile.
 - Register the Entities of one `Entity.relate` result and select from that same
   result; `Object.values(Work)` registers them all.
 - `Entity.from(entity)` and `Selection.from(selection)` are the compile steps,
@@ -452,9 +463,14 @@ const card = Data.get(ProjectCard, 'p1') // Projection<Model, RemoteData<{ name;
   handler.
 - `Entity.page(selection, window)` in an Entity Selection is Remote's
   `Selection.connection`: the window travels with the read, and the server
-  answers with a page of refs. One relation of one entity is held whole or as
-  one window at a time, so two views of the same entity should not read the
-  same relation both ways at once.
+  answers with a page of refs. A page of a whole list is read under a name of
+  its own, `comments@first=10`, so one view can show every comment while another
+  shows the first ten of the same post: they are two fields to the store, fetched
+  in one batch, merged and refreshed each on its own. A write to the list (a
+  mutation's patch, a live change) marks its pages stale, so they are read again.
+  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 `@`.
 
 `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
@@ -509,6 +525,24 @@ 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`:
 
@@ -521,8 +555,9 @@ case 'ClickedRefresh': {
 ```
 
 `Data.refresh` performs no I/O and restates no request. It returns the Model
-with every selected field the store holds reading `Refreshing` and every loaded
-connection invalidated; the `Data.subscriptions` read entries then refetch it,
+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,
 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`.
@@ -555,6 +590,52 @@ const Data = Remote.make({
 })
 ```
 
+`Query.make` names a query and says what it returns. Where it *means*
+something the client should be able to state, declare it with a body instead:
+
+```ts
+import { Entity, Expr, Order, Query } from 'foldkit-entity'
+
+const Task = Entity.define(
+  'Task',
+  Schema.Struct({ id: Schema.String, ownerId: Schema.String, updatedAt: Schema.Number }),
+)
+
+const TasksByOwner = Query.define(
+  'TasksByOwner',
+  { ownerId: Schema.String },
+  ({ input }) =>
+    Query.from(Task).pipe(
+      Query.where(Expr.eq(Task.fields.ownerId, input.ownerId)),
+      Query.orderBy(Order.desc(Task.fields.updatedAt), Order.asc(Task.fields.id)),
+    ),
+)
+```
+
+A body is written over a [`foldkit-entity`](../entity) Entity, because that is
+what has addressable fields: `Task.fields.ownerId` is a reference an `Expr` can
+be built from, where this package's own `Entity.make` describes a field as the
+schema of its value and has nothing to point at. An entity declared either way
+still reads, selects and normalizes the same; only a query body needs the
+richer declaration.
+
+What comes back is an ordinary descriptor — the same name, `Input`, `ref` and
+connection identity — carrying its `body` besides, and the result is a
+connection over the Entity the body reads, so it is not named twice. A server
+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.
+
+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
+comparison over the placeholder, never a `?:` around it.
+
+`Input` must be fields or a plain `Schema.Struct`, because that is what the
+placeholders are made from. A codec that exposes no keys is refused where the
+query is declared rather than handing the body an empty object, which would
+compare a column to nothing while every type agreed.
+
 Then a query is still just a Projection:
 
 ```ts
@@ -586,6 +667,159 @@ their required fields. `Data.next` / `Data.previous` preserve the page size and
 use the loaded boundaries; `hasNext` / `hasPrevious` come from those boundaries,
 not from guessing based on row counts.
 
+### Filtering a loaded list without asking the server
+
+A search box over a page you already have should not be a round trip.
+`Data.filtered` narrows a loaded list by a query body:
+
+```ts
+const found = Data.filtered(model, projects, ActiveProjects, {})
+
+found.items     // decoded exactly as the list decodes them
+found.complete  // whether the answer was about the whole list
+```
+
+**It filters a list; it does not run a query**, and the distinction is the
+design. "Which rows match" would need to know this list holds every row the body
+could match — predicate containment, which Remote deliberately does not do.
+"Which rows *of this list* match" is decidable from what is already here.
+
+`complete` is false unless three things hold: every edge could be judged (no row
+missing a field the *body* reads), every match could be shown (no row missing a
+field the *Selection* reads), and the list is terminal at both ends. So
+empty-and-complete and empty-and-partial stay different answers — one means
+"none", the other means "none that I can see yet".
+
+Nothing is created: no connection, nothing new to retain, nothing new to fetch.
+The server stays authoritative for which rows exist.
+
+### Judging the rows you already hold
+
+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:
+
+```ts
+const judged = Remote.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
+```
+
+It is pure, and it runs the **same interpreter the server checks itself
+against** — the reference implementation in
+[`foldkit-entity`](../entity) — so a body means one thing in both places. The
+conformance suite is run over a store as well as over rows and a table.
+
+Three things about it are deliberate.
+
+**It answers "which of the rows I hold match", never "which rows match."** Those
+are different questions, and the difference is not recoverable from a list of
+keys — so it is in the shape. A caller that knows it holds the whole population
+(a connection terminal at both ends) is the one that can turn this into a
+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
+"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.
+
+**It takes the input decoded and encodes it itself.** A store holds wire values,
+so a comparison has to happen in that space — and handing an interpreter a
+decoded value is a mistake *no runtime error catches*: the answer is simply
+empty, which reads exactly like a correct one. Doing the encoding here means a
+caller cannot get it wrong.
+
+It is **not authorization**. On the server a compiled `where` is conjoined with
+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.
+
+### An input that changes as fast as someone types
+
+A connection's identity is its query plus its **input**, which is exactly right
+for caching and exactly wrong for a search box. Bound naively, every keystroke
+is a different connection, a different request, and a different thing to retain:
+
+```ts
+// Don't: `postSearch` changes per keystroke, so the query's input does too.
+h.OnInput(text => Message.Searched({ text }))
+```
+
+Remote has no debounce, and should not: its job is to be a faithful function of
+the Model, so if the Model says the search is `Engi` then `Engi` is what the
+query asks. **The debounce belongs between the input Message and the Model field
+the query reads** — which is ordinary application state, and
+[`foldkit-primitives`](../primitives) already has the piece:
+
+```ts
+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, {
+  args: { delayMs: 250 },
+  onOut: out => model => ({ model: evo(model, { postSearch: () => out.value }) }),
+})
+```
+
+Two fields, deliberately: the one the box draws changes on every keystroke, and
+the one the query reads changes a quarter second after the last one.
+[`examples/entity`](../../examples/entity) does exactly this.
+
+The same applies to any high-frequency query input — a slider, a map viewport, a
+date scrubber. What makes a search box the usual case is that the query is often
+written *for* it: `Expr.contains` over an empty string matches everything, so an
+empty box and a filled one are one query rather than two.
+
+### A page that overruns its window is refused
+
+The client asks for `first: 25`, and a page carrying more than that is a
+protocol disagreement rather than a windfall: the client cannot tell which of
+the edges the window meant, and the connection's boundaries stop describing what
+it holds. Such a page becomes a `QueryFailed` with a named protocol error, and
+none of its edges reach the store — a connection already loaded is left exactly
+as it was, so a refresh that overruns cannot replace good rows with a rejected
+page.
+
+A window with neither `first` nor `last` bounds nothing: `after`/`before` says
+where to start, not how much to take.
+
+### When a read fails
+
+A failure is kept on the Model until something settles it, and the read says
+so. Queries fail per connection, and entity reads per field. A read with
+nothing to show reads `Failed` with the error. One that had a value (a failed
+refresh, or a failed "load more") reads `Failed` with that value as
+`previous`, which `RemoteData.render` draws as data with a `Stale` freshness,
+so it stays on screen. A failure reaches every read that needs it: a list
+fails when one of its rows' fields failed, and a project read fails when its
+owner's did.
+
+**It is not retried on its own.** A persistent error would otherwise be asked
+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.
+- 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.
+- Retention dropping it: something nothing reads any more forgets its failure,
+  so coming back to it later asks the server again.
+
+`Remote.inspect(model.remote).failures` lists what failed, by connection
+identity and by `entity\0id\0field` mark.
+
+A broken live stream is not a failed read. Its `ReadFailed` carries the
+`stream`, and records a gap in `RemoteModel.gaps` rather than failing any
+field: nothing was being read, and the values on screen are still what the
+server last said.
+
 ## Mutations and optimistic state
 
 Register mutations on the domain:
@@ -663,6 +897,41 @@ 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.
 
+### Reading past what is only pending
+
+Every projection reads the **visible** cache: the server-derived store under
+the layers still pending, which is why an optimistic change shows at once. A
+reader that must not believe a change until the server has agreed to it asks
+for the confirmed read instead:
+
+```ts
+Data.confirmed(Data.get(ProjectSummary, projectId))
+```
+
+It is the same projection — the same requirements, planned the same way, so
+observing it fetches exactly what observing the original fetches — reading the
+server-derived store alone, with the pending layers and connection overlays
+left off. An optimistically inserted edge is not in its page; an
+optimistically patched field reads as the server last said.
+
+A view almost always wants the projection itself. This is for the reader that
+reports on the world rather than drawing it, which in practice is an Agent
+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,
+})
+```
+
+There is deliberately no `Data.visible`: a projection already is the visible
+read, and a second name for it would be a wrapper that only forwards.
+
+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).
+
 ### Remote mutation vs Sync operation
 
 Do not use Remote mutation as a durable offline-write mechanism:
@@ -727,27 +996,34 @@ and refetch; Sync recovery must preserve unsent client intent.**
 
 ## Persistence and hydration
 
-Persist only the disposable entity cache, not session machinery such as live
-cursors, optimistic layers, mutation bookkeeping, gaps, or retention roots.
+A snapshot is `{ entities, connections }`. The entity cache is disposable and
+always goes; a connection goes only if named, and keeps its edges alone — never
+a cursor, which may name server state that is gone. Session machinery (live
+cursors, optimistic layers, mutation bookkeeping, gaps, retention roots) is
+never in one.
 
 ```ts
-import { emptyStore, RemotePersistence } from 'foldkit-remote'
+import { RemotePersistence } from 'foldkit-remote'
 
 // SSR: prefetch on the server, embed, then hydrate on the client.
-const snapshot = RemotePersistence.dehydrate(
-  Data.storeOf(loaded),
+// `snapshotOf` names the connections that survive; none, here.
+const text = RemotePersistence.dehydrate(
+  RemotePersistence.snapshotOf(loaded.remote),
   { scope: userId },
 )
 
+const restored =
+  RemotePersistence.hydrate(text, { scope: userId }) ?? RemotePersistence.emptySnapshot
+
 Data.reduce(model, {
   _tag: 'Hydrated',
-  entities:
-    RemotePersistence.hydrate(snapshot, { scope: userId }) ?? emptyStore,
+  entities: restored.entities,
+  connections: restored.connections,
   merge: 'preserve-existing',
 })
 
 // Or persist through Effect's KeyValueStore.
-RemotePersistence.save(store, {
+RemotePersistence.save(RemotePersistence.snapshotOf(model.remote), {
   key: 'remote-cache',
   scope: userId,
   maxBytes: 512_000,
@@ -811,6 +1087,22 @@ 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
@@ -819,6 +1111,7 @@ into private state:
 ```ts
 Data.inspect(model)            // serializable cache/domain summary
 Data.plan(model, projection)   // the entity plan a read would execute
+Data.explain(model, query)     // what one query read is, and currently is
 Remote.planQueries(...)        // missing/stale query work
 Remote.inspectEntity(...)      // one normalized entity
 ```
@@ -828,6 +1121,62 @@ useful question is: **"Why is this Projection still Initial?"** `Data.plan`
 shows whether Remote believes anything is actually missing; active Surface
 wiring determines whether that plan is being executed.
 
+`Data.inspect(model).loading` answers the other one — **"what is Remote doing
+right now?"** — with the `entity\0id\0field` marks of the reads in flight,
+beside `mutations.pending` for the writes. Both are read from the Model, not
+from the fibers doing the work: a tool that shows them shows something a
+recorded Model can be replayed to, and nothing that needs the runtime to be
+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.
+
+### Explaining one query read
+
+A query read is assembled from more pieces than it looks like: a definition, an
+input, a connection identity that excludes the window, a window that does not,
+and a Selection that is a slice asked of the server. `Data.explain` puts them in
+one serializable value, beside what the read answers from this Model right now:
+
+```ts
+Data.explain(model, projects)
+// {
+//   domain: 'remote',
+//   query: 'ProjectsByOwner',
+//   input: { ownerId: 'u1' },
+//   identity: 'ProjectsByOwner\u0000{"ownerId":"u1"}',
+//   window: { first: 25 },
+//   select: { entity: 'Project', fields: ['id', 'name'] },
+//   body: 'FROM Project\nWHERE Project.ownerId = $ownerId\nORDER BY Project.name DESC',
+//   dependencies: { fields: [...], inputs: ['ownerId'], operations: ['eq'] },
+//   state: 'Ready',
+// }
+```
+
+`body` is the query's meaning as readable text, and it is neither SQL nor
+whatever the backend compiled — an input shows as `$ownerId` rather than a bound
+parameter, and `contains` is named rather than rendered as somebody's `like`. A
+definition made with `Query.make` has no `body`, because its meaning lives on
+the server that answers it.
+
+`state` comes from the projection's own read, so an explanation and the view
+cannot disagree about whether the data is there.
+
+A Projection cannot say which Surfaces read it — several may — so pass the
+active record `subscriptions` takes and `explain` reports all of them, plus why
+each is active where that is a readable fact (`Surface.when`) rather than a
+callback (`Surface.at`):
+
+```ts
+Data.explain(model, projects, { surfaces: actives })
+// surfaces:   ['ProjectPage']
+// activation: [{ surface: 'ProjectPage', path: ['route'], tag: 'Project' }]
+```
+
+There is still no **executor**, because what answers a query is a
+`RemoteClient` Layer in the runtime rather than a value in the Model — the same
+purity that lets this be replayed from a recorded Model is what keeps it out of
+reach.
+
 ## Advanced: the kernel
 
 Everything above compiles to the lower-level exports below; there is not a