@lotics/app-sdk 0.86.0 → 0.87.0

package/dist/src/new_record.d.ts

@@ -56,7 +56,7 @@ export interface NewRecordApi<P> {
  * const { id, save } = useNewRecord({
  *   create: (id, patch) => createCustomer({ record_id: id, ...patch }),
  *   update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
- *   onCreated: refetch,
+ *   onCreated: (id) => select(id),   // it exists now — the list re-reads itself
  * });
  * <InlineText onBlur={(name) => save({ name })} />
  * ```
@@ -64,6 +64,11 @@ export interface NewRecordApi<P> {
 export declare function useNewRecord<P>(opts: {
     create: (id: string, patch: P) => Promise<unknown>;
     update: (id: string, patch: P) => Promise<unknown>;
-    /** Runs once, after the record first exists. Pass a list `refetch` to reveal it. */
+    /**
+     * Runs once, after the record first exists, with its id. NOT for refetching a
+     * list — the `create` workflow's own success already re-read it. This is for
+     * what only the id can drive: routing to the record, selecting it, dropping the
+     * surface's "new" state.
+     */
     onCreated?: (id: string) => void;
 }): NewRecordApi<P>;

package/dist/src/new_record.js

@@ -56,7 +56,7 @@ export function newRecordId() {
  * const { id, save } = useNewRecord({
  *   create: (id, patch) => createCustomer({ record_id: id, ...patch }),
  *   update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
- *   onCreated: refetch,
+ *   onCreated: (id) => select(id),   // it exists now — the list re-reads itself
  * });
  * <InlineText onBlur={(name) => save({ name })} />
  * ```

package/dist/src/rpc.d.ts

@@ -176,11 +176,13 @@ export declare const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
 /** The run token header — mirrored server-side by `APP_AGENT_RUN_TOKEN_HEADER`. */
 export declare const APP_AGENT_RUN_TOKEN_HEADER = "x-app-agent-run-token";
 /**
- * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
- * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
- * 5xx, or a JSON body without a `message` falls back to a body-free,
- * status-derived message — so a raw HTML body never becomes the message.
- * `parsed` is the JSON.parse of the body, or `null` if it wasn't JSON.
+ * The error message for a non-ok response. A JSON error the API AUTHORED surfaces
+ * verbatim — a 4xx carrying a `message`, or a 5xx that also carries `code`, the
+ * discriminator every error the API emits is built with. A non-JSON body (a
+ * gateway HTML page), a 5xx from something that is not us, or a body without a
+ * `message` falls back to a body-free, status-derived message — so a raw HTML
+ * body never becomes the message. `parsed` is the JSON.parse of the body, or
+ * `null` if it wasn't JSON.
  */
 export declare function transportErrorMessage(status: number, parsed: unknown): string;
 /**

package/dist/src/rpc.js

@@ -519,19 +519,30 @@ function gatewayErrorMessage(status) {
     return "The service returned an unexpected response. Please try again.";
 }
 /**
- * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
- * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
- * 5xx, or a JSON body without a `message` falls back to a body-free,
- * status-derived message — so a raw HTML body never becomes the message.
- * `parsed` is the JSON.parse of the body, or `null` if it wasn't JSON.
+ * The error message for a non-ok response. A JSON error the API AUTHORED surfaces
+ * verbatim — a 4xx carrying a `message`, or a 5xx that also carries `code`, the
+ * discriminator every error the API emits is built with. A non-JSON body (a
+ * gateway HTML page), a 5xx from something that is not us, or a body without a
+ * `message` falls back to a body-free, status-derived message — so a raw HTML
+ * body never becomes the message. `parsed` is the JSON.parse of the body, or
+ * `null` if it wasn't JSON.
  */
 export function transportErrorMessage(status, parsed) {
     const jsonMessage = parsed && typeof parsed.message === "string"
         ? parsed.message
         : null;
-    return parsed === null || status >= 500 || jsonMessage === null
-        ? gatewayErrorMessage(status)
-        : jsonMessage;
+    if (jsonMessage === null)
+        return gatewayErrorMessage(status);
+    // Below 500 the body is ours. At 500 and above it is ours only if it carries
+    // `code` — the discriminator every error the API emits is built with. Status
+    // alone was the wrong test: it threw away the 503 our OWN backpressure gate
+    // authors and replaced it with a different English sentence, so no wording we
+    // choose for a 5xx could ever reach an app member (GAP-300). A gateway's HTML
+    // does not parse at all, and a proxy's JSON does not carry `code`, so both
+    // still get the body-free message.
+    const authored = typeof parsed.code === "string" &&
+        parsed.code.length > 0;
+    return status < 500 || authored ? jsonMessage : gatewayErrorMessage(status);
 }
 /**
  * The error a stream that never started should throw.

package/dist/src/use_optimistic.d.ts

@@ -3,9 +3,14 @@ export interface OptimisticApi<T> {
     items: T[];
     /**
      * Optimistically merge `next` into the item keyed `id`, then run `persist`.
-     * On resolve → `onSettled?.()` (pass your query's `refetch`); the patch is
-     * kept (it already matches the refetched value, so no flicker). On reject →
-     * the patch is reverted.
+     * On resolve → `onSettled?.()`; the patch is kept (it should already match
+     * what the write persisted, so the re-read lands underneath it without a
+     * flicker). On reject → the patch is reverted.
+     *
+     * `onSettled` is NOT for refetching the query this patch came from — a
+     * successful `useWorkflow` inside `persist` re-reads every mounted query on
+     * its own. Use it for what the write cannot know about: a total the app
+     * computed itself, an indicator to clear.
      */
     patch: (id: string, next: Partial<T>, persist: () => Promise<unknown>, opts?: {
         onSettled?: () => void;

package/docs/ai.md

@@ -28,7 +28,7 @@ A declaration carries:
 | `effort_level` | Optional reasoning depth for adaptive-thinking tiers. Requires an explicit `model_tier` pin — effort is tuned per tier |
 | `prefix_cache_ttl` | Optional prompt-cache window for the agent's stable prefix (tools + system). **Omit it** — the default (`"5m"`, Anthropic's own) is right for essentially every agent. `"1h"` is a leveraged bet: it doubles the write price (2x the input rate against 1.25x, both reading back at 0.1x) to buy only the five-minute-to-one-hour band. Declining it is never "uncached" — the same prefix stays cached at the default window. Set `"1h"` only with measured cadence showing runs reliably land in that band, such as a scheduled sweep |
 | `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it. **Every field defaults to `required: true`**, exactly as `outputs` does — the two extend the same base — so an input the caller may legitimately omit needs `"required": false`, or the run is rejected before the agent sees it |
-| `outputs` | Optional typed output schema. Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose). **Every field defaults to `required: true`** (the same base schema as `inputs` above) — mark `"required": false` on anything the source may legitimately not carry. It matters most for `number`, which has no blank: text can answer `""`, but a required number leaves only a wrong value or a rejected submission |
+| `outputs` | Optional typed output schema — the declaration vocabulary, including the two ways a `select` names its option set, is [mutations](./mutations.md#structured-results-return-data). Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose). **Every field defaults to `required: true`** (the same base schema as `inputs` above) — mark `"required": false` on anything the source may legitimately not carry. It matters most for `number`, which has no blank: text can answer `""`, but a required number leaves only a wrong value or a rejected submission |
 
 **Structured vs free-text is the load-bearing split.** A structured agent's result arrives in `run.output` (the server strictly validates the submitted result against the declared schema — see the `output` typing section for the exact guarantee); a free-text agent's answer is the transcript's prose (`run.text`) and its `output` stays `undefined` — never a stray string, so a consumer reading `output.<field>` can't crash on a free-text answer.
 
@@ -145,7 +145,9 @@ The server validates the agent's submitted result strictly (unknown keys rejecte
 
 - a field declared `required: false` may be absent;
 - a `json`-typed output field is passthrough — anything goes inside it;
-- `date` / `datetime` / `email` outputs are validated only as strings, not as well-formed values;
+- a `date` / `datetime` / `email` output is checked for well-formedness (`yyyy-MM-dd`, an ISO
+  timestamp, an address shape) but not for being the *right* value — a parseable date can still
+  be the wrong date;
 - every **value** was authored by the model — a schema-valid string can still be semantically wrong;
 - one live-stream corner: the hook adopts `output` from the submit call's **arguments as they stream**, before the server-side validation runs. Normally the loud rejection makes the agent retry and the last (valid) submit overwrites it — but a run whose *final* submit was rejected ends the live stream with that invalid attempt still in `output` (the persisted run settles as an error). The review surface below is the backstop.
 

package/docs/data_fetching.md

@@ -178,6 +178,15 @@ server validates system conditions by `type` and never reads `field_key` on them
 | `query execution failed` | The query failed at the database. Deliberately generic — database internals are never sent to the client. | The app author diagnoses from the platform's server logs; the app surfaces the message. |
 | A specific validation message | e.g. an un-projected `field_key` in runtime `sort`/`filter`, invalid params, an unknown alias. An unknown column names every column the query DOES project, so the valid set is in the message. | Fix the call site — these are contract violations, not transient. |
 
+**Which message you get is decided by the ENVELOPE, not the status** (SDK 0.85.0 — before it, the
+status alone decided). A failure whose JSON body carries a `code` is one the API authored, so its
+`message` is what `error` holds — including a 5xx, which is why the shed sentence in the table above
+reaches the app at all rather than being replaced by a generic one. Everything else — a gateway's
+HTML page, a proxy's JSON with no `code`, a body with no `message` — is plumbing, and `error` holds
+a fixed sentence derived from the status instead, so a raw HTML body can never become your error
+copy. Practically: for a 5xx you are now showing a sentence the PLATFORM wrote, so treat `error` as
+copy to display, never as a string to branch on.
+
 ## Pagination — two models
 
 Reads paginate two different ways, and the difference is load-bearing:

package/docs/mutations.md

@@ -138,9 +138,23 @@ envelope's grammar — `message` is required, `field_errors` never reaches the a
   refreshes that alias's generated types in the same command, so `result.data` is typed
   immediately — no hand-copy of the echoed schema, no second `lotics app codegen`. An
   **explicitly declared** `outputs` is authoritative and never overwritten. Declare an explicit
-  `outputs` (same recursive vocabulary as inputs: scalars plus nested `object`/`array`, no
-  member/file/date_range) only to narrow beyond what's inferred; a shape the checker can't pin
-  down degrades to untyped `json`, never to a wrong schema.
+  `outputs` only to narrow beyond what's inferred; a shape the checker can't pin down degrades
+  to untyped `json`, never to a wrong schema.
+- **The output vocabulary is the input one minus the caller-only types, and `select` behaves
+  differently.** Scalars (`text`/`number`/`boolean`/`date`/`datetime`/`email`), `record_link`
+  (`table_id`, `multi?`), `select`, `json`, and nested `object` (`fields`) / `array` (`items`).
+  No `member`, `file`, or `date_range` — those describe what a caller *sends*. `select` names
+  its option set the same two ways as an input (**exactly one** of inline
+  `options: [{label, value}]` or `field: "fld_…"`, and a `field` that doesn't exist or names a
+  non-select field is rejected at bind time by the same gate, worded `select output references
+  field …`), but enforcement is **stricter than on the input side**: an output's option set is
+  enforced as *membership*, not merely key format. Inline `options` are enforced against the
+  frozen set; a `field` form is resolved to the field's **current** options at run and enforced
+  against those. So a producer — a workflow's `return({ data })`, an app agent's
+  `submit_result` — is handed the legal keys and cannot settle a label where a key belongs.
+  Prefer `field` for any select backed by a real field (the generated type tracks it, no
+  redeploy); use inline `options` for a fixed enum the app owns or a select you plan to
+  **package** (a `field` form carries a concrete field id and can't ride a package contract).
 - **Validated at run.** On a success return, the returned `data` is validated against the
   schema at the app boundary — a mismatch resolves as `status: "error"` with a field-level
   message, so a declared output is a real contract. An *error* return's `data` passes through
@@ -347,7 +361,8 @@ flash to a spinner — `loading` stays false during revalidation). `usePaginated
 yourself is yours to refresh, so a write that changes the row COUNT must also refresh whatever
 you read it from, or the page moves while "of N" does not. Focus revalidation
 (`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.
+where the staleness is one of those three — the user is looking at the number now, not the
+next time they come back to the tab.
 
 ### A read must not overtake an in-flight write
 
@@ -506,9 +521,10 @@ Contract points:
   a whole. Include every changed field in the same call; don't submit per-field requests.
 - **Nothing changes immediately.** The tool returns
   `{ approval_request_id, status: "pending" }`; the record's values update only when an
-  approver (the table's configured approvers, else org admins) accepts. A `refetch()` right
-  after submitting shows the *old* values — render a "pending approval" state from the
-  result, don't poll for the new values.
+  approver (the table's configured approvers, else org admins) accepts. The submission
+  succeeds, so the automatic re-read fires and returns the *old* values — that is correct,
+  and it is why the pending state must come from the RESULT rather than from the row. Render
+  it from `data.request_id`; don't poll the record for values no one has approved yet.
 - **Requires a member actor.** The request is attributed to the triggering member; an
   anonymous caller through a public app is rejected. Gate the affordance on a signed-in
   viewer.
@@ -523,7 +539,8 @@ const save = async () => {
     if (res.status === "success") showPending();
   } else {
     const res = await updateOrder({ record_id, ...changes });
-    if (res.status === "success") orders.refetch();
+    if (res.status === "error") { showError(res.message); return; }
+    // orders re-reads itself — a successful write already said so.
   }
 };
 ```
@@ -543,9 +560,18 @@ patch(id, next, persist, opts?);
   item's stable key. `items` is `base` with pending patches merged per key (`{ ...item,
   ...patch }`); repeated patches on the same key merge.
 - `patch(id, next, persist, { onSettled })` applies `next` immediately, then runs the
-  `persist` thunk. On **resolve**, the patch is *kept* (it should match the refetched value —
-  no flicker) and `onSettled` runs — pass the owning query's `refetch`. On **reject**, the
-  patch is *reverted*.
+  `persist` thunk. On **resolve**, the patch is *kept* and `onSettled` runs. On **reject**,
+  the patch is *reverted*.
+- **`onSettled` is not where you refetch the query the patch came from.** The `persist` thunk
+  calls `useWorkflow`, and a successful write re-reads every mounted query by itself — so the
+  re-read is already in flight before `onSettled` fires, and passing `refetch` here buys a
+  second execution of the same query. Keep it for what the write cannot know about: a total
+  you computed yourself, a "saving…" indicator to clear, an analytics call.
+- **A kept patch stays merged over `base` for the life of the view.** It is never cleared on
+  success — the design assumes it equals what the server stored, so the re-read lands
+  underneath it with no flicker. Patch the value you are SENDING, not a display form of it: if
+  the server normalizes (rounds a time, trims a string, resolves a link's label), the
+  optimistic value masks the stored one permanently and nothing reports it.
 
 **Warning — the persist thunk must throw on `status: "error"`.** `useWorkflow` resolves on
 failure (the failure model above), and a resolved promise means "kept" to `useOptimistic` —
@@ -555,6 +581,7 @@ workflow failed. Convert the status into a rejection:
 ```tsx
 const q = useQuery("events");
 const reschedule = useWorkflow("rescheduleEvent");
+const mapped = useMemo(() => q.rows.map(toCalendarEvent), [q.rows]);
 const { items, patch } = useOptimistic(mapped, (e) => e.id);
 
 const onEventDrop = (ev: CalendarEvent, newStart: Date) =>
@@ -566,14 +593,13 @@ const onEventDrop = (ev: CalendarEvent, newStart: Date) =>
       const r = await reschedule({ record_id: ev.recordId, new_date: toISODate(newStart) });
       if (r.status === "error") throw new Error(r.message ?? "Reschedule failed");
     },
-    { onSettled: q.refetch },
   );
 ```
 
 This is the full read → mutate → reconcile loop: `useQuery` reads, `row.*` coerces,
-`useWorkflow` mutates, `useOptimistic` bridges the gap until `refetch` converges. Declare
-one workflow per (table, field) you mutate — typed and narrow, never a generic
-`setField(any_field)` that hands the client write access to every field
+`useWorkflow` mutates, `useOptimistic` covers the round-trip until the write's own re-read
+converges. Declare one workflow per (table, field) you mutate — typed and narrow, never a
+generic `setField(any_field)` that hands the client write access to every field
 ([security](./security.md)).
 
 ## Editing a record that does not exist yet: `useNewRecord`
@@ -590,7 +616,7 @@ id is known from the first render and the create stops being an event the UI has
 const { id, save } = useNewRecord({
   create: (id, patch) => createCustomer({ record_id: id, ...patch }),
   update: (id, patch) => updateCustomer({ record_id: id, ...patch }),
-  onCreated: list.refetch,
+  onCreated: (id) => select(id),
 });
 
 <InlineText onBlur={(name) => save({ name })} />
@@ -605,6 +631,9 @@ const { id, save } = useNewRecord({
 - **A failed create does not latch.** The next `save` retries the create, rather than updating a
   row that was never written while the UI looks like it saved.
 - `id` and `save` are stable across renders, so `save` can be bound directly to an `onBlur`.
+- **`onCreated` is not for refetching the list.** The `create` workflow succeeded, so every
+  mounted query re-read itself already. It runs once, with the id, for what only the id can
+  drive — routing to the record, selecting it, dropping the surface's "new" state.
 
 Your `create` workflow must pass the id through to `create_records` as `ids: [record_id]`.
 Creation is creation: an id that already exists is a conflict, never an overwrite — so the

package/docs/workflows.md

@@ -425,6 +425,15 @@ full menu by category, so a miss is one informed retry.
 | **Date** | `now`, `formatDate`, `parseDate`, `addDays`, `subDays`, `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`, `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`, `isSameDay`, `isToday`, `isWithinRange` |
 | **Other** | `formatCurrency(amount, locale, currency)`, `randomNumber(len)`, `randomAlphaNumeric(len)`, `sample(items)`, `current_member_in_any_group(["grp_…"])` |
 
+**Emptiness on a record cell.** `isNull` is the strict check — true only for `null`/`undefined`.
+A cleared cell does not always reach a workflow that way: the platform stores a cleared date or
+text as `""` and a cleared select, link or files cell as `[]`, so `isNull(record.data.ngay_doi_soat)`
+is **false** on a date the user emptied. Reach for `isEmpty` for the "has the user filled this in?"
+question — it covers `null`, `undefined`, `""` and `[]`. (`isNull` stays narrow on purpose: it is
+declared as a type predicate and every `?.` in a body lowers to it, so widening it would narrow
+`""` out of a branch that still receives it.) A FORMULA field is the one surface where the two
+agree: its evaluation context normalizes every unset cell to `null` before the expression runs.
+
 A few signatures worth knowing: `requireFirst(arr, message?)` asserts non-empty and returns `T`
 rather than `T | undefined` — pair it with a `validate` on `size(x) == 0` instead of wrapping
 every read in `if (x)`. `at(arr, -1)` counts from the end. `range(end)` / `range(start, end)`.
@@ -707,7 +716,8 @@ rejects, or read a path that is null on real data. The rehearsal for that is `dr
 `app_workflow_inputs`. It walks the real step tree with the production expression evaluator and
 hands back `planned_calls` (every tool call in order, with its fully-resolved input),
 `return_value`, `validation_failures`, `evaluation_errors`, and `tool_input_errors` — inputs the
