@lotics/app-sdk 0.51.2 → 0.51.3

package/docs/ai.md

@@ -121,7 +121,7 @@ Both settle the in-flight `run()` promise cleanly with `undefined` — a stop is
 
 ### 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.
+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 — so a run that settles within that 11-minute poll window survives a flaky connection. A run still going when the poll deadline passes (the hard cap is 20 min) is **not** recovered on the client: the poll gives up and the drop surfaces as an error, though the result is still persisted server-side. Only when no run id was ever received (the run never started) does the failure reject before any polling.
 
 **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.
 

package/docs/data_fetching.md

@@ -96,24 +96,39 @@ server validates system conditions by `type` and never reads `field_key` on them
 | `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)
+## Pagination — two models
 
-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:
+Reads paginate two different ways, and the difference is load-bearing:
+
+- **`useInfiniteQuery` uses keyset (seek) pagination.** Each page seeks past the previous page's
+  opaque cursor instead of counting an offset, so a deep scroll stays O(page) and — the reason it
+  matters — **never skips or duplicates a row as the set shifts** under concurrent inserts/deletes.
+  The cursor is internal: the hook sends it and reads the next one back; you never see it. The
+  server keysets a single sortable key (the runtime `sort`, or the record-id default) and falls
+  back to offset transparently for a multi-key sort it can't seek. So an infinite feed needs **no
+  dedupe** — key rows by `__source_record_id` for stable React keys, not to guard against repeats.
+- **`useQuery`, `usePaginatedQuery`, and manual `rpc("query", { limit, offset })` use offset
+  pagination** — count `offset` rows, skip them, return the next page. Two consequences a keyset
+  scroll doesn't have: deep pages cost more, and pages shift under concurrent writes.
+
+Shared by both:
 
 - **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.
+- **Always give a paginated query a deterministic order.** With no `ORDER BY` (neither in the
+  template nor runtime `sort`), row order is unspecified — offset pages may overlap or skip rows
+  even without concurrent writes, and keyset falls back to the record-id order. Sort by a stable
+  column (unique where possible).
+
+Offset-only (the `usePaginatedQuery` numbered pages and the `useQuery` / manual `rpc` cap paths):
+
 - **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).
+  shifts every later offset — a row can appear on two consecutive pages or fall between them. If
+  you concatenate offset pages yourself, key rows by `__source_record_id` (never by array index)
+  and dedupe if the list must be exact.
 - **`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.
@@ -134,16 +149,22 @@ decode cells with the readers below.
 const { rows, loadMore, hasMore, loadingMore } = useInfiniteQuery("feed", {}, { pageSize: 30 });
 ```
 
-The first render loads one page; `loadMore()` appends the next, accumulating into `rows`.
+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).
 
-- `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`.
+- `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
+  `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).
+  so a long-lived list still mixes page snapshots taken at different times (an edit between two
+  page loads shows old and new side by side) — but keyset guarantees no row is skipped or repeated.
+- **Standalone (public) apps:** `loadMore()` can't advance past page one — the cursor is dropped in
+  transit (see [Standalone transport](#standalone-public-transport)).
 
 ### `usePaginatedQuery`
 
@@ -168,6 +189,26 @@ page cursor and fetches two things: the current page, and a `count` over the fil
   `keepPreviousData`) — gate any skeleton on `loading && rows.length === 0`, never on `loading`
   alone, or every page click collapses the table.
 
+## Standalone (public) transport
+
+An app served standalone at `<slug>.lotics.app` (a public share with no Lotics host — see
+[runtime](./runtime.md)) reaches the query endpoint through a thinner transport that forwards only
+`alias`, `params`, `limit`, and `offset`. It **silently drops** `sort`, `filter`, `count`, and the
+keyset `cursor`. Design a public app around this:
+
+- **Runtime `sort` / `filter` are ignored** — every hook's `opts.sort` / `opts.filter` is dropped,
+  so a standalone app can't order or narrow a query at the call site. Bake ordering and scoping
+  into the query **template** (or drive them through declared `params`), not the refinement options.
+- **`usePaginatedQuery.total` stays `undefined`** — the `count` request never resolves, so
+  `totalPages` never lands and `hasMore` falls back to "the current page came back full". A
+  numbered "Page 1 of N" control has no N; render it defensively, or prefer `useInfiniteQuery`.
+- **`useInfiniteQuery.loadMore()` never advances past the first page** — with the cursor dropped,
+  no `next_cursor` comes back, so `hasMore` is `false` after page one. For a standalone browse,
+  size the template `limit` (or a `params`-driven page) to return the whole set in one fetch.
+
+The embedded product host and the `lotics app dev` forwarder pass all of these through — this
+caveat is standalone-only.
+
 ## Decoding query cells
 
 `useQuery` rows are `Record<string, unknown>`. The server serializes each output column by type;

package/docs/queries.md

@@ -708,17 +708,24 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
   it. Record-link membership (`has_any_of` by id) **works** here; so does `is_current_member`
   on a member column. Traversals / `locked` / `current_member` do not — bake those into the
   template.
-- **`sort`** — `[{ field_key, order, blank_position? }]` over output columns.
-- **`limit` / `offset`** — offset pagination. `limit` is clamped to the 10,000-row cap (§10).
+- **`sort`** — `[{ field_key, order }]` over output columns — the typed `QuerySortKey` the hooks
+  accept. The wire sort node also honors `blank_position?: "top" | "bottom"` (blanks default to
+  bottom), but that field is **not** on the typed hook option; reach it only through a raw
+  `rpc("query", { sort })` call.
+- **`limit` / `offset` / keyset `cursor`** — pagination. `useQuery` / `usePaginatedQuery` page by
+  `offset` (`limit` clamped to the 10,000-row cap, §10); `useInfiniteQuery` opts into **keyset
+  (seek)** by sending `keyset: true` + the prior page's `cursor`, and the server returns the next
+  `next_cursor` (null on the last page). Seek stays O(page) and never skips/duplicates a row as the
+  set shifts, falling back to offset for a multi-key sort it can't seek.
 - **`count: true`** — returns `{ total }` only: a single-row COUNT over the *filtered* set,
   ignoring sort/limit/offset. Drives "Page 1 of N".
 
 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 `offset = page × pageSize`; `usePaginatedQuery` owns the page
-cursor and issues the page query plus 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.
+`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.
 
 Build `filter` from UI column-filters with `columnFilterToConditions` (`@lotics/ui`); prefer
 `useFieldOptions` for a select filter's option set.
