@lotics/app-sdk 0.66.0 → 0.67.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/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

@@ -440,8 +440,8 @@ derived surfaces share one implementation.
 | select_record_link | `select_record_link` | membership by linked-record **id**: `has_any_of`, `has_none_of`, `has_all_of`; text over the cached **display**: `contains`, `not_contains`, `starts_with`, `ends_with`; `is_empty`, `is_not_empty` | same — id-membership works at the runtime layer (converged `[{id}]` containment) | Sorting orders by raw JSON, not display text — project the display (link extraction / `display_output`) and sort that. `unnest` fans link ids (+ display). |
 | files | `files` | `has_filename`, `has_mime_type` (substring), `has_file_count` (exact count), `is_empty`, `is_not_empty` | same | Presign-enriched at delivery (§1); `unnest` fans file ids. Only presence-counting aggregates. |
 | formula | its declared output type (`number`/`text`/`boolean`/`date`/`datetime`; `json` until inferred) | filtered by the output type's operators; `#ERROR:` cells are guarded — they count as empty and never match value operators | same | Extracted as a real scalar, so numeric formulas feed `sum`/`avg`/sorts. A **datetime-output** formula matches day-level date filters (full-day expansion). |
-| rollup | number-returning ops → `number`; `earliest`/`latest`/`date_range` → `date`/`datetime` per the aggregated field's format | number or date operators per output type; text operators route as text | same | Datetime-format rollups match day-level date filters. |
-| lookup | the looked-up field's type | operators of the looked-up type, evaluated with ANY-element semantics over the linked values (a row matches if *any* linked value matches) | array-typed lookups follow their column type's rules | **Projection returns the first element only.** Emptiness on a files-lookup checks the inner file arrays (a linked record with zero files counts empty). For all values across links: unnest the link column + join (§8). |
+| rollup | decided by the OPERATION, never by the aggregated field: `earliest`/`latest` → `date`/`datetime` per that field's format; **every** other op → `number` | number or date operators per output type; text operators route as text | same | Datetime-format rollups match day-level date filters. `date_range` counts DAYS between the extremes, so it is a number despite its date input. A presence count (`filled`/`empty`/`percent_*`) is a number whatever it counts — including over `files`. |
+| lookup | the type of the VALUE the looked-up field yields — a formula's output type, a rollup's operation result, an autonumber's display string (`text`); never the word `formula`/`rollup` | operators of that type, evaluated with ANY-element semantics over the linked values (a row matches if *any* linked value matches) | array-typed lookups follow their column type's rules | **Projection returns the first element only.** Emptiness on a files-lookup checks the inner file arrays (a linked record with zero files counts empty). For all values across links: unnest the link column + join (§8). |
 | autonumber | `text` | text operators — filter by the visible composed string (`"ORD-0042"`) | same | Sorts numerically when the stored value is a bare integer, lexicographically otherwise — so `"ORD-0042"` orders by its padding and an unprefixed `"124"` orders after `"99"`, not before it. |
 | button | `json` | **not filterable** — buttons are not data | — | Project/ignore; only presence-counting aggregates. |
 
@@ -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.0",
+  "version": "0.67.0",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {