@lotics/app-sdk 0.66.1 → 0.68.0

package/AGENTS.md

@@ -15,7 +15,7 @@ signature; open the file.**
 | Doc | Read it for |
 |---|---|
 | [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`, data discipline, 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) — data discipline, 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. |

package/dist/src/hooks.js

@@ -31,19 +31,24 @@ export function useWorkflow(alias) {
 // rows (no retry loop that masks the error), and honor the focus/reconnect
 // opt-out.
 //
-// `revalidateIfStale: false` — SWR defaults this to `true`, and its initial
-// -revalidation decision is `isUndefined(data) || revalidateIfStale`, so every
-// re-mount of a screen that already had rows re-queried the backend. An app
-// that navigates between screens (or re-opens a drawer) paid a full query set
-// each time for data it was already showing. A cold mount still fetches
-// (`isUndefined(data)` short-circuits), focus/reconnect still refresh, and the
-// host's `refetchQueries` poke still forces a refresh after a chat turn mutates
-// records — so freshness keeps every path it had except "re-mounted".
+// `revalidateIfStale` is LEFT AT SWR's DEFAULT (`true`): re-mounting a screen
+// renders its cached rows AND re-reads them. Pinning it `false` saved a re-query
+// per navigation and cost every screen a hand-rolled arrival refetch — where
+// forgetting is SILENT (no error, no empty state, just last visit's data until a
+// hard reload), which is not a mistake an author gets told about once and learns.
+//
+// The default costs one BACKGROUND request per re-mount of a warm key and
+// nothing visible: SWR's `isLoading` is true only on an initial load with no
+// cached data, so nothing blanks to a skeleton, and `dedupingInterval` collapses
+// a burst of navigation into one fetch.
+//
+// `useAppContext` (viewer.ts) still pins it off — the app's identity is read
+// once at boot and cannot change under the reader. `useInfiniteQuery` is the
+// one hook this does not reach; see its own note.
 function swrConfig(revalidateOnFocus) {
     return {
         revalidateOnFocus,
         revalidateOnReconnect: revalidateOnFocus,
-        revalidateIfStale: false,
         shouldRetryOnError: false,
     };
 }
@@ -152,7 +157,20 @@ export function useInfiniteQuery(alias, params, opts) {
             sort,
             filter,
         });
-    }, { revalidateFirstPage: false, ...swrConfig(revalidateOnFocus) });
+    }, 
+    // `revalidateFirstPage: false` — `loadMore()` fetches the next page and only
+    // that page. SWR's default re-fetches page 1 on every load-more, costing a
+    // request per scroll and reshuffling the top of the feed under a reader
+    // looking further down it (pinned by the keyset test).
+    //
+    // THE COST, stated because it is otherwise invisible: this hook does not
+    // arrival-revalidate the way the other two do. SWRInfinite decides per page
+    // and never consults `revalidateIfStale`, and neither lever that would change
+    // that is cheap — `revalidateFirstPage` pays per load-more, `revalidateOnMount`
+    // refetches EVERY loaded page. A cold key still fetches, focus/reconnect and
+    // `refetch()` still refresh; a feed that must be fresh on arrival calls
+    // `refetch()`.
+    { revalidateFirstPage: false, ...swrConfig(revalidateOnFocus) });
     // SWRInfinite leaves an in-flight page slot `undefined` until it resolves —
     // operate on resolved pages only so a page being appended never crashes the
     // flatten or skews the counts.

package/docs/ai.md

@@ -24,8 +24,8 @@ A declaration carries:
 | `knowledge_doc_ids` | The knowledge docs the agent may read, and the whole set it can reach — a doc absent from this list is unreadable even if the agent names its id. Declare `grep_knowledge` / `read_knowledge` in `tool_names` to read them. There is no size limit and nothing is inlined, so a multi-megabyte reference corpus (a full tariff, a regulation set) is a normal declaration. Reach for `code_exec` only to COMPUTE across the corpus — counting, cross-referencing — never merely to read it |
 | `query_aliases` | The app's own named queries the agent may run via `run_app_query` — its **entire read surface** over records. You list them; there is no "all of them" shorthand, and adding a query to the app never widens an existing agent. Omitted means the agent reads nothing |
 | `workflow_aliases` | The app's own workflows the agent may invoke via `run_app_workflow` — its **entire write surface** |
-| `model_id` | Optional chat model pin. Omit (preferred) to follow the platform default chat model, resolved at run time — the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
-| `effort_level` | Optional reasoning depth for adaptive-thinking models. Requires an explicit `model_id` pin — effort is tuned per model |
+| `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 |
 | `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) |
 

package/docs/data_fetching.md

@@ -67,14 +67,18 @@ server validates system conditions by `type` and never reads `field_key` on them
 - **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 **sends no request**. Identical concurrent reads dedupe to one request.
-- **A re-mount is not a refresh event.** Freshness comes from window focus / tab return / network
-  reconnect (`revalidateOnFocus`, default on), the host's post-chat-turn refetch poke, and explicit
-  `refetch()`. Re-mounting a screen you already loaded is none of those, so it re-uses the cache.
-  A **cold** key (never loaded, or a new `(alias, params, pageSize, sort, filter)` tuple) always
-  fetches — this only affects keys that already hold rows.
-  After a write the user is watching for, call `refetch()`; never rely on navigation to refresh.
+- The cache **survives unmount/remount**, and **arrival is a refresh event**: returning to a screen
+  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()`.
+  **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.
+- **`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.
+  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()`.**
 - **`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,

package/docs/members_and_options.md

@@ -89,10 +89,10 @@ name**, not the field key. Each `FieldOptions`:
 
 ### Caching & freshness
 
-Field config is slow-changing, so the hook fetches once per alias and does **not** revalidate on
-window focus or reconnect. The option set is resolved live from field config at fetch time — an
-option added, renamed, or recolored in the table flows through on the next fetch (a remount, a full
-reload, or an explicit `refetch()`), with no app redeploy. `opts.enabled` defers the fetch (e.g.
+Field config is slow-changing, so the hook does **not** revalidate on window focus or reconnect — it
+re-reads on arrival (a remount) like the query hooks, and on an explicit `refetch()`. The option set
+is resolved live from field config at fetch time, so an option added, renamed, or recolored in the
+table flows through on the next fetch, with no app redeploy. `opts.enabled` defers the fetch (e.g.
 until an edit drawer opens). State: `{ fields, loading, isValidating, error, refetch }`.
 
 ### Coloring a stored value (the `byKey` idiom)

package/docs/queries.md

@@ -780,6 +780,19 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
 - **`count: true`** — returns `{ total }` only: a single-row COUNT over the *filtered* set,
   ignoring sort/limit/offset. Drives "Page 1 of N".
 
+**A terminal aggregate cannot be refined — plan the total accordingly.** Because refinement wraps
+*around* the template over its **output** columns, a query that has already collapsed (a `group`
+with an empty `by` and a `sum`, say) has no source column left for the filter to name, so a facet
+the list narrows by 400s against the total beside it. `window` is not a way out either: the frame
+aggregate is computed before the refinement wraps, so the number describes the unfiltered set.
+Both alternatives are worse than they look — baking the facet into the aggregate stops it being a
+runtime facet (a filter TREE is not a scalar param), and leaving the total unfiltered puts a count
+that follows the facet next to a sum that does not. **Project the summed column plus the columns
+the facet can name, fetch under the same runtime `filter`, and total in the browser** — correct and
+facet-aware, but it ships every matching row, so it holds only where the scope is already small
+(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

package/package.json

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