@lotics/app-sdk 0.59.0 → 0.59.1

package/AGENTS.md

@@ -16,7 +16,7 @@ signature; open the file.**
 |---|---|
 | [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`), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, 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`. |
+| [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`, 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 `lotics app workflow check` loop. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs, workflow-generated files, 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. |

package/docs/mutations.md

@@ -319,6 +319,62 @@ flash to a spinner — `loading` stays false during revalidation). `usePaginated
 (`revalidateOnFocus`, default on) eventually self-corrects stale data, but never rely on it
 in place of an explicit refetch after a write the user is watching for.
 
+### A read must not overtake an in-flight write
+
+`refetch()` and a direct re-read know nothing about a write that is still running. On a record
+surface with inline (blur-committing) fields, a single gesture starts both: the field's write on
+mousedown, the button's handler on mouseup — so a handler that re-reads the record to build a
+document, mint something, or copy the row can read the row as it was BEFORE the edit. It fails
+silently: the screen shows the new value, the output carries the old one.
+
+Serialize them with one barrier per record surface — every write chains on, and the ONE place
+that re-reads stored state awaits it, so no handler can forget:
+
+```tsx
+// Per surface, not module-level: useMemo(createWriteBarrier, []) inside the hook.
+export function createWriteBarrier() {
+  let chain: Promise<unknown> = Promise.resolve();
+  return {
+    // Returns the write UNCHANGED — the caller keeps its own result + error handling;
+    // the chain never rejects, it only tracks when writes SETTLE.
+    track: <T,>(write: Promise<T>): Promise<T> => {
+      chain = chain.then(() => write).catch(() => undefined);
+      return write;
+    },
+    settled: () => chain,
+  };
+}
+
+const saveField = async (key: string, value: unknown) => {
+  const r = await writes.track(saveRecord({ record_id, [key]: value }));
+  if (r.status === "error") throw new Error(r.message);   // the inline editor keeps the edit
+};
+
+/** The ONLY re-read of stored state. Every handler goes through it — never the cached row. */
+const reload = async () => {
+  await writes.settled();
+  const res = await rpc<{ rows?: Rec[] }>("query", { alias: "record", params: { id: record_id } });
+  return res.rows?.[0] ?? null;
+};
+
+const printDoc = async () => {
+  const fresh = (await reload()) ?? current;   // reflects the edit the press just committed
+  await issueDoc(buildDoc(fresh));
+};
+```
+
+A handler that reads the row held in state instead has the same defect with no in-flight write
+needed — any edit since the row was loaded is missing. Build documents and mints from the
+re-read, not from the cached row.
+
+The same trap one level up: **an action takes an ID, never a captured object.**
+`onPress={() => issueInvoice(invoice)}` closes over the invoice as it was when the press
+happened, so no amount of waiting refreshes it — the confirm quotes, and the mint bills, the
+pre-edit total. Pass the key and resolve at use (`onPress={() => setConfirmKey(invoice.key)}`,
+then re-read or `find` where it is consumed). `@lotics/ui` gates the press itself
+(`docs/data_entry.md` § Inline edit), which fixes the ordering; the captured value is the app's
+to get right.
+
 ## Diff before update — send only what changed
 
 An edit form snapshots the record's values when it loads, and on save sends **only the fields

package/package.json

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