-target tool would reject, which can only surface once the values are computed. **Write tools are
+target tool would reject, which can only surface once the values are computed. Loops run for real,
+every iteration, so a fold or a per-row fan-out is rehearsed at its true size. **Write tools are
 recorded, never dispatched**, and nothing is persisted.
 
 **Add `live_reads: true` whenever the body READS.** By default the read-only tools
@@ -721,6 +731,22 @@ which supply the real record as the payload AND turn live reads on; an app workf
 record — its payload is its inputs — so it asks for the reads directly.) Do this before the first
 live run of anything that writes.
 
+**`return_value` is what the CALLER receives**, not a summary of it: `{ status, message }` always,
+plus `data` when the body returns one and `field_errors` when it returns those — the same map a
+form reads. A `validate` step that fails produces the same shape the live run does: every failing
+check's message joined with `"; "`, and one `field_errors` entry per failing check that names a
+`field_key`.
+
+**A rehearsal can stop early, and it says so in `evaluation_errors`.** Four bounds apply — 1 000
+iterations of a `while` / `do_while` / `c_for`, 10 000 steps, 50 live reads, and 20 seconds — and
+tripping any of them appends an entry naming the bound and ending "the plan below is incomplete",
+then stops. So read `evaluation_errors` before reading `planned_calls`: an entry there may be a
+truncated plan rather than a bug in your body. A `foreach` is deliberately NOT capped at 1 000 —
+its length is known before the first iteration, so the rehearsal walks every item and instead
+refuses, up front, exactly the lists a live run refuses (over 10 000 items). The 50-live-read bound
+is the one `live_reads: true` makes reachable: a loop body that reads issues one real query per
+iteration.
+
 ## A worked body
 
 An app action that creates an order after checking for a duplicate, then returns the new id.

package/package.json

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