@lotics/app-sdk 0.100.1 → 0.101.0

package/docs/mutations.md

@@ -1,12 +1,8 @@
 # Mutations — writing data through workflows
 
-Everything about writing data from an app: `useWorkflow` (the only write path), the
-`WorkflowResult` contract and its resolve-never-throw failure model, declaring typed workflow
-inputs (file/member/optional inputs), returning structured data with `return({ data })`,
-the automatic re-read a successful write triggers, the diff-before-update discipline, locked records
-(`readLocked` + `request_locked_record_change`), optimistic reconciliation
-(`useOptimistic`), and `useRecording` — a recording the host files through a workflow. Read this before building any screen that creates, updates, or deletes
-records. What may be written **inside** the workflow body — the JS subset, steps, helpers,
+Writing data from an app: `useWorkflow` and its result contract, typed inputs and outputs, how a
+write shows on every read from the press, the re-read a successful write triggers,
+diff-before-update, locked records, `useNewRecord` and `useRecording`. What may be written **inside** the workflow body — the JS subset, steps, helpers,
 traps — is [workflows](./workflows.md). Reading data is [queries](./queries.md) +
 [data_fetching](./data_fetching.md); uploads are [files](./files.md); who a write runs as is
 [security](./security.md).
@@ -28,10 +24,8 @@ const result = await createOrder({ customer_id, quantity: 3 });
   against the alias's declared input schema, and executes the workflow under the **app
   owner's** authority (never the viewer's — see [security](./security.md) for attribution,
   privilege gates, and public-app semantics).
-- Binding is server-side (`set_app_workflow`, or `lotics app workflow set <alias>` from the
-  app project), and `lotics app deploy` calls it: `package.json#lotics.workflows.<alias>` plus
-  `src/workflows/<alias>.ts` ARE the source of a binding, so an alias committed to the repo is
-  one the next clone ships. The declaration also types `useWorkflow` (below).
+- Binding is server-side and live: `set_app_workflow` binds an alias as a new version of the app,
+  and a deploy never touches it. The declaration also types `useWorkflow` (below).
 - Invoking an alias that is not bound resolves with `status: "error"` and a message naming
   the missing binding.
 - Anonymous visitors to a publicly shared app can invoke workflows too; the triggering
@@ -39,12 +33,16 @@ const result = await createOrder({ customer_id, quantity: 3 });
 
 ## `useWorkflow(alias)` — signature and typing
 
-Exact signature: `dist/src/hooks.d.ts`. `useWorkflow(alias)` returns a stable async callable:
+Exact signature: `dist/hooks.d.ts`. `useWorkflow(alias)` returns a stable async callable:
 `(inputs) => Promise<WorkflowResult<TData>>`.
 
-Typing comes from per-app codegen: `lotics app pull` / `app dev` / `app deploy` /
-`app codegen` write `.lotics/app_workflows.d.ts`, augmenting the SDK's `AppWorkflows` and
-`AppWorkflowResults` interfaces from the manifest's alias declarations. The result:
+`useWorkflows(aliases)` is the same runner for writes that are DATA — a list of aliases known only at
+render: one callable per alias, each run exactly as `useWorkflow`'s.
+
+Typing comes from `.lotics/app_workflows.d.ts`, which augments the SDK's `AppWorkflows` and
+`AppWorkflowResults` interfaces from the app's bound declarations. The declarations are generated from the app's live bindings into `.lotics/` whenever a sandbox
+session opens on the app. A project on your own machine has none, so every alias is accepted as a
+plain string there, untyped. The result:
 
 | Declaration | Call-site type |
 |---|---|
@@ -57,7 +55,7 @@ Typing comes from per-app codegen: `lotics app pull` / `app dev` / `app deploy`
 ## `WorkflowResult` — the result contract
 
 Every call resolves to a `WorkflowResult<TData>` (type exported from the package root;
-`dist/src/hooks.d.ts`):
+`dist/hooks.d.ts`):
 
 | Field | Type | Meaning |
 |---|---|---|
