@lotics/app-sdk 0.83.1 → 0.84.0

package/AGENTS.md

@@ -16,8 +16,8 @@ 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 four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate silently at 10,000), 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/data_fetching.md](./docs/data_fetching.md) | The four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate silently at 10,000), 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) — and the fourth source, **this app's own successful write**, which re-reads every mounted query immediately rather than waiting on that push (→ [mutations](./docs/mutations.md)), 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, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), 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. |
@@ -34,6 +34,9 @@ signature; open the file.**
   A client-supplied member id is an IDOR. → [security](./docs/security.md)
 - **Server data is never copied into `useState`** — hooks are the source of truth; derive with
   `useMemo`. → [data_fetching](./docs/data_fetching.md)
+- **A successful write re-reads the screen for you** — do not chase a `useWorkflow` call with
+  `refetch()`. Reach for it only where a write cannot have told you: a poll, a value nothing on
+  this screen wrote, a total you supplied. → [mutations](./docs/mutations.md)
 - **Update writes are diffs** — send only changed fields, and *cleared* is a change: an optional
   input clears with `null` (never `""`), which `set_skip_null` drops and `set` performs.
   → [mutations](./docs/mutations.md)

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, subscribeQueriesChanged, } from "./rpc.js";
+import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeQueriesChanged, registerQueryAlias, notifyLocalWrite, } from "./rpc.js";
 import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, pendingInteractiveCall, buildChoiceOutput, applyInteractiveAnswer, landingOf, proseOf, ABORTED, } from "./agent_stream.js";
 import { getMockRows, getMockWorkflow, hasMockFlag } from "./mock.js";
 export { buildChoiceOutput } from "./agent_stream.js";
@@ -34,7 +34,18 @@ export function useWorkflow(alias) {
         if (mock) {
             return typeof mock === "function" ? await mock(inputs ?? {}) : mock;
         }
-        return rpc("workflow", { alias, inputs: inputs ?? {} });
+        const result = await rpc("workflow", { alias, inputs: inputs ?? {} });
+        // A workflow is the app's only write path, so a successful one means the
+        // rows on screen are stale. Re-read now rather than waiting for the host's
+        // realtime push to say what the caller already knows — that wait is what
+        // makes a screen feel like it lagged its own button.
+        //
+        // Only on success: a refused write changed nothing, and refetching after
+        // one would replace the values the user is still looking at (and about to
+        // correct) with an identical set, for a round trip nobody asked for.
+        if (result.status !== "error")
+            notifyLocalWrite();
+        return result;
     }, [alias]);
 }
 // Shared SWR config: surface a failed query immediately, keep the last good
