@lotics/app-sdk 0.79.1 → 0.80.0

package/AGENTS.md

@@ -16,13 +16,13 @@ signature; open the file.**
 |---|---|
 | [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/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) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only), 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). |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + link descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [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 — 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/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; a chat mutation refetches your queries through the realtime channel, not a separate poke). **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/dist/src/hooks.js

@@ -19,7 +19,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { DEFAULT_IMAGE_FIDELITY } from "./upload/optimize.js";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
-import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeHostRefetch, } from "./rpc.js";
+import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeQueriesChanged, } from "./rpc.js";
 import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, pendingInteractiveCall, buildChoiceOutput, applyInteractiveAnswer, landingOf, proseOf, ABORTED, } from "./agent_stream.js";
 import { getMockRows, hasMockFlag } from "./mock.js";
 export { buildChoiceOutput } from "./agent_stream.js";
@@ -52,17 +52,27 @@ function swrConfig(revalidateOnFocus) {
     };
 }
 /**
- * Re-run `refetch` when the host pushes `refetchQueries` — after an ambient
- * app-chat agent turn mutated records, every mounted query hook refreshes the
- * data it rendered. Inert in mock mode (no host, no listener) and for a mocked
- * alias (its rows come from the fixture). Shared by all three query hooks.
+ * Refetch this query when the host reports that ITS tables changed — whoever
+ * wrote them: another member, a workflow, the chat agent, or an external agent
+ * over the CLI or MCP.
+ *
+ * The host names the affected aliases rather than telling every hook to
+ * re-read: an app's queries usually span several tables, and a blanket refetch
+ * would re-run expensive aggregates on a change to a table they never touch.
+ *
+ * Inert in mock mode (no host, no listener), for a mocked alias (its rows come
+ * from the fixture), and for a standalone/public app (no host to push).
+ * Shared by all three query hooks.
  */
