@lotics/app-sdk 0.58.5 → 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/docs/queries.md

@@ -583,7 +583,7 @@ the table.
 
 ## 8. Shaping: group, buckets, window, fan-out
 
-### The 20 aggregate operations
+### The 21 aggregate operations
 
 `group` and `window` share one operation vocabulary. `count` is `COUNT(*)` (no `input_column`);
 everything else requires an `input_column` whose type must be compatible — checked at deploy:
@@ -599,10 +599,38 @@ everything else requires an `input_column` whose type must be compatible — che
 | `percent_filled`, `percent_empty` | any except boolean | number | **fraction 0–1**, not 0–100; NULL for an empty group |
 | `unique`, `percent_unique` | text, number, date/datetime, select, select_member, select_record_link, files, json¹ | number | distinct **present** values; array cells compare as whole arrays |
 | `checked`, `unchecked`, `percent_checked`, `percent_unchecked` | boolean | number | `unchecked` counts false **or** empty |
+| `string_agg` | text, select | **text** | the distinct present values joined — the only operation returning values rather than a count. `group` only |
 
 ¹ opaque `json` columns support only the presence-counting six (`empty`/`filled`/`unique` and
 their `percent_*` forms).
 
+**`string_agg` — a summary column, not a dataset.** Every other operation counts or reduces to a
+number; this one joins the values, so a child set answers "which ones?" in the parent row (the
+sizes on a shipment, the tags on a ticket) without a second query.
+
+```jsonc
+{ "output": "sizes", "type": "text", "operation": "string_agg", "input_column": "size",
+  "distinct": true, "separator": ", ", "max_values": 20 }
+```
+
+- **`type` must be `text`** — declaring anything else is rejected at deploy.
+- **`distinct`** defaults to **true**: three containers sized 40HC/40HC/20DC give `20DC, 40HC`.
+  Pass `false` to keep every occurrence. Values are always sorted, so the column doesn't
+  reshuffle between reads.
+- **`max_values`** (default 20, max 100) caps the emitted values so an unbounded child set can't
+  produce a giant cell. It is a silent cap — pair it with a `unique` aggregate over the same
+  column to render an honest `+N more`.
+- **`separator`** defaults to `", "` (max 8 chars).
+- Empty values are dropped by the same emptiness contract below, so a partly-blank column
+  doesn't emit empty slots. A group with nothing present yields NULL.
+- **`group` only** — it is not in the OVER-legal set, because deduplication and window frames
+  are mutually exclusive in SQL. Setting `distinct` / `separator` / `max_values` on any other
+  operation is rejected rather than ignored.
+
+It is deliberately **not** a rollup field type: a rollup persists its value into record data and
+rewrites it on every child change, and an unbounded concatenation does not belong in a stored
+cell. Query-time only.
+
 **The one emptiness contract.** `filled`/`empty`/`unique`/`percent_*` use the same definition
 of "present" as the filter layer's `is_empty` and the `isEmpty` source: array-valued cells are
 empty at NULL / JSON `null` / `[]`; text at NULL or blank (whitespace-only); opaque json at
@@ -643,8 +671,8 @@ A `window` node carries two independent column lists — **`aggregates`** (frame
 **`aggregates` — the OVER-legal aggregate subset.** Only operations that compile to a single
 legal SQL window call are accepted: **`count`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`,
 `filled`, `checked`, `unchecked`.** The rest cannot take an OVER clause (`median` is an
-ordered-set aggregate; `unique`/`percent_unique` need DISTINCT; `range`/`empty`/`date_range`/
-`percent_*` compose multiple calls) — rejected at deploy. The optional `frame` applies **only**
+ordered-set aggregate; `unique`/`percent_unique`/`string_agg` need DISTINCT;
+`range`/`empty`/`date_range`/`percent_*` compose multiple calls) — rejected at deploy. The optional `frame` applies **only**
 to these; a `frame` on a window with no `aggregates` is rejected as dead config.
 
 **`functions` — ranking / navigation.** Each is `{ "output", "fn", … }` (its own arg shape, no

package/package.json

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