foldkit-remote 0.18.1 → 0.20.0

package/README.md

@@ -1382,6 +1382,12 @@ the store the answer left:
   it. Declare the order in the body (`Query.orderBy`) to keep a list that a
   change provably did not move.
 
+**The client runs a body's primitive operators by its own table.**
+`Remote.make({ ..., operators })` (`Operators.kernel` by default) is the table
+it matches, filters and places rows with. A body calling an operator the table
+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
 what the server said in (an answer, as above, or a read or a live patch, as
@@ -1424,6 +1430,15 @@ effect on rows it did not return.
 `Unknown` for an id never started here (or settled so long ago it left the
 bounded ledger). A retry reuses its id, and the latest outcome wins.
 
+A request id names a request to this client only: it is a counter in the
+Model, so it restarts on reload and two clients' first requests share it. To a
+server, a mutation is named by its **operation**, an id minted where it is first
+sent (`crypto.randomUUID()`), unique across clients. A failed request keeps its
+operation, and a retry with the same `requestId` (`Data.mutate(model, M, input,
+{ requestId })`) sends it again, so a server that keeps a record of its writes
+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:
 
@@ -1441,7 +1456,14 @@ A mutation can also 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. `keys` names the input keys
+a delete shows nothing until its answer removes the row everywhere. 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
+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.
 
@@ -1454,7 +1476,18 @@ Data.mutate(model, EditProject, { id: 'p1', name: 'Apollo II', status: 'active'
 ```
 
 `Refusal.field(key, reason)` names an input key and why; `Refusal.conflict`
-says the row moved on. The server sends the refusal encoded by this schema and
+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.
 
@@ -2074,9 +2107,11 @@ above.
 `Remote.mutateInto(bound, model, mutation, input, requestId, { optimistic, now })` is
 the one-step imperative start/run/settle form for SSR and tests.
 
-`Remote.mutate(mutation, input, requestId)` is the transport call itself. It
-decodes the typed `Output` and returns normalized entity patches and confirmed
-connection changes for a caller to reduce through `updateRemote`.
+`Remote.mutate(mutation, input, requestId, { keys, operation })` is the
+transport call itself. It decodes the typed `Output` and returns normalized
+entity patches and confirmed connection changes for a caller to reduce through
+`updateRemote`. It mints an operation id when none is given; a caller retrying
+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