@@ -79,10 +90,18 @@ function useHostRefetch(alias, refetch, mockRows) {
     useEffect(() => {
         if (hasMockFlag() || mockRows)
             return;
-        return subscribeQueriesChanged((aliases) => {
+        // Registered separately from the subscription because the two answer
+        // different questions: the subscription is "tell me when MY alias moved",
+        // the registration is "I am on screen, so a local write should re-read me".
+        const unregister = registerQueryAlias(alias);
+        const unsubscribe = subscribeQueriesChanged((aliases) => {
             if (aliases.includes(alias))
                 refetch();
         });
+        return () => {
+            unregister();
+            unsubscribe();
+        };
     }, [alias, refetch, mockRows]);
 }
 /**

package/dist/src/rpc.d.ts

@@ -149,6 +149,25 @@ export declare function postHostNotification(message: HostNotification): void;
  * stay on pull-based freshness.
  */
 export declare function subscribeQueriesChanged(cb: (aliases: string[]) => void): () => void;
+/** Register a mounted query's alias. Returns the matching unregister. */
+export declare function registerQueryAlias(alias: string): () => void;
+/**
+ * Re-read the mounted queries because THIS app just wrote.
+ *
+ * The host's `queriesChanged` push is for changes the app did not make — it
+ * travels the realtime path (a version counter, a socket the host owns, and
+ * coalescing that is deliberately lazy under load), which is right for another
+ * member's edit and far too slow for your own. A writer already knows, so it
+ * rings the same bell locally instead of waiting to be told.
+ *
+ * It names every mounted alias rather than only the ones the write touched: the
+ * app cannot know which tables a workflow wrote, and the alternative — asking
+ * every call site to declare what it invalidates — is a list that goes stale
+ * silently the first time a workflow body grows a second write. The cost is
+ * bounded by what is on screen, and it is the work the app was going to do a
+ * moment later anyway.
+ */
+export declare function notifyLocalWrite(): 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

@@ -111,6 +111,50 @@ export function subscribeQueriesChanged(cb) {
         refetchSubscribers.delete(cb);
     };
 }
+/**
+ * Every alias with a mounted query hook, so a local write can name them.
+ *
+ * Registered by the hooks themselves rather than derived from the manifest: what
+ * matters is what is ON SCREEN, and a screen mounts a handful of an app's
+ * queries. Keyed by alias with a count, because two hooks can read one alias at
+ * once (a register and the drawer over it) and the first to unmount must not
+ * retract the second's registration.
+ */
+const mountedAliases = new Map();
+/** Register a mounted query's alias. Returns the matching unregister. */
+export function registerQueryAlias(alias) {
+    mountedAliases.set(alias, (mountedAliases.get(alias) ?? 0) + 1);
+    return () => {
+        const n = (mountedAliases.get(alias) ?? 1) - 1;
+        if (n > 0)
+            mountedAliases.set(alias, n);
+        else
+            mountedAliases.delete(alias);
+    };
+}
+/**
+ * Re-read the mounted queries because THIS app just wrote.
+ *
+ * The host's `queriesChanged` push is for changes the app did not make — it
+ * travels the realtime path (a version counter, a socket the host owns, and
+ * coalescing that is deliberately lazy under load), which is right for another
+ * member's edit and far too slow for your own. A writer already knows, so it
+ * rings the same bell locally instead of waiting to be told.
+ *
+ * It names every mounted alias rather than only the ones the write touched: the
+ * app cannot know which tables a workflow wrote, and the alternative — asking
+ * every call site to declare what it invalidates — is a list that goes stale
+ * silently the first time a workflow body grows a second write. The cost is
+ * bounded by what is on screen, and it is the work the app was going to do a
+ * moment later anyway.
+ */
+export function notifyLocalWrite() {
+    if (mountedAliases.size === 0)
+        return;
+    const aliases = [...mountedAliases.keys()];
+    for (const cb of refetchSubscribers)
+        cb(aliases);
+}
 const pending = new Map();
 const streaming = new Map();
 /** `useUrlState` subscribers — notified when the host broadcasts new params

package/docs/data_fetching.md

@@ -116,9 +116,9 @@ 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), 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.
+  (`revalidateOnFocus`, default on), a **realtime push**, and **this app's own successful write**,
+  which re-reads every mounted query without being asked (see
+  [./mutations.md](./mutations.md)). `refetch()` covers what none of those can know about.
 - **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
@@ -153,10 +153,11 @@ server validates system conditions by `type` and never reads `field_key` on them
   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
-  (a caller-supplied `total` is the caller's to refresh).
+- **`refetch()`** re-runs the query. A successful `useWorkflow` call already re-reads the mounted
+  queries on its own (see [./mutations.md](./mutations.md)), so reach for this only where a write
+  cannot have told you: a poll, a value that changes without anything on this screen writing, or a
+  total you supplied yourself. `usePaginatedQuery.refetch()` refreshes the page, and the count when
+  the hook owns it (a caller-supplied `total` is the caller's to refresh).
 - **Ambient-chat mutations refetch automatically.** When the member's ambient chat agent (see
   [./ai.md](./ai.md#useaicontextslot-context--tell-the-ambient-chat-what-the-member-is-looking-at))
   finishes a turn that mutated records, the host pushes **every mounted query hook** to re-read —

package/docs/mutations.md

@@ -3,7 +3,7 @@
 Everything about writing data from an app: `useWorkflow` (the only write path), the
 `WorkflowResult` contract and its resolve-never-throw failure model, declaring typed workflow
 inputs (file/member/optional inputs), returning structured data with `return({ data })`,
-refetching after a mutation, the diff-before-update discipline, locked records
+the automatic re-read a successful write triggers, the diff-before-update discipline, locked records
 (`readLocked` + `request_locked_record_change`), and optimistic reconciliation
 (`useOptimistic`). Read this before building any screen that creates, updates, or deletes
 records. What may be written **inside** the workflow body — the JS subset, steps, helpers,
@@ -89,7 +89,7 @@ if (result.status === "error") {
   showError(result.message ?? "Something went wrong.");
   return;
 }
-orders.refetch();
+// Success. Mounted queries re-read themselves — see "Refetch after a mutation".
 ```
 
 **Warning:** a `try/catch` with no `status` check silently treats every workflow failure as
@@ -312,9 +312,9 @@ is [workflows](./workflows.md#writing-records).
 
 ## Refetch after a mutation
 
-Query hooks cache through SWR and know nothing about your workflows — a successful mutation
-does **not** invalidate any query. After a known mutation point, call the owning query hook's
-`refetch()`:
+**A successful workflow re-reads the queries that are mounted, on its own.** A workflow is the
+app's only write path, so the rows on screen are stale the moment one succeeds — the SDK
+re-reads them rather than making every call site remember to. Nothing to call:
 
 ```tsx
 const items = useQuery("items");
@@ -323,10 +323,24 @@ const closeItem = useWorkflow("closeItem");
 const onClose = async (recordId: string) => {
   const r = await closeItem({ record_id: recordId });
   if (r.status === "error") { showError(r.message); return; }
-  items.refetch();
+  // items re-reads itself — a successful write already said so.
 };
 ```
 
+Only on **success**: a refused write changed nothing, and re-reading after one would swap the
+values the user is still looking at, and about to correct, for an identical set.
+
+It names every MOUNTED alias, not the ones the write touched — an app cannot know which tables
+a workflow body wrote, and a per-call-site list of what to invalidate goes stale silently the
+first time that body grows a second write. The cost is bounded by what is on screen.
+
+This is separate from the host's realtime push, which carries changes **other** people make and
+travels a socket the host owns. That path is right for someone else's edit and far too slow for
+your own — waiting on it is what makes a screen feel like it lagged its own button.
+
+`refetch()` remains for the reads a write cannot know about: a poll, a value the user expects to
+change without writing anything, or a total you supplied yourself (below).
+
 `refetch` re-runs the query in the background while the current rows stay on screen (no
 flash to a spinner — `loading` stays false during revalidation). `usePaginatedQuery`'s
 `refetch` re-runs the current page, and the count when the hook owns it — a total you supplied
@@ -411,7 +425,13 @@ Why a full-form snapshot save is a bug, not a style choice — three independent
 3. **Snapshots clobber concurrent edits.** An update writes exactly the fields present in the
    payload; unsent fields keep their current value. A diff therefore coexists with a
    colleague's concurrent edit to a *different* field — a snapshot overwrites it with the
-   stale load-time value.
+   stale load-time value. The coexistence stops at field granularity: sending the full array
+   of a multi-value field is a snapshot *inside* that field, so two writers appending to it
+   each keep the array they read and the later one wins, both reporting success. When the
+   append is the system's rather than a person's — an upload settling, a workflow attaching a
+   generated document — name the ITEMS with `add_to` / `remove_from`
+   ([workflows](./workflows.md#writing-records)) and the write path resolves them against the
+   record as it stands.
 
 ```tsx
 // load: snapshot the editable fields from the row

package/docs/workflows.md

@@ -482,6 +482,14 @@ differ from `<` / `>` (code-unit order) and from the database's collation.
 | `add_to` / `remove_from` / `replace` | `{ fld_x: [items] }` | surgical edits on multi-value fields (files, multi select, multi member, record links) |
 | `field_edits` | `[{ field, op, value }]` | the same surgical ops with the field named by a **string expression** — the only way to target a field chosen at run time |
 
+`add_to` / `remove_from` are RELATIVE: the server resolves them against the record as it stands
+when the write lands, inside the lock it already takes. Two runs appending to one field at the
+same time therefore each keep their item — which reading the field and writing the whole array
+back through `set` does not, since both fold onto the array they read and the later write drops
+the earlier, both reporting success. Parallel runs are ordinary (a trigger firing twice, an agent
+emitting two calls in one step), so reach for the ops rather than a read-modify-write whenever
+the workflow is ADDING to a field rather than stating it.
+
 Inside `set` and `create_records.records`: `null` clears (persisted), `undefined` or an omitted
 key preserves. So passing a possibly-null read straight through is safe. Use
 `coalesce(x, fallback)` only when you want a real fallback, never to "strip" null.

package/package.json

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