-function useHostRefetch(refetch, mockRows) {
+function useHostRefetch(alias, refetch, mockRows) {
     useEffect(() => {
         if (hasMockFlag() || mockRows)
             return;
-        return subscribeHostRefetch(refetch);
-    }, [refetch, mockRows]);
+        return subscribeQueriesChanged((aliases) => {
+            if (aliases.includes(alias))
+                refetch();
+        });
+    }, [alias, refetch, mockRows]);
 }
 export function useQuery(alias, params, opts) {
     const pageSize = opts?.pageSize;
@@ -88,7 +98,7 @@ export function useQuery(alias, params, opts) {
     const refetch = useCallback(() => {
         void swr.mutate();
     }, [swr]);
-    useHostRefetch(refetch, mockRows);
+    useHostRefetch(alias, refetch, mockRows);
     return {
         rows: mockRows ?? swr.data?.rows ?? [],
         loading: mockRows ? false : swr.isLoading,
@@ -182,7 +192,7 @@ export function useInfiniteQuery(alias, params, opts) {
     const refetch = useCallback(() => {
         void swr.mutate();
     }, [swr]);
-    useHostRefetch(refetch, mockRows);
+    useHostRefetch(alias, refetch, mockRows);
     const loadMore = useCallback(() => {
         if (!hasMore || loadingMore)
             return;
@@ -251,7 +261,7 @@ export function usePaginatedQuery(alias, params, opts) {
         void rowsSwr.mutate();
         void countSwr.mutate();
     }, [rowsSwr, countSwr]);
-    useHostRefetch(refetch, mockRows);
+    useHostRefetch(alias, refetch, mockRows);
     return {
         rows,
         total,

package/dist/src/rpc.d.ts

@@ -135,12 +135,20 @@ export declare function subscribeUrlParams(cb: (params: UrlParams) => void): ()
  */
 export declare function postHostNotification(message: HostNotification): void;
 /**
- * Subscribe to the host's `refetchQueries` push. Returns an unsubscribe fn.
- * Wired by every mounted query hook so an ambient-chat record mutation refreshes
- * exactly the data currently on screen. No host ever posts it standalone, so the
- * subscription is inert there.
+ * Subscribe to the host's `queriesChanged` push, which names the aliases whose
+ * underlying tables moved. Returns an unsubscribe fn.
+ *
+ * The host owns the realtime connection — one per tab, shared by every surface
+ * in it — because the app frame deliberately holds no platform credentials, and
+ * a second socket per app would only duplicate a subscription the host already
+ * has. The host resolves changed tables to aliases (it holds the query ASTs)
+ * and names them here, so a mounted hook refetches only when ITS query is
+ * affected rather than on every change anywhere in the workspace.
+ *
+ * A standalone (public) app has no host, so this is inert there — those apps
+ * stay on pull-based freshness.
  */
-export declare function subscribeHostRefetch(cb: () => void): () => void;
+export declare function subscribeQueriesChanged(cb: (aliases: string[]) => void): () => void;
 /**
  * Start a streaming agent run. Each raw SSE text chunk is handed to `onText`
  * (the caller parses it via `agent_stream`); `done` settles when the stream

package/dist/src/rpc.js

@@ -91,12 +91,20 @@ export function postHostNotification(message) {
     window.parent.postMessage(message, hostOrigin);
 }
 /**
- * Subscribe to the host's `refetchQueries` push. Returns an unsubscribe fn.
- * Wired by every mounted query hook so an ambient-chat record mutation refreshes
- * exactly the data currently on screen. No host ever posts it standalone, so the
- * subscription is inert there.
+ * Subscribe to the host's `queriesChanged` push, which names the aliases whose
+ * underlying tables moved. Returns an unsubscribe fn.
+ *
+ * The host owns the realtime connection — one per tab, shared by every surface
+ * in it — because the app frame deliberately holds no platform credentials, and
+ * a second socket per app would only duplicate a subscription the host already
+ * has. The host resolves changed tables to aliases (it holds the query ASTs)
+ * and names them here, so a mounted hook refetches only when ITS query is
+ * affected rather than on every change anywhere in the workspace.
+ *
+ * A standalone (public) app has no host, so this is inert there — those apps
+ * stay on pull-based freshness.
  */
-export function subscribeHostRefetch(cb) {
+export function subscribeQueriesChanged(cb) {
     ensureListener();
     refetchSubscribers.add(cb);
     return () => {
@@ -108,7 +116,7 @@ const streaming = new Map();
 /** `useUrlState` subscribers — notified when the host broadcasts new params
  *  after browser back/forward. */
 const urlStateSubscribers = new Set();
-/** Query hooks subscribed to the host's `refetchQueries` push — the host sends
+/** Query hooks subscribed to the host's `queriesChanged` push — the host sends
  *  it after an ambient app-chat agent turn mutated records. */
 const refetchSubscribers = new Set();
 let nextRpcId = 0;
@@ -131,13 +139,13 @@ function ensureListener() {
                 cb(msg.params);
             return;
         }
-        // Broadcast (no id): the host tells the app its rendered data may be stale
-        // after an ambient app-chat agent turn mutated records — every mounted query
-        // hook re-reads through its own declared queries. Push-only freshness; the
+        // Broadcast (no id): the host names the aliases whose tables changed, from
+        // the realtime channel it holds for the whole tab. Push-only freshness; the
         // host never reads app data through this path.
-        if (msg.type === "refetchQueries") {
+        if (msg.type === "queriesChanged" && Array.isArray(msg.aliases)) {
+            const aliases = msg.aliases.filter((a) => typeof a === "string");
             for (const cb of refetchSubscribers)
-                cb();
+                cb(aliases);
             return;
         }
         if (typeof msg.id !== "number")

package/docs/data_fetching.md

@@ -71,11 +71,19 @@ server validates system conditions by `type` and never reads `field_key` on them
   renders the cached rows instantly *and* revalidates them in the background, so a list reflects what
   another screen changed while you were away. Identical concurrent reads dedupe to one request.
   Freshness comes from four places — arrival, window focus / tab return / network reconnect
-  (`revalidateOnFocus`, default on), the host's post-chat-turn poke, and explicit `refetch()`.
+  (`revalidateOnFocus`, default on), a **realtime push**, and explicit `refetch()`.
   **Still call `refetch()` after a write the user is watching for**: arrival covers navigation, not a
   mutation made on the screen you are already standing on.
+- **Realtime push keeps an already-open screen current.** When a table one of your queries reads
+  changes — another member, a workflow, the chat agent, or an external agent writing over the CLI or
+  MCP — that query refetches within about a second. Nothing to wire: it follows from the query's own
+  declaration. It refetches only the aliases whose tables actually moved, so an expensive aggregate
+  is not re-run by a change to a table it never reads. Two limits worth knowing: it carries RECORD
+  changes only (a schema edit does not push), and a **standalone/public app has no host**, so those
+  apps keep focus/reconnect freshness alone. Treat push as an improvement on pull, never a
+  replacement — it is absent whenever the channel cannot connect.
 - **`useInfiniteQuery` does not arrival-revalidate** — the one exception. A warm feed re-mounted
-  refetches nothing; a cold key still fetches, and focus / reconnect / the chat poke still refresh.
+  refetches nothing; a cold key still fetches, and focus / reconnect / a realtime push still refresh.
   Re-fetching page 1 on arrival would cost a request on every `loadMore()` and reshuffle the top of
   the feed under a reader scrolling further down it, and re-fetching every loaded page grows without
   bound. **A feed that must be fresh on arrival calls `refetch()`.**
@@ -89,6 +97,17 @@ server validates system conditions by `type` and never reads `field_key` on them
 - **`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.
+- **Never derive a FIGURE from `rows` without gating on `error`.** On a failure `rows` is `[]`,
+  and `[]` is indistinguishable from a genuinely empty result — so `rows.reduce(…)` returns `0`,
+  `rows.length` returns `0`, and a screen states a confident number that no query answered. This
+  is the one place the empty-vs-broken distinction is load-bearing: a list that renders nothing
+  looks obviously wrong, whereas a total that reads `0` looks *fine*. It cost a sales register
+  nine days of showing every rep `0 ₫` of commission, because one query's runtime filter named a
+  column it did not project and nothing read `error`. A count, a sum, a "N of M", a progress
+  meter, a badge — anything a reader would act on — renders a dash and the failure, never a
+  number, while `error !== null`. Note a key CHANGE resets this: a new `params`/`filter`/`sort`
+  is a fresh key with no prior rows, so the "last successful rows stay rendered" behaviour above
+  does not save you.
 - **`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 the page, and the count when the hook owns it
@@ -110,7 +129,7 @@ server validates system conditions by `type` and never reads `field_key` on them
 | `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. |
+| A specific validation message | e.g. an un-projected `field_key` in runtime `sort`/`filter`, invalid params, an unknown alias. An unknown column names every column the query DOES project, so the valid set is in the message. | Fix the call site — these are contract violations, not transient. |
 
 ## Pagination — two models
 

package/docs/queries.md

@@ -116,6 +116,14 @@ source_table_id?, source_field_key? }` per column. Rows are plain objects keyed
 column name; decode cells with the SDK readers (`row.*`, `readSelect`, `readMembers`,
 `readLinks`, `readFiles` — see [data_fetching.md](./data_fetching.md)).
 
+**`source_fields_by_table_id` is always `{}`** — the key is part of the shape, the map is not
+filled. The server reads the source tables' field definitions to resolve option and member
+cells and then keeps them: sending them beside every page was 94% of a real register
+response's compressed bytes, for a map no reader wanted there. **The complete option sets —
+every option including those no loaded row holds, with colors — are `useFieldOptions`**
+(`/field-options`, which derives them from the same definitions); a cell's own `{ key, label }`
+comes down on the cell. See [members_and_options.md](./members_and_options.md).
+
 Delivery-layer enrichment (applied to the response, per request):
 
 - **`files` cells** — each entry gains a presigned `url` + `thumbnail_url` (24 h TTL) and

package/package.json

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