@@ -70,7 +68,7 @@ Every call resolves to a `WorkflowResult<TData>` (type exported from the package
 ### The failure model: check `status`, never just try/catch
 
 **Every failure resolves — the promise (almost) never rejects.** All three transports
-(embedded product host, standalone on the app's own origin, and the `lotics app dev` harness)
+(embedded product host, and standalone on the app's own origin)
 convert every failure into a resolved `{ status: "error", message }`:
 
 | Failure | What resolves |
@@ -132,8 +130,7 @@ setErrs(result.field_errors ?? {});
 ```
 
 Keep `message` too — it is what a refusal with no field to blame says, and the two are shown
-together (a `Callout` at the dialog's scope plus the per-field text). One reading covers both
-refusals: the key is the same whichever half answered, so a form never branches on that.
+together (a `Callout` at the dialog's scope plus the per-field text).
 
 A failing `validate` check fills the same map from its `field_key`, so the key there is the INPUT
 name as well — `field_key: "ly_do"`, never the `fld_` key of whatever column the check happened
@@ -159,10 +156,9 @@ The same run reached through the `run_app_workflow` tool — from chat, from MCP
 agent — lists those files as `file_id`. It is the same value `useWorkflow` gives you as `id`,
 so a file an agent produced and a file the app produced are addressed identically.
 
-Files travel **only** via `files[]` — never hand a `file_id`/`url` back through
-`return({ data })`, and never `update_records` a file onto a record solely to make it
-downloadable. A download-only workflow generates and returns; attaching to a record is a
-separate, optional step. Previewing/downloading files: [files](./files.md).
+Files travel **only** via `files[]` — never through `return({ data })`, and never
+`update_records` a file onto a record solely to make it downloadable
+([files](./files.md)).
 
 ### Structured results: `return({ data })`
 
@@ -172,13 +168,10 @@ envelope's grammar — `message` is required, `field_errors` never reaches the a
 (computed totals, row lists, status objects) the app reads back as `result.data`:
 
 - **Typed for free — persisted at `set`.** The alias's `outputs` schema is derived at save
-  time from the inferred TypeScript type of the body's `return({ data })` — the return *is*
-  the declaration. When the manifest declared **no** `outputs`, `lotics app workflow set`
-  writes the server-derived schema into `package.json#lotics.workflows.<alias>.outputs` and
-  refreshes that alias's generated types in the same command, so `result.data` is typed
-  immediately — no hand-copy of the echoed schema, no second `lotics app codegen`. An
-  **explicitly declared** `outputs` is authoritative and never overwritten. Declare an explicit
-  `outputs` only to narrow beyond what's inferred; a shape the checker can't pin down degrades
+  time from the inferred type of the body's `return({ data })`. When the binding declares
+  **no** `outputs`, `set_app_workflow` stores the derived schema as the alias's `outputs`. An
+  **explicitly declared** `outputs` is authoritative and never overwritten;
+  declare one only to narrow beyond what's inferred. A shape the checker can't pin down degrades
   to untyped `json`, never to a wrong schema.
 - **The output vocabulary is the input one minus the caller-only types, and `select` behaves
   differently.** Scalars (`text`/`number`/`boolean`/`date`/`datetime`/`email`), `record_link`
@@ -219,10 +212,8 @@ if (r.status === "success" && r.data) {
 An alias's declaration is `{ inputs?, outputs?, workflow_id? }` — `workflow_id` is the server's
 half, stamped by the first bind, so an alias an author has only just written carries none.
 `inputs` maps each input name to a typed declaration; it is authored beside the body and
-travels with it (`set_app_workflow` / `lotics app workflow set` reads it from
-`package.json#lotics.workflows.<alias>`, and a deploy pushes a declaration that has moved), and
-the schema the body was verified against is canonical — a manifest edit that reaches no push
-weakens nothing. It drives three things at once: compile-time typing of the `useWorkflow` payload,
+travels with it (`set_app_workflow` takes both), and the schema the body was verified against is
+canonical. It drives three things at once: compile-time typing of the `useWorkflow` payload,
 compile-time typing of `trigger.app_workflow.inputs.*` inside the body, and runtime payload
 validation at the execute boundary.
 
@@ -266,8 +257,7 @@ When the alias declares `inputs`, the server validates the payload before the wo
   owner; the body forwards it to `update_records.set`, where `null` clears.
 - **`""` is NOT a clear** — a top-level optional input whose value is the empty string is treated
   as *omitted* (HTML form controls emit `""` for "left blank", never for "blank this out"), so the
-  write reports success and the old value stays. Reaching for `""` to clear is the natural first
-  guess and it fails silently; send `null`. Nested optional object fields are plain-optional and
+  write reports success and the old value stays; send `null`. Nested optional object fields are plain-optional and
   **reject `null`** — only a top-level input clears; omit the key. A required `text` input does
   accept `""` — emptiness is not a type error; validate non-emptiness in the workflow body if it
   matters.
@@ -278,11 +268,10 @@ When the alias declares `inputs`, the server validates the payload before the wo
   the input `required: false` if "attach nothing" is valid; then `""` omits and `[]` clears.
 - **Server-side reference bindings** — every `record_link` id must reference an existing
   record in its declared `table_id`; every group-scoped `member` id must belong to the
-  declared group; every `file` id must live in the app's workspace. These are real write-time
-  constraints, not picker cosmetics — a hand-crafted request can't redirect the workflow.
-  Rationale and the full caller-boundary model: [security](./security.md).
+  declared group; every `file` id must live in the app's workspace — a tenancy floor, not an
+  authorization check ([security](./security.md#the-caller-boundary)).
 - **`select` names its option set one of two ways — declare exactly one (both or neither is a
-  set-time error).** *Inline* `options: [{label, value}]` freezes the set into the codegen
+  set-time error).** *Inline* `options: [{label, value}]` freezes the set into the generated
   literal union and is **format-only at run time**: any well-formed key is accepted, and an
   option added to the live field after deploy is valid at run time but fails the compile-time
   type (widen or redeploy the declaration when the frozen union gets in the way).
@@ -292,7 +281,7 @@ When the alias declares `inputs`, the server validates the payload before the wo
   added after authoring is accepted, a removed one rejected
   (`select input "<path>" value "<v>" is not one of field "<key>"'s current options`) with no
   redeploy. A `field` that doesn't exist or names a non-select field is rejected at bind time
-  (`lotics app workflow set` / `set_app_workflow`, which a deploy calls for a declaration it holds) with
+  (`set_app_workflow`) with
   `select input references field "<key>", which does not exist in this workspace` /
   `… which is a <type> field, not a select`. Prefer `field` for any select backed by a real
   field; keep `options` for a fixed enum the app owns. Populate pickers from `useFieldOptions`
@@ -302,25 +291,12 @@ If the alias declares **no** `inputs`, the payload passes through opaquely — n
 no typing, no reference binding. Fine for a zero-input action; declare inputs for anything
 that carries data.
 
-### File inputs
-
-A `file` input is how an upload becomes data: the app uploads bytes first (`useFileUpload` /
-`useAttachments` — [files](./files.md)), then passes the returned id(s) to the workflow. An
-uploaded file is **inert** until a workflow attaches it to a record's `files` field.
-
-- Single `file` input → one file id; wrap in an array (`[id]`) when the body writes it to a
-  `files` field (files fields are always arrays).
-- `multi: true` → the body receives `ReadonlyArray<FileId>`, directly assignable to a `files`
-  field — the way to persist several attachments onto one record in one write.
-
-### Member inputs
+### File and member inputs
 
-A `member` input is for genuine member *selection* (assign an order to a teammate) — never
-for actor identity, which the client can't be trusted to supply
-([security](./security.md) → `runtime.triggered_by_member_id`). Declaring one also unlocks
-the roster: `useMembers()` (and `useMembers({ group })` for a declared `group`) only works
-when the app declares a member-typed input somewhere — a workflow input or a query param —
-see [members_and_options](./members_and_options.md).
+A `file` input carries an upload's id ([files](./files.md#file-workflow-inputs)). A `member`
+input is member *selection*, never actor identity
+([security](./security.md#attributing-writes-runtimetriggered_by_member_id)); declaring one also
+unlocks `useMembers` ([members_and_options](./members_and_options.md#access-gates-when-it-errors)).
 
 ### What the body sees
 
@@ -328,50 +304,17 @@ Inside the workflow body, the payload is `trigger.app_workflow.inputs.<name>`, t
 `T | null | undefined` for an optional input. The triggering member is
 `runtime.triggered_by_member_id` (`null` for an anonymous public caller).
 
-**Guard on the KEY, not on the value.** The three caller states arrive intact — an omitted input
-has no key at all, a cleared one has the key with `null` — so a value test cannot tell them apart:
-`!= null` and `isNull(…)` both skip a clear as well as an omission, which is how a Clear button
-ends up doing nothing. Ask whether the key was sent:
-
-```js
-const i = trigger.app_workflow.inputs;
-if (includes(keys(i), "title")) {
-  // i.title may be null here — that is the CLEAR, and `set` writes it as one.
-  await update_records({ table_id: "tbl_items", record_ids: [i.record_id], set: { fld_title: i.title } });
-}
-```
-
-`undefined` is not spellable in a workflow body — the expression subset has no such identifier, and
-a body naming it fails to save with `Unknown identifier "undefined"`. `keys` is the presence test.
-
-When several optional inputs each map to a field, per-field guards become noise. Hand the whole
-bag to `update_records`' **`set_skip_null`** instead — same object shape as `set`, but entries
-whose value is `null`/`undefined` are dropped, so only the fields actually provided get written
-(untouched fields keep their lock / `before_update` / concurrent-edit safety — the diff-write
-discipline below, done in the body). **It drops `null` as well as `undefined`, so it cannot
-CLEAR** — a field the screen must be able to blank belongs in `set` with the guard above, whatever
-the rest of the bag does:
-
-```js
-const i = trigger.app_workflow.inputs;
-await update_records({
-  table_id: "tbl_items",
-  record_ids: [i.record_id],
-  set_skip_null: { fld_title: i.title, fld_status: i.status, fld_due: i.due }, // absent inputs drop out
-});
-```
-
-`set` still writes every key it carries — `null` in `set` **clears** the field; `null`/absent in
-`set_skip_null` **skips** it. The full write surface (`set`, `set_skip_null`, the surgical
-`add_to`/`remove_from`/`replace` ops, `increment`, `field_edits`, and the exact value shape per
-field type)
-is [workflows](./workflows.md#writing-records).
+**Guard on the KEY, not on the value** — an omitted input has no key, a cleared one has the key
+with `null`, so `!= null` skips a clear as well as an omission. `set_skip_null` writes a bag of
+optional inputs as a diff but drops `null`, so it cannot CLEAR. Both, with the rest of the write
+surface: [workflows](./workflows.md#writing-records).
 
 ## Refetch after a mutation
 
-**A successful workflow re-reads the queries that are mounted, on its own.** A workflow is the
-app's only write path, so the rows on screen are stale the moment one succeeds — the SDK
-re-reads them rather than making every call site remember to. Nothing to call:
+**A successful workflow re-reads the queries its body can have changed, on its own.** The server
+reads every table a bound workflow's body names; a success re-reads each query over one of them,
+mounted or not, so the rows on screen never wait for the host's push. Nothing to call, nothing to
+name:
 
 ```tsx
 const items = useQuery("items");
@@ -380,32 +323,25 @@ const closeItem = useWorkflow("closeItem");
 const onClose = async (recordId: string) => {
   const r = await closeItem({ record_id: recordId });
   if (r.status === "error") { showError(r.message); return; }
-  // items re-reads itself — a successful write already said so.
+  // items re-reads itself — its table is one the body names.
 };
 ```
 
-Only on **success**: a refused write changed nothing, and re-reading after one would swap the
-values the user is still looking at, and about to correct, for an identical set.
-
-It names every MOUNTED alias, not the ones the write touched — an app cannot know which tables
-a workflow body wrote, and a per-call-site list of what to invalidate goes stale silently the
-first time that body grows a second write. The cost is bounded by what is on screen.
+Only on **success**: a refused write changed nothing. A body that names a table only at run time,
+a run whose writes could not be predicted, a run before the app's write model has loaded, and a
+`useAgentRun` leg that lands, re-read every mounted query. A comment written or deleted re-reads
+every `useCommentCounts`. Under a design-time
+fixture every mounted read re-reads, since a fixture has no body to read tables from. The host's
+realtime push is separate: it carries changes **other** people make, and is far too slow for your
+own.
 
-This is separate from the host's realtime push, which carries changes **other** people make and
-travels a socket the host owns. That path is right for someone else's edit and far too slow for
-your own — waiting on it is what makes a screen feel like it lagged its own button.
-
-`refetch()` remains for the reads a write cannot know about: a poll, a value the user expects to
-change without writing anything, or a total you supplied yourself (below).
+`refetch()` remains for the reads a write cannot know about: a poll, or a value the user expects
+to change without writing anything.
 
 `refetch` re-runs the query in the background while the current rows stay on screen (no
-flash to a spinner — `loading` stays false during revalidation). `usePaginatedQuery`'s
-`refetch` re-runs the current page, and the count when the hook owns it — a total you supplied
-yourself is yours to refresh, so a write that changes the row COUNT must also refresh whatever
-you read it from, or the page moves while "of N" does not. Focus revalidation
-(`revalidateOnFocus`, default on) eventually self-corrects stale data, but never rely on it
-where the staleness is one of those three — the user is looking at the number now, not the
-next time they come back to the tab.
+flash to a spinner — `loading` stays false during revalidation). A `page` read's `refetch`
+re-runs the current page and its count. Focus revalidation
+(`revalidateOnFocus`, default on) eventually self-corrects, but never rely on it for those.
 
 ### A read must not overtake an in-flight write
 
@@ -415,32 +351,17 @@ mousedown, the button's handler on mouseup — so a handler that re-reads the re
 document, mint something, or copy the row can read the row as it was BEFORE the edit. It fails
 silently: the screen shows the new value, the output carries the old one.
 
-Serialize them with one barrier per record surface — every write chains on, and the ONE place
-that re-reads stored state awaits it, so no handler can forget:
+Await `writesSettled()` in the handler that re-reads stored state: it resolves once every record
+write this app has already sent — a workflow run or an agent run — has answered, whatever the
+answer; a write sent after the call, and a workflow that writes no record (a document, an export),
+is not waited for.
 
 ```tsx
-// Per surface, not module-level: useMemo(createWriteBarrier, []) inside the hook.
-export function createWriteBarrier() {
-  let chain: Promise<unknown> = Promise.resolve();
-  return {
-    // Returns the write UNCHANGED — the caller keeps its own result + error handling;
-    // the chain never rejects, it only tracks when writes SETTLE.
-    track: <T,>(write: Promise<T>): Promise<T> => {
-      chain = chain.then(() => write).catch(() => undefined);
-      return write;
-    },
-    settled: () => chain,
-  };
-}
-
-const saveField = async (key: string, value: unknown) => {
-  const r = await writes.track(saveRecord({ record_id, [key]: value }));
-  if (r.status === "error") throw new Error(r.message);   // the inline editor keeps the edit
-};
+import { rpc, writesSettled } from "@lotics/app-sdk";
 
 /** The ONLY re-read of stored state. Every handler goes through it — never the cached row. */
 const reload = async () => {
-  await writes.settled();
+  await writesSettled();
   const res = await rpc<{ rows?: Rec[] }>("query", { alias: "record", params: { id: record_id } });
   return res.rows?.[0] ?? null;
 };
@@ -467,8 +388,8 @@ to get right.
 
 An edit form snapshots the record's values when it loads, and on save sends **only the fields
 the user actually changed** to its update workflow. Declare each updatable input
-`required: false`; an omitted input means "not written" (the body guards each write — or hands
-them to `set_skip_null` — as shown above). "Changed" is decided at the edit surface that loaded
+`required: false`; an omitted input means "not written" (the body guards each write, or hands
+them to `set_skip_null`). "Changed" is decided at the edit surface that loaded
 the before-state — compare against the load-time snapshot, not against a re-fetch.
 
 Why a full-form snapshot save is a bug, not a style choice — three independent mechanisms:
@@ -519,7 +440,7 @@ Row-level query results carry a `__source_locked` addressing column automaticall
 `__source_record_id` — no projection needed; like all source addressing it survives
 project/filter/sort/join but not grouping, where rows stop being records).
 `readLocked(row)` — pass the **whole row**, not a cell — returns `true` for a locked record,
-`false` when the flag is absent (`dist/src/row.d.ts`). Use it to render a locked state and to
+`false` when the flag is absent (`dist/row.d.ts`). Use it to render a locked state and to
 switch the save path.
 
 ### What a write against a locked record does
@@ -590,61 +511,70 @@ const save = async () => {
 };
 ```
 
-## Optimistic reconciliation: `useOptimistic`
-
-For interactive data-bound views (calendar drag, gantt resize, kanban move) where waiting for
-the round-trip feels broken, `useOptimistic` overlays pending patches on the query result
-(`dist/src/use_optimistic.d.ts`):
-
-```ts
-const { items, patch } = useOptimistic(base, keyOf);
-patch(id, next, persist, opts?);
-```
-
-- `base` is the already-mapped item list (derived from `useQuery` rows); `keyOf` extracts each
-  item's stable key. `items` is `base` with pending patches merged per key (`{ ...item,
-  ...patch }`); repeated patches on the same key merge.
-- `patch(id, next, persist, { onSettled })` applies `next` immediately, then runs the
-  `persist` thunk. On **resolve**, the patch is *kept* and `onSettled` runs. On **reject**,
-  the patch is *reverted*.
-- **`onSettled` is not where you refetch the query the patch came from.** The `persist` thunk
-  calls `useWorkflow`, and a successful write re-reads every mounted query by itself — so the
-  re-read is already in flight before `onSettled` fires, and passing `refetch` here buys a
-  second execution of the same query. Keep it for what the write cannot know about: a total
-  you computed yourself, a "saving…" indicator to clear, an analytics call.
-- **A kept patch stays merged over `base` for the life of the view.** It is never cleared on
-  success — the design assumes it equals what the server stored, so the re-read lands
-  underneath it with no flicker. Patch the value you are SENDING, not a display form of it: if
-  the server normalizes (rounds a time, trims a string, resolves a link's label), the
-  optimistic value masks the stored one permanently and nothing reports it.
-
-**Warning — the persist thunk must throw on `status: "error"`.** `useWorkflow` resolves on
-failure (the failure model above), and a resolved promise means "kept" to `useOptimistic` —
-so a bare `() => reschedule({...})` thunk keeps the optimistic value on screen even when the
-workflow failed. Convert the status into a rejection:
-
-```tsx
-const q = useQuery("events");
-const reschedule = useWorkflow("rescheduleEvent");
-const mapped = useMemo(() => q.rows.map(toCalendarEvent), [q.rows]);
-const { items, patch } = useOptimistic(mapped, (e) => e.id);
-
-const onEventDrop = (ev: CalendarEvent, newStart: Date) =>
-  patch(
-    ev.id,
-    { start: newStart },
-    async () => {
-      // toISODate: the `@lotics/ui` local-date formatter → "YYYY-MM-DD"
-      const r = await reschedule({ record_id: ev.recordId, new_date: toISODate(newStart) });
-      if (r.status === "error") throw new Error(r.message ?? "Reschedule failed");
-    },
-  );
-```
-
-This is the full read → mutate → reconcile loop: `useQuery` reads, `row.*` coerces,
-`useWorkflow` mutates, `useOptimistic` covers the round-trip until the write's own re-read
-converges. Declare one workflow per (table, field) you mutate — typed and narrow, never a
-generic `setField(any_field)` that hands the client write access to every field
+## A write shows from the press
+
+**Every write is drawn on every read the moment it is made — with nothing to wire.** The server
+hands the app its **write model** (`GET /v1/apps/{app_id}/write_model`, read once at mount): each
+bound workflow's record writes and the steps they depend on, where each query's columns and rows
+come from, and the fields they name. `useWorkflow` walks the workflow's own steps against the rows
+the app has already read, with the evaluator the engine runs, and stages what it will write over
+every read before the request answers:
+
+- **Cells.** A written cell redraws in every column that reads it: an option as its label, a member
+  as the face a read or `useMembers` drew, a link as its label — and a column reading the linked row beside it
+  (a face) as that row's field, where a read has drawn that row.
+- **Formulas** of the written row recompute, where every field they read is held; one reading a
+  field no read carried waits for the server, and `pending` says so.
+- **Membership.** A row a read's filter — and the call's runtime `filter` — no longer admits
+  leaves it; a created row it admits joins it, standing by the read's order (the call's `sort`,
+  then the query's own) where its sort cells are numbers or dates, else first. A row the read does
+  not hold that a write may move into it waits for the server, and `pending` says so.
+- **Totals.** A `total`, a count per value (`total: { by }`), a group asked with `aggregate` or
+  declared by the query, and a parent's count or sum rollup move by exactly what the written row adds
+  or takes away; a group the last row leaves is gone, and a count per value gains the value a row
+  first holds. A mean, an extreme, a distinct count, a group by day, a group none of the read's rows
+  counted in yet, a read whose rows a search or a cap decides, or a row the app never read is left
+  as the server said it until a read asked after the write answers.
+- **A refusal takes it back**, and `result` says why, as always. A success keeps it until a read
+  asked after the write settled answers — the stored value then replaces the prediction, whatever
+  it said, so a server that rounds or trims wins with no flicker back to the old value. Where the
+  stored value differs from the one drawn, the SDK tells the server where — the workflow, table,
+  field and kind of miss, never the value.
+
+What the steps cannot tell before they run is never guessed:
+
+- A value from a query step, an agent, an integration, a member's groups, a cell no read carried:
+  the write that needs it is not drawn, and the read's `pending` is true until the answer lands.
+- A branch on such a value: every write under it waits for the answer — and where the branch can
+  end the run (`return`, `validate`, `break`), so does every write after it: a create that first
+  looks for a row to reuse draws nothing until the server says which it did. A `catch` block and a
+  `while` or counted `for` loop wait too.
+- A pause (`wait`, `wait_for_event`, `wait_for_approval`): every write after it waits for the answer.
+- A step that changes rows it cannot draw — `lock_records`, `restore_records`, a pressed button, an
+  agent whose tools can change rows, a `create_records` matching on a field, a filtered update or
+  delete: every read over the tables it may touch (every read, where it names none) is `pending`
+  until the answer lands.
+- A guard (`validate`, a `return` with `status: "error"`) it can decide over held rows: a refused
+  write draws nothing. One it cannot decide is assumed to pass — the server is the authority, and
+  a refusal takes the drawing back.
+- A guard or branch comparing an input with a constant (`i.code == "VIP"`) never reaches the app:
+  the constant would be shown to everyone who can open it. The guard is assumed to pass, and the
+  branch's writes wait for the answer. A comparison with a held row's cell reaches it.
+
+Every read hook returns **`pending`**: a write this app made is in flight over its rows, or has
+landed with part of what it changes not yet read back. The rows already show what is known; use it
+for a quiet "saving" cue, never to hide the rows.
+
+**A create gets its id before the server answers.** Every row a `create_records` makes without
+`ids` is drawn under a `rec_*` the SDK mints, and the run carries those ids to the server, which
+stores each row under the one drawn for it — so the row drawn from the press is the row the server
+stores, and every write that names it (a history line, a child filed under it) is drawn too. The
+body states nothing for this. A create that states its own `ids` keeps them; after a create the
+client cannot count, or one that may or may not run, the rows that follow wait for the server.
+`result.data` carries the id as the body returns it.
+
+Declare one workflow per (table, field) you mutate — typed and narrow, never a generic
+`setField(any_field)` that hands the client write access to every field
 ([security](./security.md)).
 
 ## Editing a record that does not exist yet: `useNewRecord`
@@ -670,9 +600,8 @@ const { id, save } = useNewRecord({
 - **The record is still created on the first write, not on mount** — a surface the user opens
   and abandons leaves nothing behind.
 - **`save` serialises.** The first call creates, every later one updates, and calls made before
-  the create resolves queue behind it. Two fields blurred in quick succession therefore produce
-  one record, not two. This is the whole reason to use the hook rather than a `useRef` latch:
-  hand-rolled, the racing-blur case creates a duplicate.
+  the create resolves queue behind it, so two fields blurred in quick succession produce one
+  record, not two.
 - **A failed create does not latch.** The next `save` retries the create, rather than updating a
   row that was never written while the UI looks like it saved.
 - `id` and `save` are stable across renders, so `save` can be bound directly to an `onBlur`.
@@ -685,12 +614,13 @@ Creation is creation: an id that already exists is a conflict, never an overwrit
 workflow cannot be used to clobber another record by guessing its id.
 
 Use `newRecordId()` directly if you need the id outside a hook (routing to the surface before
-mounting it, say). It mints the same `rec_*` shape the server validates.
+mounting it, say). It mints the same `rec_*` shape the server validates. A create made in one press
+needs neither: the SDK mints the id itself (above).
 
 ## Recording into a workflow: `useRecording`
 
 A recording act — record a site visit, a call, a meeting, and file it on the row it is about —
-is a workflow whose run waits for the transcript. Exact signature: `dist/src/recording.d.ts`.
+is a workflow whose run waits for the transcript. Exact signature: `dist/recording.d.ts`.
 
 ```tsx
 import { useRecording } from "@lotics/app-sdk";
@@ -727,7 +657,7 @@ await visit.stop();
   is still bound, and its declaration still receives recordings. A refused or failed filing is
   never retried by itself and the recording is never lost: the member retries from the
   product's bar, and a failed run also sends the app's owner the failed-run notice.
-- **`available`** is what the host states — false standalone, in `lotics app dev`, in a host
+- **`available`** is what the host states — false standalone, in a host
   that predates recording, on an instance without transcription, and until the context has
   answered. A standalone app has no member to record as; both calls reject there.