@@ -730,11 +737,12 @@ silently ignored there and `count` never resolves (`usePaginatedQuery.total` sta
 `undefined`). A standalone app must bake ordering/scoping into the template (or params) rather
 than rely on runtime refinement.
 
-**Pagination semantics:** offset-only — 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).
-There is no cursor/keyset pagination. Keep paginated browses filtered and sorted by a stable
-key, and don't build UX that walks thousands of pages.
+**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.
 
 ---
 
@@ -924,8 +932,9 @@ Consolidated from the sections above — these describe present engine behavior:
 - **No `first_value`/`last_value`/`nth_value` navigation** — the `functions` set is `row_number`,
   `rank`, `dense_rank`, `percent_rank`, `cume_dist`, `ntile`, `lag`, `lead` (§8). Frame aggregates
   remain the 10-item OVER-legal subset.
-- **Offset-only pagination.** Deep pages cost the full skipped prefix; pages can shift under
-  concurrent writes (§9).
+- **`useQuery` / numbered pagination is offset.** Deep pages cost the full skipped prefix and can
+  shift under concurrent writes; `useInfiniteQuery` uses keyset (seek), which stays O(page) and
+  never skips or duplicates rows (§9).
 - **No collation control.** Text ORDER BY uses the database default collation —
   locale-specific alphabetical order (e.g. accented-letter ordering) is not configurable.
 - **Select / member / link columns sort by raw JSON** in queries — not by configured option

package/docs/runtime.md

@@ -169,12 +169,16 @@ surfaces:
 | `query`, `field_options`, `workflow`, `members`, `context`, `binding`, `upload`, `urlState.get/set`, `openExternal` | yes | yes | yes |
 | `comments.*` | yes | yes | rejects — `"Comments are available only in embedded apps — a signed-in member is required."` |
 | `agentRun` (streaming, internal to `useAgentRun`) | yes | yes | yes |
-| `agentRuns`, `agentRun.get`, `agentRun.cancel` | yes | **no** — the dev forwarder doesn't implement them (`"Unknown RPC op: …"`) | yes |
+| `agentRun.get`, `agentRun.cancel` | yes | **no** — the dev forwarder doesn't implement them (`"Unknown RPC op: …"`) | yes |
+| `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:** in the dev loop, run *history* and server-side *cancel* for
-agent runs error (the local abort of a live stream still works); verify those
-paths on a deployed app. The standalone `query` transport forwards only
+**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
+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
 `alias`/`params`/`limit`/`offset` — runtime `sort`/`filter`/`count` refinement
 is embedded-only (see [data fetching](./data_fetching.md)).
 

package/package.json

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