@lotics/app-sdk 0.46.1 → 0.47.1

package/docs/ai.md

@@ -0,0 +1,201 @@
+# AI in apps
+
+An app has two AI surfaces, and they answer different questions. **`useAgentRun(alias)`** runs an agent *declared on the app* — a streaming, tool-looping run whose result lands back **in the app** (a typed structured output, or free-text prose) for the app to review and commit through its own [workflows](./mutations.md). **`askAi(args)`** is a *handoff* — it opens the Lotics chat messenger seeded with files, records, and a prefilled prompt, and the outcome lands **in chat**, under the signed-in member's control. Read this doc when adding any AI-driven feature to an app; read [security](./security.md) first for the authority model agent runs execute under. Exact signatures: `dist/src/hooks.d.ts` (`useAgentRun`, `useAgentRuns`), `dist/src/agent_stream.d.ts` (`AgentRunItem`, `AgentRunStep`, `AgentRunState`), `dist/src/ask_ai.d.ts` (`AskAiArgs`).
+
+## Choosing the surface — the fields-vs-file razor
+
+- **The outcome lands in *fields*** — extract, check, match, rank, classify; structured judgment the app commits into its own data behind a review surface → **`useAgentRun`**. The run's `output` is typed against a declared schema, and the app owns the commit path (show the proposal, let the user correct it, then write via a workflow).
+- **The outcome is a *file* or an *open-ended answer*** — "edit this invoice", "draft an email about this order", iterating on a document, a question with no fixed shape → **`askAi`**. Dialogue-shaped work belongs in chat; its outcome never flows back into the app's workflows.
+
+Don't run a structured extraction through `askAi` (the result is stranded in a chat thread), and don't wedge document-editing dialogue into `useAgentRun` (a flat run log is not a conversation surface).
+
+---
+
+## Declared agents — what `useAgentRun` runs
+
+An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`). `lotics app deploy` ships code and queries only — it never binds agents. The `lotics.agents` map in `package.json` is a **read-only reflection** written by `lotics app pull`; hand-editing it does nothing. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`. (After a deploy, the CLI warns about any manifest alias not bound on the server.)
+
+A declaration carries:
+
+| Field | Meaning |
+|---|---|
+| `instructions` | System instructions — the task the agent performs per run |
+| `tool_names` | The tools the agent may call, resolved against the platform's automation tool registry. **This is the capability boundary** — the run can use nothing else. May be empty for a pure-reasoning agent |
+| `model_id` | The chat model the agent runs on |
+| `effort_level` | Optional reasoning depth for adaptive-thinking models |
+| `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 |
+| `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) |
+
+**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.
+
+**Input validation and tenant bounds.** Run inputs get the same server-side enforcement as workflow inputs: `record_link` ids must live in the declared table, `member` ids in the declared group, `file` ids in the app's workspace (see [the caller boundary](./security.md)). The run executes under the **app owner's** authority in the app's own workspace.
+
+**Typing.** `lotics app pull` / `lotics app codegen` emit `.lotics/app_agents.d.ts`, which augments the SDK's `AppAgents` (alias → input shape) and `AppAgentResults` (alias → declared output shape) interfaces — `useAgentRun("recognize")` then types both `run(input)` and `output`. An alias with no codegen falls back to `Record<string, unknown>` input / `unknown` output.
+
+---
+
+## `useAgentRun(alias)`
+
+```tsx
+import { useAgentRun } from "@lotics/app-sdk";
+
+const recognize = useAgentRun("recognize");
+await recognize.run({ image_file_id: fileId }, { sessionId });
+// live: recognize.status, recognize.items
+// done: recognize.output (structured) or recognize.text (free-text)
+```
+
+### The return surface
+
+| Member | Type | What it is |
+|---|---|---|
+| `run` | `(input, { sessionId }) => Promise<TOutput \| undefined>` | Start a run. Streams progress into the hook's state and resolves to the structured output (`undefined` for a free-text or failed run). Calling it again **aborts any run still in flight** |
+| `cancel` | `() => void` | Stop the run **server-side** (saves tokens) and locally. Wire a user-facing Stop button to this |
+| `abort` | `() => void` | Stop listening **locally only** — the run keeps executing server-side and its result is still persisted. This is the unmount path (the hook calls it automatically on unmount) |
+| `status` | `"idle" \| "streaming" \| "completed" \| "error"` | Whole-run state. `abort`/`cancel` reset it to `"idle"` (and clear the partial transcript) |
+| `items` | `AgentRunItem[]` | The ordered live transcript — answer prose, thinking, and tool steps, in stream order. The single source of truth for the feed |
+| `text` | `string` | The agent's **answer prose** (every `text` segment concatenated), accumulating live. Excludes thinking. For a free-text agent this IS the result |
+| `steps` | `AgentRunStep[]` | Only the tool/step items — a backward-compat view derived from `items`. Prefer `items` (it keeps the text↔reasoning↔tool ordering) |
+| `output` | `TOutput \| undefined` | The structured result once the run completes. `undefined` when the run produced none |
+| `error` | `string \| undefined` | The failure message when `status` is `"error"` |
+
+### The `items` transcript → `@lotics/ui` `AgentRun`
+
+`AgentRunItem` is a discriminated union in stream order:
+
+| `type` | Carries | Rendering intent |
+|---|---|---|
+| `"text"` | `id`, `text` | Answer prose, grows as it streams |
+| `"reasoning"` | `id`, `text` | The agent's thinking — a **distinct segment**, kept out of `text`, so the UI can show it collapsed / revealed on demand |
+| `"step"` | `AgentRunStep`: `id`, `label` (raw tool name), `status` (`"running" \| "done" \| "error"`), `kind`, `input`, `output`, `errorText`, `detail`, `streamedChars` | One tool call — opens `"running"` the moment it fires, settles when its result arrives. `input`/`output` ride along for an on-demand reveal, not for the feed. While a call's arguments are still generating, `detail` carries a live size ("18 KB", accumulated in `streamedChars`) so a long generation reads as progressing; both clear when the call's output arrives (a call that settles `"error"` keeps its last size) |
+
+The shape is structurally the `AgentRunItem` that `@lotics/ui`'s `AgentRun` component takes, so the pairing needs **no adapter and no hand-assembly**:
+
+```tsx
+<AgentRun
+  items={run.items}
+  state={run.status === "streaming" ? "streaming" : run.status === "error" ? "error" : "done"}
+  labelForTool={(name) => toolLabels[name]}  // optional: localize tool labels
+/>
+```
+
+`AgentRun` renders thinking collapsed, groups consecutive tool steps, and shows each tool's input/output in a press-to-open peek — all for free. Never rebuild this feed from `text` + `steps`.
+
+### `output` typing and the inner-field caveat
+
+The server validates the agent's submitted result strictly (unknown keys rejected, required fields present, types checked, `select` values bound to the declared options); an invalid submission is rejected back to the agent with the validation errors, and the agent retries. A run only settles **completed** with a result that passed this — so on a completed run, `output.items.map(...)` on a declared array field is safe. What that does **not** guarantee:
+
+- a field declared `required: false` may be absent;
+- a `json`-typed output field is passthrough — anything goes inside it;
+- `date` / `datetime` / `email` outputs are validated only as strings, not as well-formed values;
+- every **value** was authored by the model — a schema-valid string can still be semantically wrong;
+- one live-stream corner: the hook adopts `output` from the submit call's **arguments as they stream**, before the server-side validation runs. Normally the loud rejection makes the agent retry and the last (valid) submit overwrites it — but a run whose *final* submit was rejected ends the live stream with that invalid attempt still in `output` (the persisted run settles as an error). The review surface below is the backstop.
+
+Treat `output` as a trusted *shape* carrying untrusted *values*: render it into a review surface and let the user confirm before a workflow commits it. Never write model output straight to records without a review step.
+
+### Errors — two channels, handle both
+
+1. **`run()` rejects (throws)** when the run can't start or the stream fails unrecoverably: AI-credit quota exhausted, the per-member concurrency cap, an undeclared alias, input validation failure, or a network error. Wrap the call in try/catch and surface the message.
+2. **An in-run failure resolves.** A model or tool error mid-run arrives as a stream frame: `run()` resolves `undefined`, `status` becomes `"error"`, and `error` carries the message. Checking only try/catch misses this path; checking only `status` misses the first.
+
+```tsx
+try {
+  const output = await recognize.run(input, { sessionId });
+  if (recognize.status === "error" || output === undefined) { /* surface recognize.error */ }
+} catch (err) { /* quota / network / validation — surface err.message */ }
+```
+
+Server-side failure modes are not all equally loud. A mid-run model/tool exception and the max-duration cap surface through channel 2 (the live run errors; a capped run's live message is a generic "The run was stopped." — the persisted run carries "Run exceeded the 20-minute limit."). But two modes are **quiet on the live stream**: a structured agent that finished without ever submitting a result, and a free-text agent that produced no text, end the live stream with `status` `"completed"` and no result — only the *persisted* run settles as an error ("Run ended without producing a structured result." / "Run produced no output."). On the live hook the only signal is the missing output, which is why the example checks `output === undefined` and not just `status`.
+
+### `cancel` vs `abort`
+
+| | `cancel()` | `abort()` |
+|---|---|---|
+| Server effect | Stops the run server-side — saves tokens; the run settles as `aborted` | **None** — the run keeps executing to completion and its result is persisted |
+| Local effect | Clears state to `idle` | Clears state to `idle` |
+| Use for | A user-facing **Stop** button | Unmount / navigating away (the hook already calls it on unmount) |
+
+Both settle the in-flight `run()` promise cleanly with `undefined` — a stop is not a failure. A dropped connection does **not** cancel a run; `cancel()` is the only stop path.
+
+**Warning:** server-side cancellation is honored *between agent steps* — a cancel issued mid-way through one long generation takes effect at the next step boundary, not instantly. The UI should reflect "stopping" optimistically (the local state clears at once).
+
+### Runs survive dropped connections
+
+The run's lifetime is decoupled from the stream: the server drives it to completion and persists the result even if the connection drops. The hook reads the run id from the stream's start; if the connection then fails, it **polls the persisted run to completion** (every 2.5 s, bounded at 11 minutes) and resolves with the settled result instead of surfacing a network error — a long extraction is never lost to a flaky connection. Only when no run id was ever received (the run never started) does the failure reject.
+
+**Warning:** on this recovery path the hook adopts the *persisted* run's output — and a **free-text** run is persisted with its final answer text as the output. So after a connection-drop recovery, a free-text agent's `output` can carry the answer **string** (the one place the "never a stray string" rule doesn't hold), while `text` keeps only what streamed before the drop. If you consume free-text agents, guard with `typeof output === "string"` on the resolved value.
+
+### Sessions
+
+`run()` requires `{ sessionId }` — an **app-minted opaque key** grouping runs into a working session. Each run replays the session's prior **completed** runs (their inputs and outputs, including re-materialized image/PDF inputs) as conversation context, so a follow-up like "make it a bit less" resolves against the previous result. Two rules keep this sane:
+
+- **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.
+
+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.
+
+### File inputs → vision
+
+A declared `file` input (single or `multi`) is materialized into the model's native perception when the type supports it: **`image/*` becomes a vision part, `application/pdf` a document part** — the agent literally sees the file, no OCR tooling needed. Any other type (docx, xlsx, csv, …) is passed as a `file_id` reference instead; the agent can only open it if a file-reading tool is in its declared `tool_names`. Every file in a `multi` input is materialized — nothing is collapsed to the first. Get the ids from [`useFileUpload` / `useAttachments`](./files.md).
+
+### Auth, quota, and bounds
+
+- **Member-authenticated, embedded-only.** Agent runs require a signed-in member — an anonymous visitor to a public/standalone app is rejected with an explicit error ("App agent runs require an authenticated member…"). Runs work embedded in the product and in the `lotics app dev` harness (where they run as the CLI key's member).
+- **Owner-billed.** Token usage is recorded against the app's organization's AI credits. The quota is enforced before the first model call (a `run()` rejection) and re-checked between steps (a mid-run exhaustion settles the run as an error).
+- **Hard duration cap: 20 minutes per run.** A capped run settles as an error — but with whatever partial transcript and captured output it produced, recoverable from the persisted run.
+- **Concurrency cap: 5 in-flight runs per member.** Exceeding it rejects with "Too many agent runs in progress".
+
+**Limitation (dev harness):** `lotics app dev` streams runs but does not forward the run id, so in the dev loop `cancel()` degrades to a local `abort()` (the run keeps executing server-side) and connection-drop recovery is unavailable. Both work fully in the embedded product.
+
+---
+
+## `useAgentRuns(sessionId, opts?)` — session history
+
+Reads a session's persisted run history, oldest-first: `{ runs, loading, error, refetch }`, where each `AgentRunRecord` carries `id`, `agent_alias`, `session_id`, `status`, `input`, `output`, `error_message`, `started_at`, `completed_at`. `opts` takes `{ enabled?, revalidateOnFocus? }`. A persisted record's `output` is the validated structured object for a structured agent and the **final answer string** for a free-text agent.
+
+**Limitation:** the embedded product host does not currently implement the history op — `useAgentRuns` errors with "Unknown RPC op: agentRuns" in an embedded app, and the dev harness rejects it the same way (standalone anonymous callers are rejected as unauthenticated). The history *exists* server-side (it is what feeds session context), but this hook cannot read it from any current transport. Do not build a session-log UI on it yet; keep the visible log in app state from the live `useAgentRun` results instead.
+
+---
+
+## `askAi(args)` — the chat handoff
+
+```tsx
+import { askAi } from "@lotics/app-sdk";
+
+await askAi({
+  file_ids: [file.id],
+  record_ids: [row.id],
+  prompt: "Update the header of this invoice to match our letterhead.",
+});
+```
+
+Opens the Lotics messenger on a **fresh chat**, seeded with the given payload. The contract:
+
+| Arg | What the host does with it |
+|---|---|
+| `prompt` | **Prefills the chat composer.** The user sees it, can edit it, and sends it themselves — **nothing runs until they press send** |
+| `file_ids` | Files to attach (ids from [`readFiles(cell)`](./files.md) or an upload). The host resolves each id itself and attaches the current version; a **single** file also opens in a preview pane beside the chat |
+| `record_ids` | Records the chat should know about (ids from query rows). The host resolves them to table context — the agent can then read and act on them **under the signed-in member's authority** |
+| `context` | Free-text grounding ("Order ORD-2481, customer Acme…"). The host stamps the app's identity (id + name) alongside it automatically |
+
+At least one of the four is required — an empty call rejects. The bridge carries only ids and text; the host resolves everything as the signed-in member, so the handoff can only surface what that member could already open. An unresolvable file or record is dropped with a visible toast and the rest of the handoff proceeds.
+
+**Name the task in `prompt`.** Word/Excel file bytes are not inlined into the model's context — a clear brief ("update the header of this invoice…") makes the agent read the attached file first instead of asking what to do.
+
+**Embedded-only.** `askAi` rejects in standalone mode ("askAi is only available when the app runs inside Lotics") and in the `lotics app dev` harness (unknown op). It also rejects on the rare embedded screen where the chat surface is unavailable ("chat is unavailable on this screen") — treat the returned promise's rejection as a real path and surface it.
+
+`askAi` returns once the handoff is delivered; it never reports what the user or agent did afterwards. If the app needs the outcome, that's the razor telling you to use `useAgentRun`.
+
+---
+
+## Version floors
+
+The floors below are when each capability shipped in `@lotics/app-sdk`; an app pinned older silently lacks them.
+
+| Capability | Minimum version |
+|---|---|
+| `useAgentRun` (with `abort`) + `useAgentRuns` | `@lotics/app-sdk` 0.34 |
+| `cancel()` (server-side stop) + connection-drop recovery | `@lotics/app-sdk` 0.37 |
+| `items` transcript (reasoning segments + per-tool `input`/`output`) | `@lotics/app-sdk` 0.43; rendering pairs with `@lotics/ui` ≥ 7.13 (`AgentRun` `items` prop) |
+| Live streamed-argument size on a running step (`detail`) | `@lotics/app-sdk` 0.44 |
+| `askAi` | `@lotics/app-sdk` 0.45 |

package/docs/data_fetching.md

@@ -0,0 +1,349 @@
+# Data fetching
+
+How an app reads data: the three read hooks (`useQuery`, `useInfiniteQuery`, `usePaginatedQuery`),
+their caching/revalidation and pagination contracts, the typed cell readers that decode query rows
+(`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`
+for complete select option sets, the data-discipline rules, and the two load-bearing read patterns
+(search-as-you-type, browse/record-picker). Authoring the named queries these hooks invoke — the
+AST, params, filter operators, aggregation, performance contract — is [./queries.md](./queries.md);
+every write goes through a workflow — [./mutations.md](./mutations.md). Exact signatures:
+`dist/src/hooks.d.ts`, `dist/src/row.d.ts`, `dist/src/select.d.ts`, `dist/src/members.d.ts`.
+
+The read model in one paragraph: an app never sends a raw query. It invokes a **named query by
+alias** (declared in `package.json#lotics.queries`) and fills the template's declared `{{params.x}}`
+value holes; the server holds the canonical AST and runs it under the **app owner's** authority
+(per-viewer scoping is a template concern — see [./security.md](./security.md)). Per-app CLI
+codegen augments `AppQueries`, so an undeclared alias is a compile-time error and params are typed
+per the manifest. Each hook is a thin wrapper over the host RPC bridge with an SWR cache in front.
+
+## Choosing a hook
+
+| Hook | Result shape | Reach for it when |
+|---|---|---|
+| `useQuery(alias, params?, opts?)` | one fetch, `rows` | a detail read, a dashboard block, a combobox's top-N — anything that is not a long list |
+| `useInfiniteQuery(alias, params?, opts?)` | accumulated `rows` + `loadMore` | infinite scroll / "load more" feeds |
+| `usePaginatedQuery(alias, params?, opts?)` | one page of `rows` + `total` | numbered, jumpable pages behind `@lotics/ui` `Pagination` |
+
+One job each — don't overload one. `useQuery` with a big `pageSize` is not pagination; a
+`usePaginatedQuery` whose pages you concatenate yourself is `useInfiniteQuery` done by hand.
+
+## Shared option surface
+
+All three hooks accept these (`BaseQueryOptions`):
+
+| Option | Type | Default | Effect |
+|---|---|---|---|
+| `enabled` | `boolean` | `true` | `false` = no request is sent, `rows` is `[]`, `loading` is `false`. Flip to `true` to fetch. The gate for search-as-you-type and on-demand detail. Note: disabling also **hides** previously loaded rows (the cache entry survives; it re-renders instantly when re-enabled). |
+| `revalidateOnFocus` | `boolean` | `true` | `false` = no auto-refetch on window focus / tab return / network reconnect (`refetch()` still works). Keep the default for dashboards; turn off for transient queries (a search bound to an ephemeral term) where a refocus re-run is wasted work and a visible reload. |
+| `sort` | `QuerySortKey[]` | — | Runtime sort, applied server-side **after** the named query, over its output columns: `[{ field_key, order: "asc" \| "desc" }]`. An empty/omitted array leaves the query's own order intact. Part of the cache key — changing it re-queries. |
+| `filter` | `QueryFilter` | — | Runtime filter, applied server-side after the named query, over its output columns. A single condition or a recursive `{ node_type: "group", logic: "and" \| "or", children }`. Part of the cache key. Build from per-column UI state with `columnFilterToConditions` (`@lotics/ui/column_filter`). |
+
+Per-hook additions:
+
+| Option | Hook | Meaning |
+|---|---|---|
+| `pageSize?: number` | `useQuery` | a **cap** on the one request, not pagination; omit to fetch up to the server row cap |
+| `pageSize: number` | `useInfiniteQuery` | rows per appended page — the options type requires it, though omitting `opts` entirely type-checks and defaults to 30 |
+| `pageSize?: number` | `usePaginatedQuery` | rows per page, default 25 |
+
+Runtime `sort`/`filter` are **server-bounded to the named query's output columns** — a `field_key`
+the query doesn't project is rejected with an error, so a sortable/filterable UI can never widen
+the app's data exposure. The full runtime-refinement contract (which operators are valid per column
+type, record-link membership filtering, and the field-less system conditions — `record_id` works in
+a runtime filter; `locked` / `current_member` are template-only and rejected at the runtime layer)
+lives in [./queries.md](./queries.md).
+
+Refinement order is fixed: the runtime **filter narrows** the named query's result, then **sort
+orders** it, then **limit/offset paginate** it. The template's own filters/sort/limit run first,
+inside the named query.
+
+**Limitation:** the exported `QueryFilterCondition` type declares `field_key` as required, but the
+field-less `record_id` system condition documented in [./queries.md](./queries.md) (the one usable
+in a runtime filter) carries no field. To satisfy the type, include `field_key: ""` on it — the
+server validates system conditions by `type` and never reads `field_key` on them.
+
+## Caching, loading states, and errors
+
+- **Cache identity** is the tuple `(alias, params, pageSize, sort, filter)` (+ the page index for
+  the paged hooks). Object *contents* are hashed, not references — passing a fresh inline
+  `{ status: "open" }` each render is the same key; you never need to memoize params.
+- The cache **survives unmount/remount**: returning to a screen renders the cached rows instantly
+  and revalidates in the background (stale-while-revalidate). Identical concurrent reads dedupe to
+  one request.
+- **`loading`** is `true` only on the *initial* load of a key — a request is in flight and there
+  are no rows yet. It stays `false` during background revalidation of a key that already has rows,
+  so consumers never blank loaded data to a spinner on refetch. A key *change* (new params, sort,
+  filter, or page) is a fresh load: `loading` goes `true` again unless that key is already cached —
+  `usePaginatedQuery` keeps the previous page's rows on screen during it, which is why skeletons
+  gate on `loading && rows.length === 0`, never `loading` alone. **`isValidating`** is `true`
+  whenever any request is in flight — use it for a subtle refresh indicator.
+- **`error`** is a `string | null`. A failed query surfaces immediately — there is **no automatic
+  retry** (no retry loop that masks the error). The last successful rows for the same key stay
+  rendered. The next focus revalidation or an explicit `refetch()` re-runs it.
+- **`refetch()`** re-runs the query. Call it after a known mutation point — a successful
+  `useWorkflow` call — to pull the latest state (see [./mutations.md](./mutations.md)).
+  `usePaginatedQuery.refetch()` refreshes both the page and the count.
+- A design-time fixture registered via `mount(<App />, { fixture })` plus the `?__mock=1` URL flag
+  short-circuits all three hooks (rows come from the fixture, no request, `loading` stays `false`)
+  — see [./runtime.md](./runtime.md).
+
+### Error messages you will actually see
+
+| `error` value | Meaning | What to do |
+|---|---|---|
+| `query timed out after 15s — narrow the filter or simplify the query` | The query hit the per-query statement timeout (15 s). Usually an unindexed predicate scanning a large table — filter *shape* drives latency; see the performance contract in [./queries.md](./queries.md). | Narrow with an indexed filter or `search`, reduce the work per request. |
+| `The app is handling too many requests right now. Please retry in a moment.` | The server's bounded-concurrency gate shed the query under load (a 503). Distinct from a query error — nothing is wrong with the query itself. | Retry (e.g. surface a retry button wired to `refetch()`); the hook does not auto-retry. |
+| `query execution failed` | The query failed at the database. Deliberately generic — database internals are never sent to the client. | The app author diagnoses from the platform's server logs; the app surfaces the message. |
+| A specific validation message | e.g. an un-projected `field_key` in runtime `sort`/`filter`, invalid params, an unknown alias. | Fix the call site — these are contract violations, not transient. |
+
+## Pagination realities (offset-based)
+
+All paging — `useInfiniteQuery` pages, `usePaginatedQuery` pages, and manual `rpc("query", { limit,
+offset })` — is **offset pagination**. There is no cursor API. The consequences are part of the
+contract:
+
+- **Row cap: 10,000.** No single query response returns more than 10,000 rows; a larger `limit`
+  (or an omitted `pageSize` on `useQuery`) is clamped to it. To read a bigger result set, page
+  through it.
+- **Deep pages cost more.** `offset: n` makes the server produce and discard `n` rows before the
+  page — page 200 is materially slower than page 2. Prefer narrowing filters over deep paging.
+- **Pages can shift under concurrent writes.** A row inserted/deleted between two page fetches
+  shifts every later offset — a row can appear on two consecutive pages or fall between them. An
+  infinite list accumulates pages fetched at different times, so treat duplicates as expected:
+  key rows by `__source_record_id` (never by array index) and dedupe if the list must be exact.
+- **Always give a paginated query a deterministic order.** With no `ORDER BY` (neither in the
+  template nor runtime `sort`), row order is unspecified and pages may overlap or skip rows even
+  without concurrent writes. Sort by a stable column (unique where possible).
+- **`count: true` counts the filtered set**, ignoring sort/limit/offset — `usePaginatedQuery`
+  issues it automatically. The count and the page are separate requests, so under concurrent
+  writes `total` can briefly disagree with what paging finds.
+
+### `useQuery`
+
+```tsx
+const { rows, loading, error, refetch } = useQuery("openOrders", { status: "open" });
+```
+
+One fetch. `params` is required when the alias declares params, optional otherwise. Returns
+`{ rows, loading, isValidating, error, refetch }`. `rows` is `Array<Record<string, unknown>>` —
+decode cells with the readers below.
+
+### `useInfiniteQuery`
+
+```tsx
+const { rows, loadMore, hasMore, loadingMore } = useInfiniteQuery("feed", {}, { pageSize: 30 });
+```
+
+The first render loads one page; `loadMore()` appends the next, accumulating into `rows`.
+
+- `hasMore` is `true` when the last page came back **full** — so a total that is an exact multiple
+  of `pageSize` costs one final empty fetch before `hasMore` turns `false`.
+- `loadMore()` is a no-op while `loadingMore` is `true` or when `hasMore` is `false` — safe to wire
+  directly to a scroll sentinel.
+- Changing any part of the result-set identity (`params`, `sort`, `filter`, `pageSize`) starts a
+  fresh accumulation from the first page.
+- `refetch()` revalidates every loaded page. Appending a page does **not** re-fetch earlier pages,
+  so a long-lived list mixes page snapshots taken at different times (see the offset notes above).
+
+### `usePaginatedQuery`
+
+```tsx
+const { rows, total, totalPages, page, setPage, hasMore } =
+  usePaginatedQuery("orders", { q }, { pageSize: 25, sort, filter });
+```
+
+The page-model hook behind a numbered table (pairs with `@lotics/ui` `Pagination`). It owns the
+page cursor and fetches two things: the current page, and a `count` over the filtered set.
+
+- **Result-set identity is `(params, filter)`.** Changing either resets to page 0 and recounts.
+  Changing only `sort` does **neither** — the count is sort-independent and you stay on the same
+  page number of the new order (re-sorting never recounts, and never jumps you back to page 0).
+- The count is keyed on `(alias, params, filter)` — page clicks and re-sorts reuse it.
+- `page` is 0-indexed. `setPage` clamps at 0 but has **no upper clamp** — a page past the end
+  returns empty rows.
+- `total` and `totalPages` are `undefined` until the count resolves — render pagination controls
+  defensively. `totalPages` is `max(1, ceil(total / pageSize))`. Until the count lands, `hasMore`
+  falls back to "the current page came back full".
+- A page change **keeps the previous rows on screen** while the next page loads (built-in
+  `keepPreviousData`) — gate any skeleton on `loading && rows.length === 0`, never on `loading`
+  alone, or every page click collapses the table.
+
+## Decoding query cells
+
+`useQuery` rows are `Record<string, unknown>`. The server serializes each output column by type;
+coerce every cell with a typed reader — never re-implement the serialization contract by hand (it
+rots when the wire format evolves; the readers move with it).
+
+Wire shapes per output column type:
+
+| Column type | Cell value on the wire |
+|---|---|
+| `text` | `string` |
+| `number` | `number` (numeric database strings are normalized server-side; a rare decimal too precise for float64 stays a string — `row.num` parses both) |
+| `boolean` | `boolean` |
+| `date` | `"YYYY-MM-DD"` — a calendar day, no time component |
+| `datetime` | `"YYYY-MM-DDTHH:mm"` — workspace wall-clock, minute precision |
+| `select` | `Array<{ key, label }>` — one entry per selected option |
+| `select_member` | `Array<{ id, name, email? }>` — `email` only for authenticated viewers of the app's own org |
+| `select_record_link` | `Array<{ id, display }>` — target record id + its display text |
+| `files` | `Array<{ id, filename, mime_type, url, thumbnail_url?, size?, created_at? }>` — presigned |
+
+Row-level (non-grouped) queries additionally carry system columns: `__source_record_id` /
+`__source_table_id` / `__source_locked` (source addressing — pass `__source_record_id` to
+workflows), `__created_at` / `__updated_at` (record timestamps), and per-projection `__src_field_*`
+metadata. A grouped query collapses rows and emits none of these. Details:
+[./queries.md](./queries.md).
+
+### The readers
+
+| Reader | In → out | Semantics |
+|---|---|---|
+| `row.opt(cell)` | select cell → `string \| null` | first option **key** (accepts the legacy bare-string / `{ id }` shapes); `null` when empty |
+| `row.text(cell)` | any → `string` | strings pass through, finite numbers stringify, everything else → `""` |
+| `row.num(cell)` | any → `number` | numbers pass (NaN/Infinity → 0), parseable strings parse, everything else → `0` |
+| `row.bool(cell)` | any → `boolean` | `true` or the string `"true"`; everything else `false` |
+| `row.date(cell)` | date/datetime cell → `Date \| null` | the stored **calendar day** at LOCAL midnight — time stripped |
+| `row.datetime(cell)` | date/datetime cell → `Date \| null` | local `Date` **keeping the stored wall-clock** (minute precision; seconds are dropped); missing time = midnight |
+| `row.link(cell)` | link cell → `{ id, display } \| null` | the FIRST linked record |
+| `readLinks(cell)` | link cell → `{ id, display }[]` | ALL linked records (`[]` when empty) |
+| `readSelect(cell)` | select cell → `ResolvedOption[]` | all selected options as `{ key, label }` (`[]` when empty) |
+| `readMembers(cell)` | member cell → `ResolvedMember[]` | `{ id, name, email? }[]` (`[]` when empty) |
+| `readFiles(cell)` | files cell → `AppFile[]` | attached files with presigned URLs (`[]` when empty) |
+| `readLocked(rowObj)` | the whole **row** → `boolean` | the record's lock state from `__source_locked` |
+
+All readers are pure (`unknown` in, value out), never throw, and return their empty value
+(`null` / `""` / `0` / `false` / `[]`) for absent or malformed input — so callers iterate and
+render without null-check pyramids.
+
+**`row.date` vs `row.datetime`.** `row.date` parses only the leading `YYYY-MM-DD` and builds a
+LOCAL-midnight `Date` — calendar/gantt placement never shifts across viewer timezones. `row.datetime`
+keeps the stored wall-clock verbatim (no UTC conversion — the stored value is a timezone-less
+workspace wall-clock), so `getHours()` / `toLocaleTimeString()` render the time as written. A
+**`date`-typed output column carries no time on the wire** — `row.datetime` on it returns midnight
+and the UI prints `00:00`. When you need the time, the query must output the column as `datetime`
+(the type-override rules are in [./queries.md](./queries.md)).
+
+**`readSelect`.** A query **cell** carries `key` + `label` only — `color` comes from
+`useFieldOptions`, not the cell. An option deleted after the cell was written surfaces as
+`label === key` (the stale state is explicit, never hidden). Render with `@lotics/ui` `OptionBadge`
+— see [./members_and_options.md](./members_and_options.md).
+
+**`readMembers`.** `name` is `null` when the id doesn't resolve in the app's org (e.g. a removed
+member) — fall back explicitly. `email` is present only on authenticated responses from the app's
+own org; anonymous public visitors and cross-org viewers get name only (no PII exposure). Cells
+never carry avatar images — the avatar lives on the `useMembers` roster
+([./members_and_options.md](./members_and_options.md)).
+
+**`readLinks` / `row.link`.** `display` is the linked record's primary-field text — render it;
+use `id` to correlate, filter (link `has_any_of`), or fetch detail. `row.link` reads the first
+entry only — on a multi-link field use `readLinks`.
+
+**`readFiles`.** Each entry's `url` (and `thumbnail_url` for images) is **presigned with a 24-hour
+TTL** — it renders directly in an `<Image>`/preview and works from the sandboxed iframe and for
+anonymous public-app visitors; re-querying refreshes the TTL naturally. Entries the server didn't
+presign (no `url`) are skipped, so you never render an unservable file. `size` (bytes) and
+`created_at` (ISO upload timestamp) are resolved at serving time; `size` is absent for older files
+not yet backfilled — render it only when present, and surface both as dedicated sortable columns
+over the raw values (a formatted "8.4 MB" string sorts wrong). Previewing and uploading files:
+[./files.md](./files.md).
+
+**Warning — the presign ceiling:** signing file URLs is per-entry server work, so a response is
+capped at **2,000 file entries** (server default). A query over the cap **fails** with an error
+naming the count and the remedies — it never silently returns unsigned cells. Project `files`
+columns **only in the query that renders them**, narrow with a filter, or paginate. A bare
+`from_table` with no projection ships every column — including `files` — and is how you hit this.
+
+**`readLocked`.** Takes the whole row object, not a cell. A locked record rejects direct writes —
+show the locked state and route edits through the locked-change request flow
+([./mutations.md](./mutations.md)).
+
+## Complete select option sets
+
+A query cell carries only the options a record actually holds (key + label, no color). For the
+**complete** option list of a select column — every option including those in no current row, with
+colors — use **`useFieldOptions`**, and prefer it over deriving options from loaded rows
+(row-derived sets are incomplete until every page loads and carry no colors). Its full contract
+(return shape, `byKey`, `opts.enabled`, freshness), rendering the values (`OptionBadge`,
+`MemberChip`, `MemberSelect`), and the member roster (`useMembers`) live in
+[./members_and_options.md](./members_and_options.md).
+
+## Data discipline
+
+These rules prevent whole bug classes; every app follows them.
+
+- **Server data is never copied into `useState`.** `useQuery` / `useWorkflow` results are the
+  source of truth — derive everything else with `useMemo`. A second copy drifts and serves stale
+  values.
+- **Prefer derivation + callbacks over `useEffect`.** A derived value is `useMemo`; "state A
+  changed → set state B" is both set in the one triggering callback. `useEffect` is for genuine
+  external subscriptions (timers, DOM listeners, storage) — fetching is `useQuery`, not an effect.
+- **No layout shift on load or paging — the UX bar, not a nicety.** (1) First load renders
+  `Skeleton` placeholders that mirror the final layout, not a bare spinner; (2) a page change keeps
+  the previous rows (`usePaginatedQuery` does this for you) — gate the skeleton on
+  `loading && rows.length === 0`, never `loading` alone; (3) a view↔edit toggle reserves the
+  input's height so pressing Edit never reflows.
+- **Diff before update.** An edit form snapshots the record at load and sends only the CHANGED
+  fields to its update workflow. The full rule and the locked-record path:
+  [./mutations.md](./mutations.md).
+- **Reuse the kit's utilities.** `@lotics/ui` ships the formatters (`formatMoney`, `formatDate` /
+  `parseDate` / `toISODate`) — never hand-roll `dd/MM` or currency strings. Grep `@lotics/ui`
+  exports before writing one.
+
+## Search-as-you-type
+
+A search-first picker (type → ranked results → pick) is one `@lotics/ui` component plus three SDK
+pieces. Compose these — don't hand-roll search:
+
+- **`Combobox`** (`@lotics/ui/combobox`) owns the interaction — debounced `onSearchChange`, a
+  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
+  [./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.**
+- **`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
+  wasted work.
+- **`useRecents(key, { max })`** — persist the picked option locally; pass its list as
+  `recentOptions` ([./navigation_and_state.md](./navigation_and_state.md)).
+
+```tsx
+const [term, setTerm] = useState("");            // live input stays local
+const { rows, loading } = useQuery(
+  "searchCustomers",
+  { q: term },
+  { enabled: term.trim().length > 0, revalidateOnFocus: false },
+);
+```
+
+Fetch detail on select with a **second** parameterized query — a unique-code `equals`, or a link
+`has_any_of [record_id]` — never a bare full-table load. To fetch a record by its **own id** (your
+starting point is a bare id, e.g. a drill row), use the field-less `record_id` system condition —
+contract and example in [./queries.md](./queries.md); prefer a link/join whenever an actual
+relationship exists.
+
+## Browse + sort + filter (the record picker)
+
+When the user doesn't know the term — "show me everything, let me narrow it" — build a modal table
+they can browse (numbered pages), search, sort, and filter:
+
+- **The screen is app-owned**, composed from `@lotics/ui`: a `Dialog` over `SearchInput` + filter
+  pills (`ColumnFilter`) + `Table` + `Pagination`. It needs both `@lotics/ui` and the SDK (which is
+  UI-free), so it lives in the app (e.g. a `record_picker.tsx`) — reuse it for any table by passing
+  a different `alias` + column config.
+- **`usePaginatedQuery`** drives it: the page of rows, the `total` for "Page 1 of N" (the built-in
+  `count` request), and the page cursor.
+- **Filter pills → runtime `filter`** via `columnFilterToConditions` (`@lotics/ui/column_filter`);
+  **column-header sort → runtime `sort`** by mapping the table's `{ key, order }` to
+  `[{ field_key: key, order }]`. Both are server-bounded to the query's output columns — the picker
+  can't widen exposure ([./queries.md](./queries.md)).
+- **Browse needs an unbounded query.** A `limit` baked into the query template caps the *total*
+  browsable set — paging then pages within that cap. Drop the template limit and let `pageSize`
+  drive (the server row cap still bounds any single page).
+- **Select filter options come from `useFieldOptions`** — the complete set, not options derived
+  from loaded rows.