@jsenv/navi 0.29.418 → 0.29.419

package/docs/resource.md

@@ -29,9 +29,8 @@ Each callback returns the data to upsert into the store:
 
 Actions are read in components through the action system (`useAsyncData`,
 `<Button action>`, …) — see [actions.md](./actions.md). An action's `data` is
-`undefined` until its callback has answered once, plural verbs included: a
-`GET_MANY` that has not run has no array, and `[]` is what an empty answer
-looks like ([data_states.md](./data_states.md#data-and-loading-are-independent)).
+`undefined` until its callback has answered once, plural verbs included
+([data_states.md](./data_states.md#data-and-loading-are-independent)).
 
 - [`store.upsert()` is not how data enters the store](#storeupsert-is-not-how-data-enters-the-store)
 - [`persist`: the last answer, drawn again after a reload](#persist-the-last-answer-drawn-again-after-a-reload)
@@ -39,11 +38,6 @@ looks like ([data_states.md](./data_states.md#data-and-loading-are-independent))
 - [Searching the same collection](#searching-the-same-collection)
 - [Relations: pick one of the four methods](#relations-pick-one-of-the-four-methods)
 - [Callback return contracts](#callback-return-contracts)
-  - [`.one(propertyName, childResource, { GET, PUT, DELETE })`](#onepropertyname-childresource--get-put-delete-)
-  - [`.many(propertyName, childResource, restCallbacks)`](#manypropertyname-childresource-restcallbacks)
-  - [`.scopedOne(propertyName, { idKey, GET, POST, PUT, PATCH, DELETE })`](#scopedonepropertyname--idkey-get-post-put-patch-delete-)
-  - [`.scopedMany(propertyName, { idKey, GET, GET_MANY, POST, PUT, PATCH, DELETE, … })`](#scopedmanypropertyname--idkey-get-get_many-post-put-patch-delete--)
-  - [A relation declared on a scoped child](#a-relation-declared-on-a-scoped-child)
 - [When the backend answers a sub-route with the whole parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)
 - [Relations and autorerun](#relations-and-autorerun)
 - [`withParams()`: a scope with reruns of its own](#withparams-a-scope-with-reruns-of-its-own)
@@ -54,10 +48,10 @@ looks like ([data_states.md](./data_states.md#data-and-loading-are-independent))
 ## `store.upsert()` is not how data enters the store
 
 navi writes the store. Declare the resource and its relations, return the shape
-each callback owes (tables above and below), and the write happens. A hand
-written `store.upsert()` in the path of a normal request of the resource is the
-sign that something is missing: a relation that is not declared, or a callback
-that does not return what it should.
+each callback owes, and the write happens. A hand-written `store.upsert()` in
+the path of a normal request of the resource is the sign that something is
+missing: a relation that is not declared, or a callback that does not return
+what it should.
 
 `store` is exposed for what is **not** a request of the resource, where writing
 it yourself is the point:
@@ -65,28 +59,23 @@ it yourself is the point:
 - seeding it with data that came from elsewhere — state rendered by the server,
   a websocket message (the resource's own last answer is not "elsewhere": that
   is [`persist`](#persist-the-last-answer-drawn-again-after-a-reload), below);
-- absorbing the parent object a relation route answered with: the relation
-  callback only writes the relation, so the parent's own fields have nowhere
-  else to land (see [When the backend answers a sub-route with the whole
+- absorbing the parent fields a **scoped** relation's route answered with: a
+  `.scopedOne()`/`.scopedMany()` callback writes the relation and nothing else
+  (see [When the backend answers a sub-route with the whole
   parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)).
 
-A list that loads its rows a slice at a time is **not** one of those cases — that is
-`GET_RANGE`, right below.
+A list that loads its rows a slice at a time is **not** one of those cases —
+that is `GET_RANGE`, below.
 
 ## `persist`: the last answer, drawn again after a reload
 
-Some `GET`s are the app. `GET /me` answers who is signed in, their things, what
-the header and the tab bar draw; until it lands, a page that is rendered has
-nothing to draw. On a reload, or when the app is reopened from the home screen,
-that wait is pure loss: the previous answer was on screen a moment ago and is
-almost always still true, and a server waking up makes it last seconds.
-
-What is wanted is the second line of the table in
-[data_states.md](./data_states.md#data-and-loading-are-independent) reached on
-a reload: the last known row drawn, the request out behind it, the fresh answer
-replacing it. `persist` names the resource whose answer is worth keeping, and
-the signal that keeps it — a `stateSignal` that persists, the primitive navi
-has for a state that survives a reload:
+Some `GET`s are the app — `GET /me` answers who is signed in, what the header
+and the tab bar draw — and on a reload, or an app reopened from the home screen,
+waiting for them is pure loss: the previous answer was on screen a moment ago
+and is almost always still true. `persist` puts that reload on the second line
+of the table in [data_states.md](./data_states.md#data-and-loading-are-independent)
+— the last known row drawn, the request out behind it — and names the signal
+that keeps the copy, a `stateSignal` that persists:
 
 ```js
 const mePersistedSignal = stateSignal(undefined, {
@@ -105,70 +94,50 @@ ME.one("user", USER);
 ME.many("my_games", GAME);
 ```
 
-From there navi does the rest:
-
-- **the rows `GET` lands with are written into the signal** — one per params
-  the `GET` was asked with, so a `GET` without params keeps one row. Where the
-  signal keeps its value is the signal's business: `persists: true` is
-  localStorage, and a plain `signal()` keeps it for the page's lifetime, which
-  is what a test wants;
-- **the first run of the `GET` draws the kept row.** It enters the store and
-  becomes the action's provisional value: `data` is set while `loading` is
-  `true`, the row is on screen and the request is out behind it. Nothing else
-  moves — `runningState` is `running`, the answer replaces the row, an error
-  lands in `errorSignal` beside it;
-- **the copy follows the store.** It is written with its relations inline — the
-  shape the `GET` callback returns, so it re-enters through the same setters a
-  real answer goes through — and rewritten whenever the row or a row it reaches
-  through a relation changes: a `PUT` on the item, a list upserting one of its
-  children, a game joining `my_games`. A rewrite that changes nothing is
-  skipped, so the signal moves only when the copy does;
-- **under a network policy answering reads from the store, the kept row answers
-  the `GET`** ([network_policy.md](./network_policy.md)): a reload with no
-  network reopens on the last answer rather than on nothing.
+The copy follows the store — a `PUT` on the item, a game joining `my_games`
+rewrite it — and the first run of the `GET` draws it as its provisional value:
+`data` set while `loading` is `true`, the answer replacing it. Under a network
+policy answering reads from the store, the kept row answers the `GET`
+([network_policy.md](./network_policy.md)): a reload with no network reopens on
+it. A plain `signal()` keeps the copy for the page's lifetime, which is what a
+test wants.
 
 What stays the app's, because only the app knows:
 
-- **the key.** A stored copy is only as good as the code reading it: a deploy
-  that changes the shape of the answer must not draw the old one. Put in the
-  signal's `id` whatever makes a copy unusable — the deployed version — and a
-  new id starts clean.
+- **the key.** A deploy that changes the shape of the answer must not draw the
+  old one: put in the signal's `id` whatever makes a copy unusable — the
+  deployed version — and a new id starts clean.
 - **`when`: is the copy about this session?** A tab viewing as someone else, an
-  account being switched — the row in the store is somebody's, and it must not
-  be kept for the next person. `when` is read whenever the copy is about to be
-  read or written: `false` reads nothing, writes nothing, and empties the
-  signal. It is a function so it can read a signal, and it has to: a plain
-  variable is only looked at again when the store changes.
-- **the moment, not the state.** Sign-out is not a condition that holds, it is
-  something that happens: writing `undefined` into the signal
-  (`mePersistedSignal.value = undefined`) forgets the copy at once, and nothing
-  is written until a `GET` lands again. The store rows stay — the screen keeps
-  what it shows until the app resets the action, as it does today.
+  account being switched — the row is somebody's, and must not be kept for the
+  next person. `when` is read whenever the copy is about to be read or written:
+  `false` reads nothing, writes nothing, and empties the signal. It is a
+  function so it can read a signal, and it has to: a plain variable is only
+  looked at again when the store changes.
+- **the moment, not the state.** Sign-out is something that happens, not a
+  condition that holds: writing `undefined` into the signal forgets the copy at
+  once, and nothing is written until a `GET` lands again. The store rows stay —
+  the screen keeps what it shows until the app resets the action.
 - **what the `GET` feeds beside its return value.** Counts, badges, a feature
-  flag set from the response are the app's signals, not the row; they are not
-  kept, and the callback does not run on a kept row. Anything the app wants
-  back before the answer, it stores itself.
-- **the veil.** A loading screen that waits on the `GET` being `running` stays
-  over the drawn row for the whole request. It waits on `data` being set —
-  the emptiness test of data_states.md — and the refresh is shown as usual.
+  flag set from the response are the app's signals, not the row: they are not
+  kept, and the callback does not run on a kept row.
+- **the veil.** A loading screen waiting on the `GET` being `running` stays over
+  the drawn row for the whole request. It waits on `data` being set — the
+  emptiness test of data_states.md — and the refresh is shown as usual.
 
 What the copy is not:
 
-- **an answer.** The `GET` goes out every time; the copy is a drawing aid. A
-  screen must not read `data` as "the server confirmed": that is `loading`,
-  and the two are independent.
-- **a store on disk.** One row per params key, `GET` only — a resource whose
-  `GET` is asked for every id would keep every id. It is meant for a singleton
-  or a handful of rows.
+- **an answer.** The `GET` goes out every time; a screen must not read `data` as
+  "the server confirmed" — that is `loading`, and the two are independent.
+- **a store on disk.** One row per params key, `GET` only: meant for a singleton
+  or a handful of rows, not a resource whose `GET` is asked for every id.
 - **seeded at declaration.** The row enters the store at the first run of the
-  `GET`, once the relations are declared, so that its relation values are
-  normalized into their stores as a real answer's are. `ME.store` read before
-  that first run is empty.
+  `GET`, once the relations are declared, so its relation values are normalized
+  as a real answer's are. `ME.store` read before that first run is empty.
 
 ## `GET_RANGE`: feeding a list that loads as it scrolls
 
 A `<List.Items>` asks for the rows it is about to draw and keeps what it gets.
-`GET_RANGE` is the resource's answer to that question — one slice at a time:
+`GET_RANGE` is the resource's answer to that question, one slice at a time:
 
 ```js
 const GAME = resource("game", {
@@ -188,18 +157,19 @@ const GAME = resource("game", {
 ```
 
 The callback receives the bound params merged with the range the list asks for
-(`start`, `end`, `limit`, `before`, `after`, `around`, `count`), and `{ signal }`
-as second argument — a signal aborted when the list stops wanting those rows.
-It returns a range the way a `Content-Range` does: **`{ items, start, count }`**
-— these rows, at this place, out of that many. `start` may be omitted when the
-list asked for one at or after `0` (a negative `start` counts back from the end,
-and the source must then say where the slice landed); `count` defaults to
-`start + items.length` (a source that does not know its total). The items are
-upserted on their way in, so the list draws store items — never copies of the
-JSON — and a request sent from a row is read back on that row.
-
-A row that must follow its **own fields** through a write reads them from the
-store rather than from the object it was handed:
+(`start`, `end`, `limit`, `before`, `after`, `around`), and `{ signal }`,
+aborted when the list stops wanting those rows. It returns a range the way a
+`Content-Range` does: **`{ items, start, count }`** — these rows, at this place,
+out of that many. `start` may be omitted when the list asked for one at or after
+`0` (a negative `start` counts back from the end, and the source must then say
+where the slice landed); `count` defaults to `start + items.length`. The items
+are upserted on their way in, so the list draws store items, never copies of the
+JSON.
+
+But the list keeps the object it was handed, and an update replaces the item
+object (the store holds values, which is what makes a change detectable). So a
+row that must follow its **own fields** through a write reads them from the
+store:
 
 ```jsx
 const GameCard = ({ id }) => {
@@ -208,41 +178,27 @@ const GameCard = ({ id }) => {
 };
 ```
 
-An update replaces the item object (the store holds values, and that is what
-makes a change detectable), so the one the list is holding is the one it was
-given. Relations are not concerned: they are keyed by owner, and a row reading
+Relations are not concerned: they are keyed by owner, and a row reading
 `game.candidates` reads the shared collection whatever object carries it.
 
-`GET_RANGE` is a **reader, not an action**. It keeps no response and takes no
-place in the rerun graph, which is what makes it usable per slice:
-
-- the list already holds the slices it received and glues them back together —
-  a second memory holding one of them would fight it;
-- a `POST` invalidating "the collection" would otherwise send every slice ever
-  loaded back to the network at once.
-
-What it keeps instead is the collection's composition — which rank holds which
-id, and how many ranks there are, per resolved bound params — so a list drawing
-this collection again after its screen went away finds it drawn and revalidates
-it rather than starting over
-([list_refresh.md](./list_refresh.md#leaving-the-screen-and-coming-back)).
-
-Membership is what a re-read answers: a verb listed in `rerunOn.GET_RANGE`
-(`["POST", "DELETE"]` by default) tells the run the collection moved, and it
-asks again for the window it draws, rows staying on screen meanwhile. A write
-that moves an item in or out through another verb — a `PATCH` that archives —
-is added there, or `reader.invalidate()` is called; a `key` on the run is not the
-way ([list_refresh.md](./list_refresh.md#a-paginated-list-stays-on-screen-too)).
-
-It reads a collection, so it lives on the resource itself (or on a
-`withParams()` of it), not on a relation.
+`GET_RANGE` is a **reader, not an action**: it keeps no response and takes no
+place in the rerun graph — the list already holds the slices it received, and a
+`POST` invalidating "the collection" would otherwise send every slice ever
+loaded back to the network at once. What it keeps is the collection's
+composition, so a list coming back finds it drawn
+([list_refresh.md](./list_refresh.md#leaving-the-screen-and-coming-back)), and a
+verb listed in `rerunOn.GET_RANGE` makes it ask again for the window it draws,
+rows staying on screen
+([list_refresh.md](./list_refresh.md#a-paginated-list-stays-on-screen-too)). It
+reads a collection, so it lives on the resource (or on a `withParams()` of it),
+not on a relation.
 
 ## Searching the same collection
 
-A screen showing a collection asks a second question about it soon enough: the
-list draws a page, a search box goes looking in the whole base for what the page
-does not hold. Same entity, same ids — so it is the same `GET_MANY`, with one
-more param:
+A screen showing a collection soon asks a second question about it: the list
+draws a page, a search box goes looking in the whole base for what the page does
+not hold. Same entity, same ids — so it is the same `GET_MANY`, with one more
+param:
 
 ```js
 const USER = resource("user", {
@@ -251,65 +207,53 @@ const USER = resource("user", {
 });
 
 const pageAction = USER.GET_MANY.bindParams({ scope: "seatable" });
-const searchAction = USER.GET_MANY.bindParams({
-  scope: "seatable",
-  search: searchSignal,
-});
+const searchAction = USER.GET_MANY.bindParams(
+  computed(() => ({ scope: "seatable", search: searchSignal.value })),
+  { debounce: 300 },
+);
 ```
 
-Not a resource of its own, and not a `createAction` sitting beside the resource.
-Those answer with **detached copies**: the user a search found is a different
-object from the same user everywhere else on screen — it does not follow an
+Not a resource of its own, and not a `createAction` sitting beside the resource:
+those answer with **detached copies** — the user a search found is a different
+object from the same user everywhere else on screen, it does not follow an
 update, and a mutation writes to the one it is not. The resource's own
 `GET_MANY` upserts what comes back like any other read, so one object per user
 answers both questions.
 
 **Two `GET_MANY` on one resource do not compete.** Each bound instance keeps its
-own array of ids (none until it has answered) and resolves it against the
-shared store, so answering the search leaves the page's list as it was — clear
-the search box and every row it had is still there. ["A `*_MANY` callback
-replaces the collection
-wholesale"](#when-the-backend-answers-a-sub-route-with-the-whole-parent), below,
-is about the rows the store keeps for one owner — not about what some other
-action reading the same resource is showing.
-
-It is `bindParams`, not `withParams`: a `withParams()` carves an autorerun scope
-(a POST at the root does not reach into it), and a word someone typed is not a
-scope — the search must refresh after a write like the list does
+own array of ids (none until it has answered) and resolves it against the shared
+store, so answering the search leaves the page's list as it was — clear the
+search box and every row it had is still there. It is `bindParams`, not
+`withParams`: a word someone typed is not a scope
 ([`withParams()`](#withparams-a-scope-with-reruns-of-its-own)).
 
-The lifecycle a search wants comes with being an action: `loading` while the
-word is in flight, the run before it aborted through its `signal`, typing
-debounced by the effect driving it —
-`actionRunEffect(searchAction, () => …, { debounce: 300 })` where the app owns
-the request, a `stateSignal` when the word is in the address. A word already
-asked is answered by the instance that asked it, with no second request
-([actions.md](./actions.md#reading-an-action)).
+The lifecycle a search wants comes with being an action, read with
+`useAsyncData(searchAction, { run: true, loading: true })`
+([actions.md](./actions.md#params-bindparams-and-calling-the-action)): the typing
+is debounced by the binding, `loading` is up while a word is in flight, and a
+word already asked is answered by the instance that asked it, with no second
+request.
 
 What stays the app's is what to KEEP of a search once the word changes — the
 rows someone picked out of it and expects to still see under the next word.
 Keep their **ids**, not the objects: an object is a snapshot, and it stops
 following its row the moment anything writes to it. `RESOURCE.useAllByIds(ids)`
-reads those rows as they are now — a kept id turned back into something that
-stays fresh, and the ids the store no longer holds simply drop out.
-`RESOURCE.useById(id)` is the singular, `RESOURCE.useArray()` the whole store.
-None is a hook (a `.map()` over them is fine), and each subscribes the render
-that calls it to what it returns: `useById` and `useAllByIds` to the rows they
-hand back — a card reading its own row stays still while other rows of the
-store are written, and re-renders when its row is — `useArray` to the whole
-store. An entry of `useAllByIds` given by a unique key rather than by id can
-only be found by reading the whole store, and that read follows it too.
+reads those rows as they are now — the ids the store no longer holds drop out —
+`RESOURCE.useById(id)` one row, `RESOURCE.useArray()` the whole store. None is a
+hook (a `.map()` over them is fine), and each subscribes the render that calls
+it to what it returns: a card reading its own row stays still while other rows
+of the store are written. An entry of `useAllByIds` given by a unique key rather
+than by id is found by reading the whole store, and that read follows it too.
 
 A row counts as written only when something in it changed:
 
-- **An answer** — what a callback returns — is compared to the row held in
-  depth. Parsed JSON makes every object nested in a row a new one; a
-  revalidation returning the same rows keeps every one of them, and their
-  readers stay still.
-- **A relation** changes its row when the row points at other children. What
-  happens to the children themselves is followed through the relation:
-  `game.place.label` read in a render re-renders it when the place is written,
-  and the game row stays the one it was.
+- **An answer** is compared in depth to the row held: a revalidation returning
+  the same rows keeps every one of them — though parsed JSON makes every nested
+  object a new one — and their readers stay still.
+- **A relation** changes its row when the row points at other children; the
+  children themselves are followed through the relation — `game.place.label`
+  read in a render re-renders it when the place is written, and the game row
+  stays the one it was.
 - **A value written with `store.upsert()`** is compared by reference: a new
   object is a change, whatever it holds.
 
@@ -330,14 +274,11 @@ PATCH: ({ id, op, ...rest }) => {
 
 One verb dispatching on a string gives up everything the store does for you:
 per-operation action state (loading/error per button), per-relation autorerun,
-and a child collection that other components can read.
-
-The same smell wears a second coat: a verb on one relation carrying, in its
-params, an id from a **different** relation — a `group_id` sent to the game ×
-user shares, which the server expands into people. That is two relations
-spelled as one, and the one the gesture is actually about (game × group) is the
-one that ends up with no rows, no action state, and nothing for its row on
-screen to read.
+and a child collection that other components can read. The same smell wears a
+second coat: a verb on one relation carrying an id from a **different** relation
+— a `group_id` sent to the game × user shares, which the server expands into
+people — is two relations spelled as one, and the one the gesture is about
+(game × group) ends up with no rows and nothing for its row on screen to read.
 
 | Situation                                                                                                     | Use                                                                                                                                 |
 | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
@@ -350,173 +291,53 @@ screen to read.
 Singular vs plural is about the relation, not the verb: `.one`/`.scopedOne` for a
 single sub-object, `.many`/`.scopedMany` for a collection.
 
-And the table has a negative worth naming, because the workaround looks fine in
-a demo: **a write whose effect the response does not carry is a modelling bug,
-not a case for the client to remember.** After the write, some row on screen
-will claim "this happened" — and it must read that from the store, which only
-holds what responses carried. When the relation actually written has no row
-anywhere (the response answered with a different entity than the one the
-gesture was about), whatever the screen memorizes instead lives on the client
-and **dies with the session**: reload, and the row confidently claims the write
-never happened. The fix is on the shape — give that relation its own
-relationship method and a callback returning what was written, even when the
-backend must grow a field for it — never a flag next to the button.
+**A write whose effect the response does not carry is a modelling bug, not a
+case for the client to remember.** The row on screen claiming "this happened"
+reads the store, which holds only what responses carried; whatever the screen
+memorizes instead lives on the client and dies with the session — reload, and
+the row confidently claims the write never happened. The fix is on the shape —
+give that relation its own relationship method and a callback returning what was
+written, even when the backend must grow a field for it — never a flag next to
+the button.
 
 ## Callback return contracts
 
-These are not guessable — each relationship method has its own shape.
-
-### `.one(propertyName, childResource, { GET, PUT, DELETE })`
-
-`GET` and `PUT` return the **parent** object with the child nested inside;
-`DELETE` returns the parent id, or `{ id }`:
-
-```js
-const USER_SESSION = USER.one("session", SESSION, {
-  GET: async ({ id }) => {
-    const session = await fetchJson(`/users/${id}/session`);
-    return { id, session }; // { id, session: { id: 10, token: "abc" } }
-  },
-  DELETE: async ({ id }) => {
-    await fetchJson(`/users/${id}/session`, { method: "DELETE" });
-    return id; // property becomes null
-  },
-});
-```
-
-`session: null` in the returned parent means "no relation". A parent GET/POST
-that embeds the child inline works too — the property setter upserts it.
-
-### `.many(propertyName, childResource, restCallbacks)`
-
-GET_MANY returns the **parent** object with the array nested inside; DELETE
-returns the pair of ids:
-
-```js
-const USER_FRIENDS = USER.many("friends", USER, {
-  GET_MANY: async ({ id }) => {
-    const friends = await fetchJson(`/users/${id}/friends`);
-    return { id, friends }; // { id, friends: [{ id: 2 }, { id: 3 }] }
-  },
-  POST: async ({ id, friendId }) =>
-    fetchJson(`/users/${id}/friends`, { method: "POST", body: { friendId } }),
-  DELETE: async ({ id, friendId }) => {
-    await fetchJson(`/users/${id}/friends/${friendId}`, { method: "DELETE" });
-    return [id, friendId]; // [parentId, childId]
-  },
-  DELETE_MANY: async ({ id, friendIds }) => {
-    await fetchJson(`/users/${id}/friends`, {
-      method: "DELETE",
-      body: { friendIds },
-    });
-    return [id, friendIds]; // [parentId, [childId, …]]
-  },
-});
-```
-
-The singular POST/PUT/PATCH callbacks return the **child** object. It is upserted
-into the child store, but it does not join the parent's array on its own: the
-array is the backend's, and only a GET_MANY refresh rewrites it.
-
-### `.scopedOne(propertyName, { idKey, GET, POST, PUT, PATCH, DELETE })`
-
-Every callback returns `[ownerId, props | null]`:
-
-```js
-const USER_PROFILE = USER.scopedOne("profile", {
-  GET: async ({ id }) => [id, await fetchJson(`/users/${id}/profile`)],
-  PATCH: async ({ id, ...props }) => [
-    id,
-    await fetchJson(`/users/${id}/profile`, { method: "PATCH", body: props }),
-  ],
-  DELETE: async ({ id }) => {
-    await fetchJson(`/users/${id}/profile`, { method: "DELETE" });
-    return [id, null];
-  },
-});
-```
-
-The property is `null` until a callback provides data. `ownerId` may be
-`{ [uniqueKey]: value }` when the owner is known by an alternate key rather than
-its id.
-
-### `.scopedMany(propertyName, { idKey, GET, GET_MANY, POST, PUT, PATCH, DELETE, … })`
-
-Every callback returns `[ownerId, ...rest]`:
-
-```js
-const GAME_CANDIDATES = GAME.scopedMany("candidates", {
-  idKey: "user_id",
-  GET_MANY: async ({ id }) => [id, await fetchJson(`/games/${id}/candidates`)],
-  POST: async ({ id, ...body }) => [
-    id,
-    await fetchJson(`/games/${id}/candidates`, { method: "POST", body }),
-  ],
-  PUT: async ({ id, oldUserId, ...props }) => [id, oldUserId, props], // id rename
-  DELETE: async ({ id, user_id }) => {
-    await fetchJson(`/games/${id}/candidates/${user_id}`, { method: "DELETE" });
-    return [id, user_id];
-  },
-});
-```
-
-| Callback           | Returns                                                |
-| ------------------ | ------------------------------------------------------ |
-| GET / POST / PATCH | `[ownerId, props]`                                     |
-| PUT (id rename)    | `[ownerId, oldId, props]`                              |
-| DELETE             | `[ownerId, childId]`                                   |
-| any `*_MANY`       | `[ownerId, itemArray]` — replaces the whole collection |
-| DELETE_MANY        | `[ownerId, [childId, …]]`                              |
-
-`idKey` names the child's own key inside its owner (`user_id` above); it defaults
-to `"id"`.
-
-### A relation declared on a scoped child
-
-A scoped child takes relations of its own — a column pointing at a shared data
-type:
-
-```js
-const TABLE_COLUMNS = TABLE.scopedMany("columns", {
-  idKey: "name",
-  GET_MANY: async ({ id }) => [id, await fetchJson(`/tables/${id}/columns`)],
-  // [id, [{ name: "email", dataType: { id: 2, name: "varchar" } }, …]]
-  PATCH: async ({ id, name, ...props }) => [
-    id,
-    await fetchJson(`/tables/${id}/columns/${name}`, {
-      method: "PATCH",
-      body: props,
-    }),
-  ],
-});
-TABLE_COLUMNS.one("dataType", DATA_TYPE);
-```
-
-Every column gets a reactive `dataType` read from the `DATA_TYPE` store, fed by
-what the scoped child's callbacks embed. The relation itself takes none of the
-callbacks whose result names the column — `.one()`'s `GET`/`PUT`/`DELETE`,
-`.many()`'s `GET_MANY`/`DELETE`/`DELETE_MANY`, and every callback of a
-`.scopedOne()`/`.scopedMany()`, whose `ownerId` would be the column: they name
-it by its `name` alone, and a column exists only inside its table — two tables
-can each have an `email`. Declaring one throws. A column's data type is read and
-changed through `TABLE_COLUMNS`, whose results say which table
-(`[id, { name, dataType }]`); the fields of a data type itself, through
-`DATA_TYPE`.
-
-A `.scopedOne()`/`.scopedMany()` chained on a scoped child works the same way,
-and keeps one value per column: `TABLE_COLUMNS.scopedMany("constraints")` gives
-`users.email` and `admins.email` a collection each, fed by the `constraints`
-embedded in each table's columns.
+These are not guessable — each relationship method has its own shape, written
+out with an example in its JSDoc:
+
+- **`.one(propertyName, CHILD, { GET, PUT, DELETE })`** — `GET`/`PUT` return
+  the **parent** with the child nested inside (`{ id, session: { id: 10 } }`,
+  `session: null` for none); `DELETE` the parent id, or `{ id }`. A parent
+  `GET`/`POST` that embeds the child inline works too.
+- **`.many(propertyName, CHILD, callbacks)`** — `GET_MANY` returns the
+  **parent** with the array nested inside; `GET`/`POST`/`PUT`/`PATCH` the
+  **child**, upserted into the child store but not joining the parent's array,
+  which only a `GET_MANY` rewrites; `DELETE` `[parentId, childId]`,
+  `DELETE_MANY` `[parentId, [childId, …]]`.
+- **`.scopedOne(propertyName, callbacks)`** — every callback returns
+  `[ownerId, props | null]`; the property is `null` until one does.
+- **`.scopedMany(propertyName, { idKey, … })`** — `[ownerId, props]`; `PUT` (an
+  id rename) `[ownerId, oldId, props]`; `DELETE` `[ownerId, childId]`; any
+  `*_MANY` `[ownerId, itemArray]`, which replaces the whole collection;
+  `DELETE_MANY` `[ownerId, [childId, …]]`. `idKey` names the child's own key
+  inside its owner (`"id"` by default).
+
+`ownerId` may be `{ [uniqueKey]: value }` when the owner is known by an
+alternate key. A scoped child takes relations of its own —
+`TABLE_COLUMNS.one("dataType", DATA_TYPE)`, fed by what the columns' callbacks
+embed — but none of the callbacks whose result names the child by itself
+(`.one()`'s `GET`/`PUT`/`DELETE`, `.many()`'s `GET_MANY`/`DELETE`/`DELETE_MANY`,
+every scoped callback): a column exists only inside its table, and two tables
+can each have an `email`. Declaring one throws.
 
 ## When the backend answers a sub-route with the whole parent
 
 This is the common REST shape, and it is the reason `op` dispatch feels
 attractive: a full-parent response absorbs into a parent `PATCH` with no
 thinking. Model the relation anyway and absorb the response in the callback —
-`resource()` gives a plural callback for exactly this: **any `*_MANY` callback
-replaces the collection wholesale** — the rows the store keeps for that owner,
-not what some other action reading the same resource is showing (see
-[Searching the same collection](#searching-the-same-collection)).
+**any `*_MANY` callback replaces the collection wholesale**: the rows the store
+keeps for that owner, not what some other action reading the same resource is
+showing (see [Searching the same collection](#searching-the-same-collection)).
 
 ```js
 const GAME_CANDIDATES = GAME.scopedMany("candidates", {
@@ -537,22 +358,22 @@ const GAME_CANDIDATES = GAME.scopedMany("candidates", {
 });
 ```
 
-For `.many()`, the equivalent is its GET_MANY callback, which already takes the
-parent object with the array nested inside — return the response untouched.
-
-Deletion is the exception: `DELETE`/`DELETE_MANY` drop by id rather than replace,
-so return `[ownerId, deletedId]` using the id you already have in the params,
-and ignore the full parent the backend sent back.
+For `.many()`, the equivalent is its `GET_MANY` callback, which already takes
+the parent object with the array nested inside — return the response untouched.
+Deletion is the exception: `DELETE`/`DELETE_MANY` drop by id rather than
+replace, so return `[ownerId, deletedId]` from the id you already have in the
+params, and ignore the full parent the backend sent back.
 
-Fields of the parent that come back in such a response (a `status`, a `score`)
-are not applied by the relation callback — it only writes the relation. If the
-parent's own fields change too, either let the parent GET rerun (see below) or
-`store.upsert()` the parent explicitly.
+The parent's own fields in such a response (a `status`, a `score`) are applied
+only where the callback returns the parent: `.one()`'s `GET`/`PUT` and
+`.many()`'s `GET_MANY` upsert it whole, fields included. A scoped relation's
+callback writes the relation alone — if the parent's own fields change too,
+either let the parent `GET` rerun (below) or `store.upsert()` the parent
+explicitly.
 
 ## Relations and autorerun
 
-Relationship mutations do **not** invalidate their parent by default. The exact
-rules, verified by `src/state/rest/tests/resource_graph_parent_rerun.test.js`:
+Relationship mutations do **not** invalidate their parent by default. The rules:
 
 - `.scopedMany` child **POST** reruns the owner's singular `GET`, whether it
   goes through the child or through a `withParams()` scope of it — but only when
@@ -563,21 +384,21 @@ rules, verified by `src/state/rest/tests/resource_graph_parent_rerun.test.js`:
   already carries the updated child.
 - `.scopedOne` mutations rerun nothing, ever — the result is the new value.
 - `.one` / `.many` children live in an independent store; mutating them never
-  reruns the parent. Declare it explicitly with `dependencies` if you need it
-  (see [`dependencies`](#dependencies-rerun-after-another-resource-writes)).
+  reruns the parent. Declare it with
+  [`dependencies`](#dependencies-rerun-after-another-resource-writes) if you
+  need it.
 - Within a relationship resource, the usual defaults still apply: its own
   `GET_MANY` reruns after its own `POST`. A `.one`/`.many` `GET` is reset (not
   rerun) by its own `DELETE`, as a root `GET` is; a scoped `GET` is not reset —
-  its data simply resolves to nothing once the child is dropped. Override per
-  relation with `rerunOn`/`dependencies`, which every relationship method
-  accepts; what a relation leaves out is its parent resource's (`rerunOn` key
-  by key).
+  its data resolves to nothing once the child is dropped. Every relationship
+  method accepts `rerunOn`/`dependencies`; what a relation leaves out is its
+  parent resource's (`rerunOn` key by key).
 
 Splitting a sub-resource out of a parent `PATCH` therefore changes the refresh
 graph: a parent field the parent's own response kept fresh is, once the relation
 is a resource of its own, refreshed only by these rules. When a parent field
-genuinely depends on a child mutation, say so with `dependencies` rather than
-relying on a rerun that will not happen.
+depends on a child mutation, say so with `dependencies` rather than relying on a
+rerun that will not happen.
 
 ## `withParams()`: a scope with reruns of its own
 
@@ -589,8 +410,8 @@ resource read under several fixed questions at once — the admins and the guest
 of one `USER`, each list on its own screen. A guest created should not send the
 admin list back to the network.
 
-`withParams()` carves that out. It binds params into every action of the
-resource and gives the result a rerun scope of its own:
+`withParams()` binds params into every action of the resource and gives the
+result a rerun scope of its own:
 
 ```js
 const ADMIN = USER.withParams({ role: "admin" });
@@ -603,29 +424,29 @@ await ADMIN.POST({ name: "Bob" }); // reruns ADMIN.GET_MANY, and nothing else
 
 The isolation is complete, in both directions: a write on `ADMIN` reaches no
 read of `GUEST` and no read of `USER` itself, and a write on `USER` reaches no
-read of either scope (held by cases 5 and 6 of
-`src/state/rest/tests/resource_graph_lifecycle.test.js`). What the scopes still
-share is the **store**: an item updated through one is the same object in the
-others, so the fields of a row change everywhere without a request — only the
-membership of each list is a question its own scope answers.
-
-It scopes a relation as well as a resource, and the scope's actions are the
-relation's: `TABLE_COLUMNS.withParams({ withTypes: true }).GET_MANY` keeps the
-`[ownerId, items]` contract of `.scopedMany()` and replaces that table's
-columns.
-
-`withParams()` chains, merging the params —
-`USER.withParams({ role: "admin" }).withParams({ gender: "male" })` is
-`USER.withParams({ role: "admin", gender: "male" })`. Its second argument takes
-`rerunOn` and `dependencies` for that scope; what it leaves out is the
-resource's — a `rerunOn` key by key, so `{ rerunOn: { GET: ["PATCH"] } }` keeps
-the resource's `GET_MANY` and `GET_RANGE`. Empty params throw: a scope has to be
-about something.
-
-It is not the tool for a param the user types. A search word bound with
+read of either scope. What the scopes still share is the **store**: an item
+updated through one is the same object in the others, so the fields of a row
+change everywhere without a request — only the membership of each list is a
+question its own scope answers.
+
+**A scope is the object `withParams()` returned, not its params.** Each call
+builds one of its own: two `USER.withParams({ role: "admin" })` written in two
+files do not reach each other, and neither do
+`USER.withParams({ role: "admin" }).withParams({ gender: "male" })` and
+`USER.withParams({ role: "admin", gender: "male" })`, though they bind the same
+params. Declare each scope once, and import it.
+
+It scopes a relation as well, keeping the relation's return contract
+(`TABLE_COLUMNS.withParams({ withTypes: true }).GET_MANY` replaces that table's
+columns). Its second argument takes `rerunOn` and `dependencies` for that scope;
+what it leaves out is the resource's — a `rerunOn` key by key, so
+`{ rerunOn: { GET: ["PATCH"] } }` keeps the resource's `GET_MANY` and
+`GET_RANGE`. Empty params throw: a scope has to be about something.
+
+It is not the tool for a param the user types: a search word bound with
 `withParams()` would keep its results from refreshing after a write on the
-resource; a word is a `bindParams` on the resource's own `GET_MANY`, which stays
-in the rerun graph ([Searching the same collection](#searching-the-same-collection)).
+resource, where a `bindParams` on the resource's own `GET_MANY` stays in the
+rerun graph ([Searching the same collection](#searching-the-same-collection)).
 `withParams()` is for a scope the code fixes once — a role, a status, a tenant.
 
 ### `dependencies`: rerun after another resource writes
@@ -642,12 +463,13 @@ const ROLE_WITH_OWNERS = ROLE.withParams(
 ```
 
 Any write on a listed resource (`POST`, `PUT`, `PATCH`, `DELETE`) reruns the
-completed `GET` and `GET_MANY` of the resource that declared it. A dependency is
-a facade: `DATABASE` and `DATABASE.withParams(…)` are two of them, and only
-writes on the one listed count. Nothing goes the other way, and nothing is
-inferred — the relationship methods have rules of their own
-([above](#relations-and-autorerun)), and a relation that really is a sub-route
-of the parent is modelled with them, never declared as a dependency.
+completed `GET` and `GET_MANY` of the resource that declared it, and invalidates
+its `GET_RANGE` readers when the verb is in its `rerunOn.GET_RANGE`. A
+dependency is a facade: `DATABASE` and `DATABASE.withParams(…)` are two of them,
+and only writes on the one listed count. Nothing goes the other way, and nothing
+is inferred — a relation that really is a sub-route of the parent is modelled
+with the relationship methods ([above](#relations-and-autorerun)), never
+declared as a dependency.
 
 ## A function calling the verb, or the instance
 
@@ -665,30 +487,32 @@ Both forms are real, and what separates them is narrower than it looks:
 </Button>
 ```
 
-The function gives up almost nothing. Either way the button is busy while the
-write runs, shows the error if it fails and goes back to what it held; either way
-what runs inside is the same resource run, so the store is updated and the
-actions this mutation invalidates rerun the same. The failure travels too — the
-call fails, so the action around it fails
-([error_handling.md](./error_handling.md#what-a-failing-action-does)).
-
-What `bindParams` adds, and it adds only this, is **identity**: everyone binding
-the same params holds one instance, so a run started in one place is visible from
-another. Reach for it when something else on screen has to see this very run — a
-user row in a side explorer going loading while the main page renames that user,
-two affordances for the same delete that must both go busy at once. Nothing else
-in the stack answers that question: the store holds the data, not who is
-currently writing it.
-
-Either way, what to READ afterwards is the store, or the instance that ran —
-never the verb: a run made with params lands on the child those params made,
-so `GAME_CANDIDATES.POST.dataSignal` is empty whichever form ran it. The verb's
-own signals hold only a run made on the verb itself, with no params (see
-[actions.md](./actions.md#the-answer-is-kept-on-the-instance-that-ran)).
-
-Where it does not pay, and most call sites are here: one affordance, in one
-place, that nobody else watches. A `bindParams({ id })` written per row builds an
-identity nothing reads, and a plain function says the gesture more directly.
+Either way the button is busy while the write runs and shows the error if it
+fails; either way what runs inside is the same resource run, so the store is
+updated, the actions this mutation invalidates rerun the same, and a failure
+fails the action around it
+([error_handling.md](./error_handling.md#what-a-failing-action-does)). But a
+function is wrapped into an action of its own, one with no verb, and the
+instance carries two things that wrapper does not:
+
+- **identity.** Everyone binding the same params holds one instance, so a run
+  started in one place is visible from another. Reach for it when something else
+  on screen has to see this very run — a user row in a side explorer going
+  loading while the main page renames that user, two affordances for the same
+  delete that must both go busy at once. Nothing else in the stack answers that
+  question: the store holds the data, not who is currently writing it.
+- **the verb** (`meta.verb`). Under a [network policy](./network_policy.md), a
+  control holding a write verb's instance — or sitting in a `<Form>` holding one
+  — is read-only before the press and says why. The function form is not seen:
+  the press is accepted, and the write fails after it with a
+  `NetworkPolicyError`.
+
+Where neither pays — one affordance, in one place, that nobody else watches, and
+no network policy to hold the write — a `bindParams({ id })` written per row
+builds an identity nothing reads, and a plain function says the gesture more
+directly. Either way, what to READ afterwards is the store, or the instance that
+ran — never the verb, whose signals hold only a run made on the verb itself, with
+no params ([actions.md](./actions.md#the-answer-is-kept-on-the-instance-that-ran)).
 
 What genuinely loses what a resource gives is neither of those two, but a
 callback that goes around the verb:
@@ -702,10 +526,6 @@ callback that goes around the verb:
 </Button>
 ```
 
-Away from a component, where the run is a gesture and not something to render,
-an action is callable: `GAME.DELETE({ id })` is
-`GAME.DELETE.bindParams({ id }).rerun()`.
-
 ## See also
 
 - [list_refresh.md](./list_refresh.md) — what re-runs after a write, and what