@lotics/app-sdk 0.77.1 → 0.77.3

package/AGENTS.md

@@ -14,7 +14,7 @@ signature; open the file.**
 
 | Doc | Read it for |
 |---|---|
-| [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. The templates a generated file is filled from are registered through the CLI, not the app — `lotics docs document_templates`. |
+| [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
 | [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
@@ -22,7 +22,7 @@ signature; open the file.**
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
-| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). **A `file` input carries its own content** — images/PDFs are perceived natively, Word/Excel/CSV/text are materialized into the run; no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`** (`run_app_query` / `run_app_workflow`); the raw record read/write tools are rejected., a leg's `AgentRunLanding` (`settled`/`parked`/`failed`/`aborted` — never a bare `undefined`) |
+| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state — and the `AgentRunLanding` every leg resolves), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). **A `file` input carries its own content** — no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`.** Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads and how to shape a mutating alias for it. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
 | [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
 

package/docs/ai.md

@@ -26,9 +26,9 @@ A declaration carries:
 | `workflow_aliases` | The app's own workflows the agent may invoke via `run_app_workflow` — its **entire write surface** |
 | `model_tier` | Optional model tier — `haiku` \| `sonnet` \| `opus`. Omit (preferred) to follow the platform default tier, resolved at run time. A tier names capability, not a version, so the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
 | `effort_level` | Optional reasoning depth for adaptive-thinking tiers. Requires an explicit `model_tier` pin — effort is tuned per tier |
-| `prefix_cache_ttl` | Optional prompt-cache window for the agent's stable prefix (tools + system). **Omit it** — the default (`"5m"`, Anthropic's own) is right for essentially every agent. `"1h"` is a leveraged bet: it doubles the write price (2x the input rate against 1.25x, both reading back at 0.1x) to buy only the five-minute-to-one-hour band, and an entry nothing re-reads inside the hour was paid for twice over. Declining it is never "uncached" — the same prefix stays cached at the default window. Set `"1h"` only with measured cadence showing runs reliably land in that band, such as a scheduled sweep |
+| `prefix_cache_ttl` | Optional prompt-cache window for the agent's stable prefix (tools + system). **Omit it** — the default (`"5m"`, Anthropic's own) is right for essentially every agent. `"1h"` is a leveraged bet: it doubles the write price (2x the input rate against 1.25x, both reading back at 0.1x) to buy only the five-minute-to-one-hour band. Declining it is never "uncached" — the same prefix stays cached at the default window. Set `"1h"` only with measured cadence showing runs reliably land in that band, such as a scheduled sweep |
 | `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it. **Every field defaults to `required: true`**, exactly as `outputs` does — the two extend the same base — so an input the caller may legitimately omit needs `"required": false`, or the run is rejected before the agent sees it |
-| `outputs` | Optional typed output schema. Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose). **Every field defaults to `required: true`** (the same base schema as `inputs` above) — mark `"required": false` on anything the source may legitimately not carry. It matters most for `number`, which has no blank: text can answer `""`, but a required number leaves only a wrong value or a rejected submission, and an agent handed that dilemma spends the run resolving it instead of doing the rest of its instructions |
+| `outputs` | Optional typed output schema. Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose). **Every field defaults to `required: true`** (the same base schema as `inputs` above) — mark `"required": false` on anything the source may legitimately not carry. It matters most for `number`, which has no blank: text can answer `""`, but a required number leaves only a wrong value or a rejected submission |
 
 **Structured vs free-text is the load-bearing split.** A structured agent's result arrives in `run.output` (the server strictly validates the submitted result against the declared schema — see the `output` typing section for the exact guarantee); a free-text agent's answer is the transcript's prose (`run.text`) and its `output` stays `undefined` — never a stray string, so a consumer reading `output.<field>` can't crash on a free-text answer.
 
@@ -198,7 +198,7 @@ On recovery, `output` adopts the row's output **only when it is an object** (a s
 
 - **The app owns the state.** Always pass the authoritative current state in `input` — the session context is memory, not the source of truth.
 - **Mint a new `sessionId` to clear context.** There is no reset call; a fresh key is a fresh session.
-- **One-shot agents get a fresh `sessionId` per run.** Session context only pays for conversational follow-ups. If every run is self-contained (the app passes the complete input each time — e.g. a document-extraction agent), reusing a key replays dead context into every request — every replayed run still bills its input tokens, so a one-shot agent on a shared key pays for history it never uses. Append a per-run nonce to the key instead. (Media itself replays as a provider file reference — uploaded once, referenced by id — so a long session no longer grows toward the provider's request-size cap; the cost of dead context is tokens, not payload.)
+- **One-shot agents get a fresh `sessionId` per run.** Session context only pays for conversational follow-ups. If every run is self-contained (the app passes the complete input each time — e.g. a document-extraction agent), reusing a key replays dead context into every request — every replayed run still bills its input tokens, so a one-shot agent on a shared key pays for history it never uses. Append a per-run nonce to the key instead. (Media itself replays as a provider file reference — uploaded once, referenced by id — so the cost of dead context is tokens, not payload.)
 
 Sessions are scoped to the authenticated member who ran them: two members using the same `sessionId` string share nothing, and a member can never read or extend another member's thread.
 
@@ -211,15 +211,14 @@ Sessions are scoped to the authenticated member who ran them: two members using
 | **Perceived natively** | `image/*`, `application/pdf` | A vision / document part — the agent literally sees it |
 | **Materialized** | Word (`.docx`/`.doc`), Excel (`.xlsx`/`.xls`), CSV, and text (`.txt`, `.md`, `.json`, `.eml`, `.html`, `.xml`, `.yaml`) | Read server-side by the same engines `view_files` uses and inlined into the run's message, truncated at 40,000 characters with the agent told when that happened |
 
-**Pictures inside a Word document are delivered as images**, so a scanned page, an ID card photographed into a `.docx`, or a screenshot pasted into one is READ, not merely described. A document whose content is entirely pictures carries no text at all — it used to arrive as empty paragraphs plus a size in centimetres, and the agent correctly reported it could not read it. Any picture that is skipped or unresolvable is counted and stated in the text, so a partially-read document never reads as a complete one.
+**Pictures inside a Word document are delivered as images**, so a scanned page, an ID card photographed into a `.docx`, or a screenshot pasted into one is READ, not merely described. Any picture that is skipped or unresolvable is counted and stated in the text, so a partially-read document never reads as a complete one.
 | **Unreadable** | Archives, audio, video | The run fails immediately, naming the file — a fact about the upload, not a gap in your configuration |
 
 Every file in a `multi` input is materialized — nothing is collapsed to the first. Get the ids from [`useFileUpload` / `useAttachments`](./files.md).
 
 **So do not dispatch on the file type.** Every tier above reads, which means the format tells you
 nothing about what a document IS — the same claim form arrives as `.xlsx` from a laptop, as a PDF
-through a chat app, and as a photo of a printout; an invoice arrives as PDF, as the XML beside it,
-or as a screenshot. An intake that routes on the extension is reading the envelope, and it fails
+through a chat app, and as a photo of a printout. An intake that routes on the extension is reading the envelope, and it fails
 SILENTLY: the wrong extractor runs, returns something correctly shaped, and the user is handed a
 confident wrong answer. Let one agent read the drop and say what each document is, keyed on what
 only the content carries. Prefer separate output slots (`don_hang`, `hoa_don`, plus a named
@@ -333,7 +332,7 @@ Declarative and lifecycle-bound: mounting or changing `context` pushes it; unmou
 | `data` | must JSON-serialize to ≤ 2000 chars, else it is **replaced by an `omitted` marker** the agent reads (the description is kept) |
 | slots per app | ≤ 8 (a 9th evicts the least-recently-updated) |
 
-Keep `description` tight and human-readable — it is the line the agent reads. Put anything structured (filter/sort/form values) in `data`, and remember it is replaced whole past its size cap: the agent is told the state existed but not what it was, so don't hide load-bearing facts there that aren't also in `description`. It is replaced rather than silently dropped so the agent cannot mistake "too big to send" for "there was nothing".
+Keep `description` tight and human-readable — it is the line the agent reads. Put anything structured (filter/sort/form values) in `data`, and remember it is replaced whole past its size cap: the agent is told the state existed but not what it was, so don't hide load-bearing facts there that aren't also in `description`.
 
 ### Security — push-only, a snapshot of what was already rendered
 
@@ -346,7 +345,7 @@ This hook is a **one-way push of data the app already showed this member**. (Cha
 
 `useAiContext` is a PUSH — a snapshot of what one screen rendered. It cannot
 answer a question about a record that is not on screen, and it is capped, so it
-was never the whole story.
+is not the whole story.
 
 While a member has an app open, their chat agent can also **call that app's own
 declared aliases** — named queries via `run_app_query`, workflows via
@@ -380,29 +379,42 @@ inputs object, and a select's legal values are your DECLARATION's — usually an
 inline set that matches no table field — so an agent reading option values off
 the underlying table would send ones your write rejects.
 
-Two things follow for you as an author. **Your descriptions are what it reads**,
-on this surface and inside your own agents' runs — they enter the prompt as a
-capability listing, never as instructions. And **a `select` input's options are
-part of the contract the agent sees**, so prefer the `field: "fld_…"` form when
-the values come from a real field: it resolves to that field's CURRENT options
-at both render and validation time, and can never drift out of sync with them.
-
-**Writes carry a second gate that reads do not: `run_app_workflow` asks the
-member to approve every call from chat.** A wrong read is fixed by asking
-again; a wrong write is not. The alias list bounds what an agent *could* reach;
-the approval is what stops the wrong one. Approval applies to the chat surface
-only — an app agent's run is already an explicit act with no human in the loop
-to answer.
-
-The prompt names the action and lists the inputs the agent chose, so **your
-input names are what the member reads before authorizing the write**. Name them
-for that reader (`ma_khach_hang`, `so_tien`), and keep the decisive ones
-top-level — a value nested inside an opaque payload shows as JSON, and long
-values are truncated. Context ids the member never chose (`app_id`,
-`workspace_id`, `organization_id`) are filtered out.
-
-Nothing about your app changes to get this — declare a workflow as you already
-do, and it becomes reachable. If a workflow should NOT be agent-reachable, it
+The app's own `description` heads that listing as `about:`, on both surfaces. It
+is the only channel that reaches the agent on **every** turn without the member
+saying anything, so a standing process belongs there: the recurring job the app
+exists for, which alias does it, and what the agent must leave alone.
+
+Three things follow for you as an author. **Your descriptions are what it
+reads**, on this surface and inside your own agents' runs — they enter the
+prompt as a capability listing, never as instructions. **A `select` input's
+options are part of the contract the agent sees**, so prefer the
+`field: "fld_…"` form when the values come from a real field: it resolves to
+that field's CURRENT options at both render and validation time. And **an
+input's `description` is the only place a DEFAULT is visible** — the catalog
+renders a name, a type, a `?` and your prose, never the body. An optional input
+whose default goes unstated is one the agent asks the member about instead of
+omitting; write what omitting it means ("left blank = today").
+
+**Put anything irreversible behind a
+[`wait_for_approval`](./workflows.md#wait_for_approval--the-one-wait-worth-binding):**
+an email, a shipment, a published post, a write over a value with no version to
+restore. The body's own gate is the only human checkpoint on this path — it
+names the act in the language of the business and reaches the approvers the
+workflow declares.
+
+**Shape a mutating alias around ONE call per job.** An alias that takes a single
+record turns a fifteen-record job into fifteen executions and no single answer to
+report, and a partial failure leaves it half done with nothing that says so. Take
+an array input instead — one call, one outcome. A narrow write is right for a
+screen's button, where the member picked the record by opening it; here nobody
+picked anything.
+
+**Report what it did NOT do.** The member's account of the write is assembled
+from what the workflow returned and nothing else, so a batch that matched nine of
+eleven and returns only success tells them all eleven were done. Return the
+misses in `data`.
+
+If a workflow should NOT be agent-reachable, it
 does not belong in the manifest at all, since the member can already fire it
 from the app's own buttons.
 

package/docs/data_fetching.md

@@ -170,8 +170,7 @@ const { rows, loadMore, hasMore, loadingMore } = useInfiniteQuery("feed", {}, {
 ```
 
 The first render loads one page; `loadMore()` appends the next, accumulating into `rows`. Paging is
-**keyset (seek)** — appended pages never skip or duplicate a row as the set shifts (the pagination
-models above).
+**keyset (seek)** (the pagination models above).
 
 - `hasMore` is `true` while the last page came back **full** (a non-null cursor came back) — so a
   total that is an exact multiple of `pageSize` costs one final short fetch before `hasMore` turns
@@ -398,13 +397,12 @@ pieces. Compose these — don't hand-roll search:
   popover listbox with rich rows (`renderOptionContent`), keyboard navigation, `recentOptions`,
   `allowCustom`. (For a known small list with no search box, `Picker`.)
 - **A parameterized `search` query** — a `from_table` with `search: "{{params.q}}"` over the
-  maintained search document: **diacritics- and case-insensitive** (`"da nang"` matches
-  `"Đà Nẵng"`), trigram-indexed so it stays fast on large tables, and AND-ed with the template's
-  `filter` (search within a scope). The full `search` contract is in
+  maintained search document: **diacritics- and case-insensitive**, trigram-indexed, and AND-ed
+  with the template's `filter` (search within a scope). The full `search` contract is in
   [./queries.md](./queries.md). Reserve an OR-group of per-field `contains` only when you must
-  bound exactly which fields match — `contains` is case-insensitive but **accent-sensitive** and
-  **unindexed**, so a zero-match keystroke forces a full table-partition scan that hangs the
-  picker. **Search-as-you-type uses `search`, never a `contains` OR-group.**
+  bound exactly which fields match — `contains` is **unindexed**, so a zero-match keystroke
+  forces a full table-partition scan. **Search-as-you-type uses `search`, never a `contains`
+  OR-group.**
 - **`useQuery(alias, { q }, { enabled })`** — gate on a non-empty term: an empty term applies no
   search constraint and would dump the table on first paint. `enabled` makes "nothing loads until
   you type" true. Add `revalidateOnFocus: false` — re-running an ephemeral search on refocus is

package/docs/files.md

@@ -44,17 +44,16 @@ Signature: `dist/src/hooks.d.ts`. Returns `{ upload, uploading, error }`:
   `{ id, filename, mime_type, url?, thumbnail_url? }` — `url`/`thumbnail_url` are presigned
   (24 h) and load directly in the sandboxed iframe, so a just-uploaded image previews without a
   round-trip.
-- `fidelity` — **how faithful the stored image must be.** An ordinal scale, so the value tells
-  you what it costs without looking up a mapping. The platform owns the pixels behind each step
-  and re-tunes them centrally as model tiers change.
+- `fidelity` — **how faithful the stored image must be.** The platform owns the pixels behind
+  each step and re-tunes them centrally as model tiers change.
 
   Defaults to `"high"` — enough to resolve the text of a photographed document. Drop to
   `"standard"` when collecting in volume.
 
   **This only affects photographs.** A PDF, Word, Excel or CSV file is stored untouched at every
-  step, so `"original"` is not what keeps a document intact — it already is. Reach for it when
-  the PIXELS are the evidence. Note too that HEIC (what an iPhone camera produces) is transcoded
-  to JPEG server-side whatever you choose, because no browser can render it.
+  step, so `"original"` is not what keeps a document intact — it already is. Note too that HEIC
+  (what an iPhone camera produces) is transcoded to JPEG server-side whatever you choose, because
+  no browser can render it.
 
   | `fidelity` | Use it when | Stored at |
   |---|---|---|

package/docs/mutations.md

@@ -302,10 +302,7 @@ await update_records({
 ```
 
 `set` still writes every key it carries — `null` in `set` **clears** the field; `null`/absent in
-`set_skip_null` **skips** it. That is the per-field "clear vs. leave unchanged" choice, so a field
-may appear in **at most one** of `set` / `set_skip_null` (naming it in both is rejected at run
-time). An all-absent `set_skip_null` with no other write surface is a no-op — no records touched,
-no `before_update` hooks. The full write surface (`set`, `set_skip_null`, the surgical
+`set_skip_null` **skips** it. The full write surface (`set`, `set_skip_null`, the surgical
 `add_to`/`remove_from`/`replace` ops, `field_edits`, and the exact value shape per field type)
 is [workflows](./workflows.md#writing-records).
 

package/docs/navigation_and_state.md

@@ -22,8 +22,7 @@ mechanism:
 They compose: a screen is a path; the screen's filters ride as query params.
 Neither is server state — `useUrlState` values are *client* state that you feed
 into a query's *server* params (see [named-query params](./queries.md) and the
-[data-fetching hooks](./data_fetching.md) they drive). Nothing here is
-persisted server-side; the address bar is the only store.
+[data-fetching hooks](./data_fetching.md) they drive).
 
 The embedded-vs-standalone distinction below is the runtime's: embedded means
 the app runs in an iframe inside the Lotics host, standalone means it runs on

package/docs/queries.md

@@ -6,8 +6,7 @@ Every read a custom-code app performs is a **named query**: a fixed AST template
 for the hook-side contract). This document is the authoring reference for the query engine
 itself: the node kinds, the source expressions, the per-field-type operator support, filters and
 params, search, cross-table composition, server-side shaping, runtime refinement, and the
-engine's hard limits. Read it before writing any non-trivial query — the engine is deliberately
-a small closed surface, and knowing what composes (and what doesn't) up front saves hours.
+engine's hard limits.
 
 ---
 
@@ -204,13 +203,12 @@ indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank
   collection.** `{ "type": "files", "output": "photo", "source": "fld_…", "limit": 1 }` returns
   the first entry per cell, in stored order, cut in SQL so the rest is never read or signed.
   Without it the cell yields the whole array and the response pays to resolve every entry it
-  will never show: a register over containers averaging 33 gate photos each resolved ~832 files
-  to display 25 thumbnails, within 2.4× of the response-wide presign ceiling (§10) that would
-  reject the query outright. The bound is per CELL and caps at `FILES_PROJECTION_MAX_LIMIT`
-  (10) — a row wanting more than a handful is asking for the collection, which belongs to the
-  record surface that opens it. It is a different axis from the query's own `limit`, which
-  counts ROWS; `limit` on any non-`files` column — or on a computed source, which has no cell
-  to bound — is rejected at deploy rather than ignored. **On a UNION, set it on every arm.**
+  will never show — at scale, into the response-wide presign ceiling (§10). The bound is per
+  CELL and caps at `FILES_PROJECTION_MAX_LIMIT` (10) — a row wanting more than a handful is
+  asking for the collection, which belongs to the record surface that opens it. It is a
+  different axis from the query's own `limit`, which counts ROWS; `limit` on any non-`files`
+  column — or on a computed source, which has no cell to bound — is rejected at deploy rather
+  than ignored. **On a UNION, set it on every arm.**
   Arms align by column name and type, and `limit` is neither, so an arm that omits it still
   yields whole cells — the query stays correct and silently costs what the bound was there to
   avoid.
@@ -622,11 +620,10 @@ non-empty term client-side (`enabled`), or first paint dumps the table.
 search document indexes select option labels, member names, dates in three formats, and each
 linked record's cached display text — including the `Field=True/False` pill a boolean renders
 into. A box captioned "find a person" then matches rows that merely share a stage label or an
-owner, and folding makes near-homographs collide (`tiến` ≡ `tiền`). Measured on a real 88-row
-customer book, one such term returned **every row**. When the box means *find this person*, bound
-it: an OR-group of `contains` over the two or three identity fields (name, national id, phone),
-with the term param `required: false` so an empty box prunes the group to match-all. Use `search`
-when the box genuinely means *find this anywhere in the record*.
+owner, and folding makes near-homographs collide (`tiến` ≡ `tiền`). When the box means *find
+this person*, bound it: an OR-group of `contains` over the two or three identity fields (name,
+national id, phone), with the term param `required: false` so an empty box prunes the group to
+match-all. Use `search` when the box genuinely means *find this anywhere in the record*.
 
 ---
 
@@ -815,33 +812,18 @@ facet-aware, but it ships every matching row, so it holds only where the scope i
 (one member's own records, a single project). A workspace-wide total that must follow a runtime
 facet has no server-side shape today.
 
-The SDK hooks map onto this directly (`dist/src/hooks.d.ts` for exact signatures): `useQuery`
-sends `limit: pageSize, offset: 0` (a cap, not pagination) plus `opts.sort`/`opts.filter`;
-`useInfiniteQuery` pages by **keyset** (`keyset: true` + the prior `next_cursor`), so its scroll
-never skips or duplicates a row; `usePaginatedQuery` owns the page cursor, pages by `offset`, and
-issues a `count` keyed on `(alias, params, filter)` — independent of page and sort, so paging and
-re-sorting never recount, while changing `(params, filter)` resets to page 0 and recounts. Given
-its `total` option it issues none at all: a screen that already renders that figure from an
-aggregate hands it over rather than buying it twice
-([data_fetching](./data_fetching.md) → `usePaginatedQuery`).
+The SDK hooks map onto this directly — the hook-side contract is
+[data_fetching](./data_fetching.md).
 
 Build `filter` from UI column-filters with `columnFilterToConditions` (`@lotics/ui`); prefer
 `useFieldOptions` for a select filter's option set.
 
 **Warning (transport gaps):** the embedded product host and the `lotics app dev` forwarder pass
 `sort`/`filter`/`count` through. The **standalone public transport** (`<slug>.lotics.app`)
-currently forwards only `alias`/`params`/`limit`/`offset` — runtime `sort`/`filter` are
-silently ignored there and a `count` never resolves, so a standalone pager has no "of N" unless the
-app supplies one through `usePaginatedQuery`'s `total` (a plain aggregate query survives the thin
-transport). A standalone app must bake ordering/scoping into the template (or params) rather than
-rely on runtime refinement.
-
-**Pagination semantics.** `useQuery` / `usePaginatedQuery` and manual `rpc("query", { limit,
-offset })` are **offset** — a deep page costs the server the full skipped prefix (page 400 of a
-25-row pager scans ~10,000 rows before returning 25), and pages can shift under concurrent writes
-(a row inserted before your offset repeats or skips a row across pages). `useInfiniteQuery` is
-**keyset (seek)** — deep scrolls stay O(page) and never skip/duplicate rows. Keep offset browses
-filtered and sorted by a stable key, and don't build numbered UX that walks thousands of pages.
+forwards only `alias`/`params`/`limit`/`offset` — runtime `sort`/`filter` are silently ignored
+there and a `count` never resolves ([data_fetching](./data_fetching.md) → Standalone transport).
+A standalone app must bake ordering/scoping into the template (or params) rather than rely on
+runtime refinement.
 
 ---
 
@@ -1062,8 +1044,6 @@ above, with `region` replaced by whatever the lookup pointed at.
 
 ## 12. Current limitations
 
-Consolidated from the sections above — these describe present engine behavior:
-
 - **No pivot/crosstab node.** Row-values-to-columns happens client-side over grouped results
   (§8).
 - **No `first_value`/`last_value`/`nth_value` navigation** — the `functions` set is `row_number`,

package/docs/recipes.md

@@ -1,8 +1,7 @@
 # Recipes — the app actions that are not obvious
 
 The other area docs describe contracts. This one is task-shaped: **"how do I do X"**, for the
-handful of actions whose mechanism is not guessable from the hooks alone. Each was worked out
-against the running platform once — the point of writing them down is that nobody re-derives them.
+handful of actions whose mechanism is not guessable from the hooks alone.
 
 ---
 
@@ -11,7 +10,7 @@ against the running platform once — the point of writing them down is that nob
 A button that produces a file — a quotation, a debit note, a label — and hands it over, touching
 **no** record.
 
-**The mechanism is the return channel, and it is not the one you would guess.** Any workflow tool
+**The mechanism is the return channel.** Any workflow tool
 whose step output carries a `file_id` (`generate_pdf_from_template`, `generate_excel_from_template`,
 `generate_word_from_template`) is auto-collected by the execute endpoint and comes back in
 **`result.files[]`**, each with a servable `url`.

package/docs/runtime.md

@@ -134,9 +134,7 @@ clear the gate: `<slug>.lotics.app` is served by the app-host Worker, which
 withholds every byte of the bundle and serves a password page instead. On
 success it sets `lotics_app_session` on the app's origin; the SDK reads that
 cookie and forwards it as `X-Lotics-App-Session` on data calls. The SDK owns no
-password UI — a gate is a property of *serving* an app, not of fetching data,
-so it lives at the serving layer where one styled, localized page covers every
-public app. A `401` with error code `PASSWORD_REQUIRED` (the owner rotated or
+password UI. A `401` with error code `PASSWORD_REQUIRED` (the owner rotated or
 cleared the password) reloads the page, which puts the visitor back through the
 gate. What the password does and doesn't protect: [security](./security.md).
 
@@ -173,9 +171,7 @@ surfaces:
 | `agentRuns` (session history) | **no** — the product host doesn't implement it either (`"Unknown RPC op: agentRuns"`) | **no** | yes |
 | `askAi` | yes | **no** — `"Unknown RPC op: askAi"` | rejects — `"askAi is only available when the app runs inside Lotics"` |
 
-**Limitation:** agent-run **history** (`agentRuns`) is not implemented by the
-embedded product host *or* the dev forwarder — both error `"Unknown RPC op:
-agentRuns"`. Don't build a session-log UI on `useAgentRuns`; keep the log in app
+**Limitation:** Don't build a session-log UI on `useAgentRuns`; keep the log in app
 state from live `useAgentRun` results (see [ai](./ai.md)). Server-side *cancel*
 also errors in the dev loop (the local abort of a live stream still works) —
 verify cancel on a deployed app. The standalone `query` transport forwards only
@@ -355,8 +351,7 @@ install `posthog-js` or call any analytics API from app code.
   replay are off (autocapture is disabled at the project level — a client flag
   could not re-enable it). System signals are deliberately not events: data
   reads (`useQuery` fetches) and workflow/agent run outcomes. The backend
-  already logs and persists every run (`workflow_executions`, `app_agent_runs`),
-  so a client run event would be redundant system telemetry, not a gesture.
+  already logs and persists every run (`workflow_executions`, `app_agent_runs`).
 - Events the SDK emits automatically:
 
 | Event | Fired when | Properties |

package/docs/workflows.md

@@ -540,6 +540,30 @@ the **diff**: `changes["fld_link"]?.next_value` / `?.prev_value` are plain id ar
 has nowhere to attach a fetch, so it cannot descend either), and they feed `set:` directly.
 Everywhere else, write `[x.id]`.
 
+### A write that will be re-run
+
+The tables above answer *what the caller sent*. A workflow an agent can reach
+needs the other axis too — **what the record already holds** — because the same
+call arrives twice: a recurring report a week later, a retry, one batch
+overlapping the last. On that second pass an unconditional `set` reports success
+and silently replaces what was there.
+
+Decide per field, and expect the two directions of one operation to be
+**asymmetric**. A field recording *when* something happened is written only while
+it is still empty, while its undo clears unconditionally:
+
+```js
+if (i.undo) {
+  await update_records({ table_id: "tbl_x", record_ids: [row.id], set: { fld_submitted_on: null } });
+} else if (isNull(row["fld_submitted_on"])) {
+  await update_records({ table_id: "tbl_x", record_ids: [row.id], set: { fld_submitted_on: i.on } });
+}
+```
+
+There is no version to restore a cell from, so prove it before anyone can call
+it: `lotics app workflow run <alias>` the same input twice, and confirm the
+second run changed nothing.
+
 ### Authorizing the caller
 
 A workflow runs under the **app owner's** authority, so its own principal tells you nothing about

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.77.1",
+  "version": "0.77.3",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {