@lotics/app-sdk 0.59.0 → 0.59.4

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/dist/src/rpc.d.ts

@@ -178,6 +178,16 @@ export declare const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
  * `parsed` is the JSON.parse of the body, or `null` if it wasn't JSON.
  */
 export declare function transportErrorMessage(status: number, parsed: unknown): string;
+/**
+ * The error a stream that never started should throw.
+ *
+ * A streaming endpoint fails BEFORE the first byte like any other request — a 402 when the
+ * workspace is out of credits, a 403, a 404. Those bodies are structured errors, and throwing
+ * the body TEXT put the whole JSON on screen: `{"message":"Credit quota exceeded…","error":
+ * "quota_exceeded","plan_id":"free",…}`. Same rule as every other call: the `message` is the
+ * message, and a non-JSON or 5xx body never becomes one.
+ */
+export declare function streamStartError(res: Response): Promise<Error>;
 /**
  * A package installation's alias→concrete-id maps — what the generated
  * `.lotics/app_fields.ts` of a package project resolves `F`/`OPT`/`ROLE`

package/dist/src/rpc.js

@@ -257,8 +257,7 @@ export function rpcAgentRunContinue(payload, onText) {
             signal: controller.signal,
         });
         if (!res.ok || !res.body) {
-            const text = await res.text().catch(() => "");
-            throw new Error(text || `HTTP ${res.status}`);
+            throw await streamStartError(res);
         }
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
@@ -295,8 +294,7 @@ function agentRunStandalone(payload, onText, onRunId) {
             signal: controller.signal,
         });
         if (!res.ok || !res.body) {
-            const text = await res.text().catch(() => "");
-            throw new Error(text || `HTTP ${res.status}`);
+            throw await streamStartError(res);
         }
         const runId = res.headers.get("x-app-agent-run-id");
         if (runId)
@@ -410,8 +408,11 @@ async function boot() {
  * A user-facing message for a transport/gateway failure — derived from the HTTP
  * status, never from the response body. A 524 (Cloudflare edge timeout on a long
  * run), any 5xx, or a non-JSON body (an HTML error page) must NOT surface its raw
- * body as the error message. Kept in parity (by value, no shared dep) with the
- * dev-loop transport in `packages/sdk/src/client.ts`.
+ * body as the error message.
+ *
+ * A by-value MIRROR of `@lotics/shared/transport_error`, which is canonical. This
+ * package ships to npm with zero internal dependencies, so it cannot import it;
+ * every other transport does. Change one, change both.
  */
 function gatewayErrorMessage(status) {
     if (status === 524) {
@@ -437,6 +438,28 @@ export function transportErrorMessage(status, parsed) {
         ? gatewayErrorMessage(status)
         : jsonMessage;
 }
+/**
+ * The error a stream that never started should throw.
+ *
+ * A streaming endpoint fails BEFORE the first byte like any other request — a 402 when the
+ * workspace is out of credits, a 403, a 404. Those bodies are structured errors, and throwing
+ * the body TEXT put the whole JSON on screen: `{"message":"Credit quota exceeded…","error":
+ * "quota_exceeded","plan_id":"free",…}`. Same rule as every other call: the `message` is the
+ * message, and a non-JSON or 5xx body never becomes one.
+ */
+export async function streamStartError(res) {
+    const text = await res.text().catch(() => "");
+    let parsed = null;
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // not JSON — a gateway HTML page; transportErrorMessage will not surface it
+        }
+    }
+    return new Error(transportErrorMessage(res.status, parsed));
+}
 // Standalone requests carried no timeout: a hung or slow backend pinned the
 // fetch — and one of the browser's few per-origin connections — indefinitely,
 // surfacing as an app that "loads forever". Bound every standalone call the way

package/docs/ai.md

@@ -90,6 +90,16 @@ The terminal `submit_result` call is captured into `output`, **not** rendered as
 
 `AgentRun` renders thinking collapsed, groups consecutive tool calls, and expands each tool's input/output in place on press — all for free. Running it in a bounded container (a dialog, a panel)? Wrap it in `@lotics/ui`'s `FollowScroll` so the container follows the stream instead of letting new content grow below the fold. **Errors surface two ways:** a per-tool failure is an `output-error` part (amber dot, reason in the expanded Error panel — the feed flows on, exactly like a run that retried and recovered); a **breaking** error that killed the run lives in `run.error` (not in `parts`) — pass it as `error` and it renders as a terminal danger row. Never rebuild this feed by hand.
 
+`run.error` is always a **sentence to show a person**, never a payload — on both the ways a run can fail.
+
+*Before it starts*: the request is refused (most often a 402 when the workspace is out of AI credits — "Credit quota exceeded. Upgrade your plan for continued AI access." — or a 403/404). You get that response's `message` alone; the rest of the body (`error`, `plan_id`, `credits_used`, …) never reaches the string, and a non-JSON body or any 5xx is replaced by a status-derived message.
+
+*After it starts*: the run dies mid-flight, and the message is written **in the triggering member's language** (the workspace default when an anonymous visitor triggered it). An error the platform wrote surfaces as-is, so running out of credits **during** a run still says to upgrade rather than to retry. A provider or tool failure does NOT — its wording is a debugging string that names our request shape, so it becomes one of two sentences: the request itself was rejected (an attachment that is corrupt or too large — retrying unchanged cannot help), or it broke transiently and is worth another run. The raw error is kept in error tracking with the run id.
+
+Two caveats on that language guarantee. A message written at its throw site rather than fixed on its error class stays English — those strings are also what the chat agent reads to correct its own tool calls, so they are deliberately one language. And the *before it starts* case above is the API response's own `message`, which is not localized either. So an app that must be wholly in one language should render its own copy on failure rather than the platform's.
+
+So `error={run.error}` is safe to render verbatim. What it is NOT is machine-readable: `status` tells you a run failed, not why, and the difference between "worth retrying" and "retrying cannot help" lives in the sentence rather than in a code. **Do not parse it** — the wording is copy and will change. If your app needs to act on the distinction (a retry button that disables itself when a retry is futile, an upgrade prompt on a quota hit), that discriminator can be exposed; it is classified server-side already and simply is not on the wire yet.
+
 ### The agent asks back — `pendingChoice` / `answerChoice`
 
 Every app agent carries the platform's MANDATORY interactive tool `ask_user_choice` —

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,7 +1,7 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.59.0",
-  "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
+  "version": "0.59.4",
+  "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
     ".": {