@lotics/app-sdk 0.58.1 → 0.58.4

package/AGENTS.md

@@ -17,6 +17,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/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. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |

package/docs/mutations.md

@@ -6,8 +6,10 @@ inputs (file/member/optional inputs), returning structured data with `return({ d
 refetching after a mutation, 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. Reading data is [queries](./queries.md) + [data_fetching](./data_fetching.md);
-uploads are [files](./files.md); who a write runs as is [security](./security.md).
+records. What may be written **inside** the workflow body — the JS subset, steps, helpers,
+traps — is [workflows](./workflows.md). Reading data is [queries](./queries.md) +
+[data_fetching](./data_fetching.md); uploads are [files](./files.md); who a write runs as is
+[security](./security.md).
 
 ## The write model
 
@@ -124,9 +126,10 @@ separate, optional step. Previewing/downloading files: [files](./files.md).
 
 ### Structured results: `return({ data })`
 
-A workflow body ends with `return({ status, message?, data? })`. `data` is arbitrary
-structured data (computed totals, row lists, status objects) the app reads back as
-`result.data`:
+A workflow body ends with a `return({ status, message, field_errors?, data? })` step (the
+envelope's grammar — `message` is required, `field_errors` never reaches the app — is
+[workflows](./workflows.md#return--the-envelope)). `data` is arbitrary structured data
+(computed totals, row lists, status objects) the app reads back as `result.data`:
 
 - **Typed for free — persisted at `set`.** The alias's `outputs` schema is derived at save
   time from the inferred TypeScript type of the body's `return({ data })` — the return *is*
@@ -289,7 +292,9 @@ await update_records({
 `set_skip_null` **skips** it. That is the per-field "clear vs. leave unchanged" choice, so a field
 may appear in **at most one** of `set` / `set_skip_null` (naming it in both is rejected at run
 time). An all-absent `set_skip_null` with no other write surface is a no-op — no records touched,
-no `before_update` hooks.
+no `before_update` hooks. The full write surface (`set`, `set_skip_null`, the surgical
+`add_to`/`remove_from`/`replace` ops, `field_edits`, and the exact value shape per field type)
+is [workflows](./workflows.md#writing-records).
 
 ## Refetch after a mutation
 

package/docs/workflows.md

@@ -0,0 +1,677 @@
+# Workflows — the body-authoring reference
+
+The grammar of a **workflow body**: what may be written inside `src/workflows/<alias>.ts`, the
+JS subset that is accepted, and the rules that decide whether a body saves. Every write an app
+performs runs through one of these bodies, so this is the other half of the write path —
+[mutations](./mutations.md) owns the *call* side (`useWorkflow`, the `WorkflowResult` contract,
+declaring typed inputs, reading `result.data` / `result.files`); this document owns everything
+between the braces. Read it before authoring or editing any body.
+
+## The mental model
+
+A workflow body is **a strict subset of JavaScript that is never executed**. At save time the
+source is parsed into a typed step tree, type-checked against a generated `.d.ts` of your
+workspace, resolved, linted, and stored as data. At run time the engine walks that tree — no JS
+engine, no `eval`, no sandbox. Four consequences shape everything below:
+
+- **Only the listed forms exist.** Anything outside them fails the save with a precise error
+  naming the rule and, where one exists, the substitute. A save never partially succeeds.
+- **A successful save may still return `warnings[]`** — advisory lint that does not block
+  (a possible infinite loop, a link path more than three hops deep, a button action with no
+  `validate` guard). Read them; they are the failures that only show up in production.
+- **One canonical form per concept.** Several JS spellings are accepted and *lowered* to one
+  stored form. The stored tree renders back to source on `lotics app pull`, so a pulled body
+  shows the canonical spelling, not the sugar you typed (see *Round-tripping* below).
+- **Opaque keys, never display names.** Fields are `fld_*`, select options are `opt_*`, tables
+  are `tbl_*`, groups are `grp_*`. A display name is rejected at save with an error pointing at
+  the right key. The generated types carry the human-readable name in a JSDoc comment; the
+  *value* is always the key.
+
+```js
+// A field read by its opaque key, compared against one of that field's option keys:
+if (order.data["fld_status"] == "opt_open") { … }
+```
+
+## Where a body lives
+
+`lotics app pull` writes each bound alias to `src/workflows/<alias>.ts` — the filename **is**
+the alias — wrapped in an `async function __workflow()` envelope under a generated header that
+references `.lotics/workflows/<alias>.globals.d.ts`. Edit only between the wrapper lines.
+
+| Command | What it does |
+|---|---|
+| `lotics app codegen` | (re)generates the per-alias `.d.ts` so the body is locally typed |
+| `lotics app workflow check [alias]` | reproduces the server's save-time verdict locally (below) |
+| `lotics app workflow set <alias>` | strips the envelope and pushes the body; the **server re-verifies** |
+| `lotics app deploy` | ships code, queries, capabilities — **never** binds or updates a workflow |
+
+For a brand-new alias, declare it in `package.json#lotics.workflows.<alias>` first (its `inputs`;
+leave `outputs` off to let the body's `return({ data })` derive it), write the body, `codegen`,
+`check`, then `set`. Input declaration vocabulary and validation:
+[mutations](./mutations.md#declaring-workflow-inputs).
+
+An app workflow body carries **no trigger declaration** — the binding supplies the trigger
+context. A stray `on({ … })` line is rejected.
+
+## Expression sources
+
+Every read starts from one of a fixed set of roots. Which roots exist depends on what the
+workflow is attached to — these are *ambient declarations*, so an unavailable root is a
+compile-time "cannot find name", not a runtime `undefined`.
+
+| Root | Available in | Value |
+|---|---|---|
+| `trigger` | every context | the trigger namespace. For an app workflow: `trigger.app_workflow.inputs.<name>` |
+| `runtime` | every context | execution context — see the key table below |
+| `record` | button + table-lifecycle workflows | the record the trigger fired on (merged data on update) |
+| `prev_record` | table `*_update` / `*_delete` | the prior record state — same shape as `record`, link descent included |
+| `changes` | table `*_update` | per-field diff — a *partial* map, so read it `changes["fld_x"]?.next_value` / `?.prev_value` |
+| `index` | inside a `for-of` body | the current 0-based iteration index |
+| `<bind_name>` | inside a `for-of` body | the current item |
+| `<step_id>` | after the step | that step's output (`rows.records`, `approval.status`, …) |
+| `<let_name>` | its block | a mutable `let` binding |
+| `<param>` | inside a helper callback | that lambda's parameter |
+
+`record`, `prev_record` and `changes` are the **canonical** roots — the spelling a `pull` hands
+back. The raw trigger payload carries the same three views under `trigger.data`,
+`trigger.prev_data` and `trigger.changes`; those spellings are **accepted and mean exactly the
+same thing** (the parser lowers each onto the root, so both save to one AST and read one value),
+but a saved body prints back in the bare form. Write the bare form.
+
+A **body in `src/workflows/`** is an app workflow: it sees `trigger` and `runtime` only. There is
+no `record` — an app workflow is not attached to a table. Pass the record id in as a
+`record_link` input and `get_record` it.
+
+`runtime` keys: `timezone`, `now`, `workflow_id`, `execution_id`, `workspace_id`,
+`organization_id`, `triggered_by_member_id` (`null` for a system trigger or an anonymous
+public-app caller), and `change_origin` — a discriminated union over how the **execution** was
+started: `button` · `automation` · `app_action` · `app_workflow` · `table_workflow`. It describes
+the dispatch, never the person, and it is fixed per attachment — an app workflow always reads
+`app_workflow`, a table workflow always `table_workflow`. To branch on *who wrote the record*,
+read `trigger.change_origin` on a table workflow (that one carries the originating write's
+origin, and spans every write path: `member`, `chat_agent`, `app_workflow`, …). `runtime`
+is never null, so `runtime?.x` is rejected outright. Prefer the helper `now()` over
+`runtime.now`.
+
+Authorizing the *person* who triggered the run is a separate concern from the authority the run
+executes under — see [security](./security.md) and `current_member_in_any_group` below.
+
+### Path access
+
+| Form | Meaning |
+|---|---|
+| `["fld_x"]` / `.fld_x` | field access by opaque key — both spellings work; brackets read better |
+| `[n]` / `[<expr>]` | array index, literal or computed |
+| `["fld_link"][0]["fld_name"]` | descend into the *n*-th linked record and read one of its fields |
+| `.key` | plain object key on a step output (`rows.records`, `doc.file_id`) |
+
+**A path must start at a root.** It cannot hang off a helper call: `first(rows.records).id` is
+rejected. Bind the call (`const top = first(rows.records);` then `top.id`) or index the array
+directly (`rows.records[0].id`).
+
+**Link descent is a lazy fetch, and it must be one unbroken path.**
+`order.data["fld_link"][0]["fld_name"]` works because the walker fetches the linked row where the
+`[index]` is syntactically attached — scoped to the run's authority, null-tolerant, cached per
+execution. It collapses along a single path from a record read: `record` / `prev_record`, a
+`for-of` item, a lambda parameter, a `let` binding, or a `get_record` / `query_records` step
+output — the last of these only when the call passed a **literal** `table_id`, since that is what
+lets the server resolve the table at save.
+
+The moment you *materialize* the array (`const ids = order.data["fld_link"]`), `ids` is what it
+always was at runtime: a plain `string[]` of record ids. `ids[0]` is a bare `rec_*` **string**,
+and reading a field off it is a loud runtime error — one the type checker does **not** catch,
+because `ids` keeps the linked-record type it had on the path. Pass it where a record id is wanted
+(`record_id: ids[0]`), `get_record` it, or keep the read as one path. Descent also terminates
+after **one hop** in the type system: a linked row's own link fields type as ids. Deeper reads
+take the id and `get_record` it.
+
+## Step forms
+
+The body is a sequence of statements, each of which maps 1:1 onto a stored step.
+
+| Form | Syntax |
+|---|---|
+| Tool call, with output | `const <id> = await <tool>({ …kwargs });` |
+| Tool call, no output | `await <tool>({ …kwargs });` |
+| Bind (compute once, reuse many) | `const <id> = <expression>;` |
+| Mutable binding | `let x = <expr>;` then `x = …`, `x += …`, `x++` |
+| Branch | `if (<expr>) { … } else if (<expr>) { … } else { … }` |
+| Switch | `switch (<expr>) { case "X": { … } default: { … } }` |
+| Iterate | `for (const item of <expr>) { … }` |
+| Count / condition loops | `for (let i = 0; i < n; i++) { … }`, `while (…) { … }`, `do { … } while (…);` |
+| Loop control | `break;` / `continue;` |
+| Error handling | `try { … } catch (e) { … }` |
+| Pause | `await wait({ duration_in_minutes: 5 });` |
+| Pause for an event | `await wait_for_event({ event_type: "payment" \| "webhook", event_ref, timeout_in_minutes? });` |
+| Pause for a decision | `const a = await wait_for_approval({ approvers, prompt, timeout_in_minutes? });` |
+| LLM reasoning | `const x = await agent({ instructions, input, tools, model?, output });` |
+| Guard | `validate({ checks: [{ fail_when, field_key?, message }, …] });` |
+| End the run | `return({ status, message, field_errors?, data? });` |
+
+`validate` and `return` are **calls**, not JS keywords in the usual sense — `return` happens to
+be spelled with the JS `return` statement, but its argument is a single object literal and the
+key set is closed. A key outside `{status, message, field_errors, data}` is rejected.
+
+### Step ids, names, and comments
+
+The binding name on `const x = await tool({…})` **becomes the step id**, which is how later
+expressions read the output (`x.records`). A `// id: my_step` comment immediately above a
+statement sets an explicit id — the name must be a plain identifier (`[A-Za-z_][A-Za-z0-9_]*`),
+and a line that misses that shape is **not** an error: it falls through and becomes description,
+leaving the step id as the binding name. Any other `//` comment lines above a statement become
+the step's description, which is what the execution log shows.
+
+```js
+// id: find_duplicates
+// Block the write when the code is already in use
+const dup = await query_records({ table_id: "tbl_orders", filters: { … } });
+```
+
+Names live in one flat namespace. A binding, step id, `for-of` bind, or lambda parameter may not
+collide with a tool, a helper (`size`, `first`, `filter`, … are all taken), a reserved root, or a
+declared function. **Step ids are unique across the whole body** — a `const` inside an `if`
+claims its name everywhere, so a second `const a` in any block is rejected. Only `let` bindings
+and `for-of` binds are block-scoped: each may shadow an outer one of the same name, neither leaks
+out of the `if` / loop / `try` that declares it, and neither may take a name a step id already
+holds. A lambda parameter must likewise be free of every step id, enclosing `for-of` bind, and
+enclosing lambda parameter.
+
+### `return` — the envelope
+
+```js
+return({ status: "success", message: "Order created.", data: { total: subtotal } });
+```
+
+- `status` is a literal `"success"` or `"error"`. `message` is **required** (any string
+  expression). Both `field_errors` and `data` are optional.
+- `data` is what the app reads back as `result.data`; the alias's `outputs` schema is derived at
+  save from its inferred type. Full contract: [mutations](./mutations.md) § "Structured results".
+- `field_errors` annotates a *rejected record write* — it is consumed by the table-workflow
+  surface for cell-level error rendering. An app-invoked workflow surfaces only `status`,
+  `message`, `data`, and `files`, so put anything the app must read under `data`.
+- A body that completes without hitting a `return` resolves `status: "success"` with no `data`.
+- Generated documents never travel through `data`; they are collected into `result.files[]`
+  automatically ([files](./files.md)).
+
+### `validate` — the guard
+
+```js
+validate({ checks: [{
+  fail_when: size(dup.records) > 0,
+  field_key: "fld_order_code",
+  message: "This order code already exists.",
+}]});
+```
+
+`fail_when` rejects when truthy. `field_key` is an optional literal `fld_*`. A failing check ends
+the run as `status: "error"` with the failing messages joined — cleanly, not as a crash: it is
+control flow, so **`try`/`catch` does not catch it** (nor `return`).
+
+### `wait_for_approval` — the one wait worth binding
+
+```js
+const approval = await wait_for_approval({
+  approvers: trigger.app_workflow.inputs.approvers,
+  prompt: `Approve this order?`,
+});
+
+if (approval.status == "approved") { … } else { … }
+```
+
+Output: `{ status: "approved" | "rejected" | "timed_out", decided_by: MemberId | null,
+decided_at: string, decision_comment: string | null }`. `approvers` takes loose forms — bare
+`"mbr_*"` and `"grp_*"` strings are wrapped by prefix, full principal objects
+(`{ type: "member" | "member_group" | "organization", id }`) pass through — so a `select_member`
+field value or a `member` input works unwrapped. An approvers value that resolves to nobody ends
+the run legibly as `status: "error"` naming the bad value; it does not throw.
+
+Plain `wait` and `wait_for_event` carry no payload and are statement-only. `wait.duration_in_minutes`
+and every `timeout_in_minutes` must be a **positive number literal**, not an expression, and
+`wait_for_event.event_type` is a string literal from a closed set — `"payment"` or `"webhook"`.
+
+### `agent` — LLM reasoning as one step
+
+```js
+const order = await get_record({ table_id: "tbl_orders", record_id: i.order_id });
+
+const summary = await agent({
+  instructions: "Summarize the order in one sentence for an internal digest.",
+  input: { code: order.data["fld_order_code"], total: order.data["fld_total"] },
+  tools: [],
+  output: { mode: "text" },
+});
+```
+
+Two scoping rules govern what crosses into and out of the step; both surface as "cannot find
+name" when broken:
+
+- **Only `input` sees the workflow.** It must be an **object literal**; its field values are
+  ordinary expressions and are the *only* workflow data the agent receives. `instructions` is a
+  static string literal and `tools` a literal array of tool names — neither may read a binding,
+  so do not interpolate a record into `instructions`; move it into `input`.
+- **Only the bound name comes back.** In `{ mode: "text" }` the result *is* the string — use it
+  directly. In `{ mode: "object", schema }` the `schema` is itself a top-level object declaration
+  (`{ type: "object", fields: { total: { type: "number" }, … } }`, the same vocabulary as an
+  alias's `outputs`); read the declared fields as `x.field`, and a name not in `schema` does not
+  exist. The agent's own tool calls and reasoning are not readable.
+
+`model` is an optional pin — omit it to follow the platform default. The step is atomic (no wait
+or approval inside it).
+
+### `try` / `catch`
+
+```js
+try {
+  await send_email({ to: recipient, subject: "Receipt", body: text });
+} catch (e) {
+  await update_records({ table_id: "tbl_orders", record_ids: [id], set: { fld_note: e.message } });
+}
+```
+
+`e` is shaped `{ message, type, step_id?, detail? }`. Caught: tool errors and expression errors
+thrown inside the body. **Not caught:** `validate` failures and `return` (control flow), and
+errors from steps that run on *resume* after a `wait` inside the body — the wrapper spans one
+execution pass. There is no `finally`: put always-run steps after the `try`, always-on-failure
+steps in the `catch`.
+
+### Loops
+
+`for-of` is the workhorse; `while`, `do…while`, and counter `for` loops all work, each with a
+runtime cap of 10 000 iterations and a re-checked wall-clock budget. `for-in` is not supported.
+Bodies may not be empty. `break` / `continue` must sit inside a loop body, and labels
+(`break outer;`) are not supported.
+
+```js
+let created = [];
+for (const line of trigger.app_workflow.inputs.lines) {
+  const row = await create_records({ table_id: "tbl_lines", records: [{ fld_qty: line.qty }] });
+  created.push(line.qty);   // the accumulator idiom
+}
+```
+
+## Operators
+
+Precedence is JS's: `? :`, `||`, `??`, `&&`, `== != === !==`, `< <= > >=`, `+ -`, `* / %`,
+prefix `!` and `-`. Both equality forms work as in JS — `==`/`!=` loose, `===`/`!==` strict.
+
+Not supported: `**`, bitwise operators, `||=` / `&&=` / `??=`, `in`, `typeof`, `instanceof`,
+`delete`, `void`.
+
+**Ordered comparison against null is `false`, never a throw.** `<`/`>`/`<=`/`>=` with a
+null/undefined operand evaluate to `false`. A mismatch between two *non-null* operands still
+throws, naming the offending value.
+
+## The sugar list
+
+Each of these is accepted and lowered to a canonical stored form at save. Knowing the list
+matters twice: it is what you may write, and it is why a pulled body does not look like what you
+typed.
+
+| You write | It stores as |
+|---|---|
+| `a ?? b` | `coalesce(a, b)` |
+| `a?.b`, `a?.["k"]`, `a?.[0]`, `a?.length`, `a?.trim()` | `isNull(a) ? null : …` — one guard per `?.` |
+| `` `Total: ${x}` `` | a template expression |
+| `x.trim()`, `arr.includes(v)` | `trim(x)`, `includes(arr, v)` — the method form, and only for a helper that is also a real JS method (see *Helpers*) |
+| `arr.map(fn)` | `pluck(arr, fn)` |
+| `x.length` (dot only) | `length(x)` — strings and arrays. `x["length"]` still reads a field |
+| `String(x)`, `Number(x)`, `parseFloat(x)`, `+x` | `toString(x)` / `toNumber(x)` |
+| `x.toUpperCase()`, `x.toLowerCase()` | `upper(x)`, `lower(x)` |
+| `x.toFixed(2)` | `formatNumber(x, 2)` |
+| `Math.round/min/max/abs/floor/ceil/pow/sqrt(…)` | the like-named helper |
+| `Math.max(...arr)` / `Math.min(...arr)` | `max(arr)` / `min(arr)` |
+| `JSON.parse`, `JSON.stringify` | `parseJson`, `toJson` |
+| `Array.isArray`, `Object.keys/values/entries` | `isArray`, `keys`/`values`/`entries` |
+| `arr.at(i)` | `at(arr, i)` — negative counts from the end |
+| `arr.filter(Boolean)` | `compact(arr)` — drops every falsy element |
+| `[...a, b]` | `concat(a, [b])` |
+| `{ ...a, b: 1 }` | `merge(a, { b: 1 })` — later sources win, as in JS |
+| `{ table_id }` | `{ table_id: table_id }` — in expressions **and** tool inputs |
+| `xs.push(a, b);` | `xs = concat(xs, [a, b])` — statement form, on a `let` binding |
+| `x += 1`, `i++`, `--i` | `x = x + 1`, … (also in a c-`for` init/update) |
+| `const { records } = await query_records({…});` | one bind per name off a synthetic step id |
+| `function (x) { return e; }` in callback position | the same lambda node as `(x) => e` |
+
+`parseInt` is **rejected** rather than aliased: `toNumber` has `parseFloat` semantics and would
+silently drop the radix. Parse with `toNumber(x)`, then `floor` / `ceil` / `round`.
+
+**Spread is rejected anywhere inside a tool input**, at any nesting depth — static analysis reads
+those keys to extract table and file ids. Bind the merged value first, then pass the binding.
+Computed property keys (`{ [k]: v }`) are rejected everywhere for the same reason; to write a
+field chosen at runtime, use `field_edits` (below).
+
+### Destructuring
+
+```js
+const { records } = await query_records({ table_id: "tbl_orders" });
+const { fld_status: status, "fld_order_code": code, fld_note = "" } = order.data;
+for (const { id, fld_qty } of records) { … }
+const a = 1, b = 2;
+```
+
+Object and array patterns work on `const`, `let`, and `for-of`, with rename, string-literal keys,
+array holes (`const [head, , third] = records;`), and defaults. A default lowers to `coalesce`,
+so it fires on **null** as well as undefined. The right-hand side must be **read-shaped** — a
+root, a step output, or a binding; compute first, then destructure (`const [a] = [1, 2];` is
+rejected). Nested patterns and rest (`...rest`) are not supported.
+
+### Top-level `function` declarations
+
+```js
+const q = await query_records({ table_id: "tbl_lines", filters: { … } });
+
+function lineTotal(l = {}) { return l.data["fld_qty"] * l.data["fld_price"]; }
+
+const subtotal = sumBy(q.records, (l) => lineTotal(l));
+```
+
+A single-expression helper, **top level only**, inlined at every call site.
+
+- **Every parameter needs a default.** The subset has no type annotations, so the default is what
+  makes the parameter's type inferable; a bare parameter is rejected at parse.
+- The body is exactly one `return <expr>;` and sees only its own parameters, helpers, and the
+  reserved roots — never the caller's bindings, and never `index` (it is loop-local, so an
+  inlined body would mean something different at each call site).
+- A call may precede the declaration (declarations are collected first). Recursion, the method
+  form (`x.fn()`), a bare reference (`const g = fn`), a name that shadows a helper/tool/reserved
+  root, and a declaration that is **never called** are all rejected.
+- An omitted argument uses the default; a provided one wins outright (presence is syntactic —
+  unlike a destructuring default, there is no null guard here).
+- **A parameter you read a property off must be handed a record or a binding**, not a computed
+  value: `lineTotal({ qty: 1, price: 2 })` is rejected because inlining would splice a path onto
+  an object literal. Bind it first (`const l = { … };` then `lineTotal(l)`), or pass a row.
+
+**A declared `function` does not survive a pull.** Inlining erases it: `pull` returns the body
+repeated at each call site and no `function` at all. Reach for one when the *saved* logic is what
+matters, and expect to re-extract it if you edit the pulled source.
+
+### Round-tripping
+
+`pull → set` is a fixed point on the stored tree, not on your text. A pulled body prints the
+canonical form — `concat` for a spread, `merge` for an object spread, `{x: x}` for shorthand,
+`toString`/`lower` for a cast or a method call, the arrow spelling for either callback form, and
+the inlined body at each call site of a declared `function`. `?.` and `??` re-sugar, and a
+tool-result destructure prints back as the destructuring statement (`const { records } = await
+query_records({…});`, with renames and defaults intact); where a `?.` guard lands mid-path it
+prints as the explicit `isNull(…) ? null : …` ternary, which re-parses to the same tree.
+
+## Helpers
+
+Helpers are the only callable things an expression may reach — a tool is never callable from an
+expression. **The call form always works.** The method form is lowered to it (`x.trim()` →
+`trim(x)`; `x?.trim()` null-guards the receiver), but only for the names that are *also* real JS
+methods — `trim`, `toUpperCase`, `toLowerCase`, `replace`, `replaceAll`, `split`, `join`,
+`substring`, `padStart`, `padEnd`, `startsWith`, `endsWith`, `includes`, `slice`, `at`, `concat`,
+`reverse`, `map`, `filter`, `find`, `some`, `every`, `reduce`, `toFixed`, `toString`. A
+helper-only method — `arr.size()`, `s.upper()`, `n.round()`, `d.addDays(1)` — is **rejected at
+save** with the call form to write instead (`size(arr)`). `.length` is a property, not a method:
+write `x.length` (no parentheses) or `length(x)`. Naming an unknown helper fails the save with the
+full menu by category, so a miss is one informed retry.
+
+| Category | Helpers |
+|---|---|
+| **Type / null** | `isNull`, `isNotNull`, `isEmpty`, `isString`, `isNumber`, `isBoolean`, `isArray`, `isObject`, `coalesce`, `toNumber`, `toString`, `typeOf`, `parseJson`, `toJson` |
+| **Array** | `size`, `first`, `requireFirst`, `last`, `nth`, `at`, `slice`, `includes`, `filter`, `find`, `some`, `every`, `pluck`, `sortBy`, `groupBy`, `countBy`, `unique`, `uniqueBy`, `compact`, `flatten`, `reverse`, `concat`, `difference`, `differenceBy`, `intersection`, `intersectionBy`, `list`, `range`, `reduce` |
+| **Number** | `sum`, `sumBy`, `mean`, `meanBy`, `min`, `max`, `minBy`, `maxBy`, `round`, `ceil`, `floor`, `abs`, `mod`, `pow`, `sqrt`, `clamp`, `percentage` |
+| **String** | `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`, `replaceAll`, `substring`, `length`, `split`, `join`, `padStart`, `padEnd`, `formatNumber`, `numberToWords` |
+| **Object** | `keys`, `values`, `entries`, `get`, `pick`, `omit`, `merge`, `nonNullKeys` |
+| **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_…"])` |
+
+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)`.
+`sortBy(arr, keyOrFn, "asc" | "desc")`. `formatNumber(x, decimals)`. `get(obj, "a.b", fallback)`.
+Exact declarations reach you through the generated `.lotics/workflows/<alias>.globals.d.ts` —
+open it rather than guessing an arity.
+
+### Callbacks
+
+`filter`, `find`, `some`, `every`, `pluck`, `sortBy`, `sumBy`, `meanBy`, `minBy`, `maxBy`,
+`groupBy`, `countBy`, `uniqueBy`, `differenceBy`, `intersectionBy`, and `reduce` take a callback.
+Everything else does not — a lambda anywhere else is rejected.
+
+- Both spellings lower to the same node: `(x) => <expr>`, `(x) => { return <expr>; }`, and
+  `function (x) { return <expr>; }`. A multi-statement body, `async`, a generator, and a named
+  function expression are rejected. Fold branches into one expression (a ternary).
+- Parameters are plain identifiers, positional per item — `(item, idx) => …`; `reduce` gets
+  `(acc, item, idx)`. No destructuring or defaults in a lambda parameter list.
+- A body may read the reserved roots, step outputs, `let` bindings, enclosing `for-of` binds, and
+  an enclosing lambda's parameters. Parameter names must be unique across the nesting — a name
+  already bound in scope is rejected.
+- `reduce` is callback-only and its **initial value is required** (it is what gives the
+  accumulator a type).
+- Most of these also accept a **path-string** form instead of a callback, resolved with `get`
+  semantics against each item: `filter(lines, "status", "open")`, `sumBy(lines, "amount")`,
+  `sortBy(lines, "due_on", "desc")`. On a `query_records` result the items are
+  `{ id, data }`, so the path is `"data.fld_amount"` — the callback form
+  (`sumBy(rows, (r) => r.data["fld_amount"])`) usually reads better there.
+
+### Dates are null-safe, which the types make you handle
+
+Date fields are `string | null`. The arithmetic, difference, and parse helpers **return null** on
+a null or empty input, and they are *declared* that way — so save-time TypeScript forces the
+guard rather than letting an empty cell crash at run time:
+
+```js
+const overdue = (differenceInCalendarDays(now(), record["fld_due"]) ?? 0) > 30;
+```
+
+A `formatDate(…)` call with a **literal** format string is probed against the real formatter at
+save, so a bad token (`YYYY`, `DD`) blocks the save with guidance. A computed format string stays
+a run-time concern.
+
+String ordering in `sortBy` / `minBy` / `maxBy` is `en-US`-pinned for reproducibility, which can
+differ from `<` / `>` (code-unit order) and from the database's collation.
+
+## Writing records
+
+`update_records` carries four composable surfaces. A field may appear in **at most one** of them.
+
+| Surface | Shape | Effect |
+|---|---|---|
+| `set` | `{ fld_x: value }` | write the whole value. `null` **clears** the field |
+| `set_skip_null` | `{ fld_x: value }` | same shape, but `null`/`undefined` entries are **dropped** — absent means "leave unchanged" |
+| `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 |
+
+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.
+
+`set_skip_null` is what turns a bag of optional workflow inputs into a diff-write without a guard
+per field; naming the same field in both `set` and `set_skip_null` is an error, and an
+all-dropped `set_skip_null` with no other surface is a no-op (no records touched, no
+`before_update` hooks). Why diffs and not snapshots, plus locked records and the
+`request_locked_record_change` path: [mutations](./mutations.md#diff-before-update--send-only-what-changed).
+
+Value shapes, which the generated types enforce exactly:
+
+| Field | Read | Write |
+|---|---|---|
+| single `select` | one `opt_*` key, or `null` | the key: `fld_status: "opt_open"` |
+| multi `select` | array of `opt_*` keys | array: `fld_tags: ["opt_urgent"]` |
+| single `select_member` | one member id, or `null` | the id |
+| multi `select_member` | array of member ids | array |
+| `select_record_link` | array of linked-record handles — one hop of `[0]["fld_x"]` descent | array of ids: `fld_customer: [customer.id]` — never a record object |
+| `files` | array of file refs | array of file ids |
+
+Ids are **branded** on the write side: a member id types as `MemberId`, a file id as `FileId`, a
+linked record id as `RecordId<"tbl_…">`. They come out branded from a record read (`customer.id`)
+or from a workflow input declared `member` / `file` / `record_link` — a `rec_*` string carried in
+a plain `text` input does *not* type-check into a link field, so declare the input for what it is.
+
+A link **read** is not an id array either, so it does not feed straight back:
+`set: { fld_link: record["fld_link"] }` is rejected ("write an ID array, e.g. [x.id]") — and
+`prev_record["fld_link"]` is the same read, so the same rejection. The one id-shaped surface is
+the **diff**: `changes["fld_link"]?.next_value` / `?.prev_value` are plain id arrays (a diff value
+has nowhere to attach a fetch, so it cannot descend either), and they feed `set:` directly.
+Everywhere else, write `[x.id]`.
+
+### Authorizing the caller
+
+A workflow runs under the **app owner's** authority, so its own principal tells you nothing about
+who pressed the button. `runtime.triggered_by_member_id` is that person (null for a system
+trigger or an anonymous public caller), and `current_member_in_any_group(["grp_…"])` authorizes
+them by group. It fails closed — unknown group, deleted group, or no triggering member → `false`
+— and `grp_` literals are validated at save.
+
+```js
+if (!current_member_in_any_group(["grp_managers"])) {
+  return({ status: "error", message: "Only managers can approve this." });
+}
+```
+
+Full model, including what a public app must never expose: [security](./security.md).
+
+## Traps
+
+The rules that are easy to get wrong because the failing code looks correct.
+
+- **Link read/write asymmetry, and the materialized-array cliff.** Descent works only on one
+  unbroken path from a record read. `const ids = record["fld_link"]; ids[0]["fld_name"]`
+  type-checks **clean** and throws at run time — `ids[0]` is a bare id string, and the type it
+  kept says otherwise. Write links as id arrays.
+- **You cannot `for-of` a link field.** `for (const x of record["fld_link"])` is **rejected at
+  save**: a `for-of` has no `[index]` for the fetch to attach to, so the loop would bind bare
+  `rec_*` ids. Read one linked record as a path (`record["fld_link"][0]["fld_x"]`), or
+  `query_records` the linked table and iterate its `records`. Iterating a link field on a row you
+  already descended into (`record["fld_a"][0]["fld_b"]`) is fine — those *are* ids, so
+  `get_record` each one.
+- **`create_records` ids are not reusable downstream.** Storage-commit timing makes the returned
+  `record_ids` array unreliable for a follow-up foreign-key write, and the lint **rejects**
+  `created.record_ids[0]`. Re-query the table by a unique field you just wrote, and use that.
+- **`get_record` needs a literal `table_id` to narrow.** Without it, `.data` degrades to a union
+  of every table and no field read type-checks. `table_id` stays optional at run time; this is a
+  save-time typing requirement.
+- **Date helpers return null.** Guard with `?? 0` before comparing or writing (above).
+- **Waits are disallowed inside any loop body** — `for-of`, `while`, `do…while`, and a c-`for`'s
+  init/update included. Resume re-enters *after* the whole loop, so a wait inside would run
+  iteration 0 and silently skip every remaining iteration and its mutations. Move the wait out,
+  or split the loop into separately triggered runs.
+- **Waits and `agent` steps are disallowed in `before_*` table workflows.** Those run inside the
+  mutation pipeline and must complete synchronously; an LLM loop cannot return an accept/reject
+  verdict in time.
+- **String contexts coerce to display text.** A read inside a template or a string-typed argument
+  renders the *label*; everywhere else it is the raw key. So
+  `` `Status: ${record["fld_status"]}` `` prints "Done" while
+  `record["fld_status"] == "opt_done"` compares keys — both correct, and neither substitutes for
+  the other. A change-diff read (`changes["fld_status"]?.next_value`) behaves exactly like the
+  same field read off the record.
+- **Multi-select `==` quietly desugars.** On a multi-select field,
+  `record["fld_tags"] == "opt_urgent"` rewrites to `includes(…)` at save. Either spelling is
+  fine — but a `switch` on a multi-select discriminant is **rejected**, because its value is an
+  array and no string `case` could ever match. Use `if (includes(…))` branches. `switch` cases
+  must be string literals, each in its own `{ }` block; there is no fallthrough, and a case on a
+  single-select discriminant is option-key-validated.
+- **`let` survives a wait, so its values must survive JSON.** The binding stack is snapshotted at
+  the pause and hydrated on resume — no Dates, functions, or Maps in a `let` initializer.
+- **An empty accumulator can't infer its element type.** `let xs = []` then
+  `xs = concat(xs, someArray)` fails to typecheck; appending a whole *array* has no `push`
+  spelling. Start that binding from the first array instead of seeding it `[]`. Appending single
+  **items** (`xs.push(item)`) works on a bare `[]` seed.
+- **A mutation on the trigger table of an `after_*` workflow can re-trigger itself** — a lint
+  warning, not an error. Gate it on `trigger.change_origin.type == "member"` (the originating
+  write's origin). Not `runtime.change_origin`: that is the execution's own origin, always
+  `table_workflow` here, so it discriminates nothing.
+
+## The bright line
+
+Three invariants make the engine safe, and nothing crosses them: an expression computes a value
+but **cannot call a tool**; every callee is **statically named** so save-time analysis can extract
+table and file ids; evaluation is **deterministic and pure**. So these are boundaries, not gaps:
+
+`Math.random()`, `Date.now()`, `new Date()`, `new` at all (non-deterministic) · regex literals
+(no engine, and ReDoS) · functions as values — a function passed, returned, or bound to a name
+(`const f = (x) => …`) · recursion · `throw` · `import` / `export` · classes · `for-in` ·
+computed property keys · loops or assignment inside an expression · `await` anywhere but a step.
+
+The two `function` forms the subset *does* accept do not cross the line: a callback becomes a
+lambda node, a declaration is inlined — neither survives to run time as a value.
+
+The substitutes: a `bind` step for a value used twice, a top-level `function` for logic used
+twice, a `for-of` step for repetition, `reduce` for a fold, and a separate workflow for anything
+genuinely recursive.
+
+## The check loop
+
+`lotics app workflow check [alias]` runs the server's **own** parse and type passes locally: the
+same subset parser, the same generated `.d.ts` and envelope, the same compiler options, one
+isolated program per alias. **Green means pushable and red means real** — do not push through a
+red check.
+
+Order matters. A subset rejection is reported *alone* and the compiler is skipped, because a body
+the parser refuses never reaches the type checker on the server anyway. Diagnostics carry
+`<file>:<line>:<col>` at the physical position in `src/workflows/<alias>.ts`.
+
+What only the **server** can decide, so `check` stays green and `set` may still refuse:
+
+- whether an identifier is a **registered tool** (the CLI ships no tool registry), and whether a
+  tool's kwargs are the right ones;
+- **field, option, table, and group resolution** — a `fld_*` that doesn't exist, an `opt_*` that
+  isn't one of that field's options, a display name where a key belongs;
+- **`switch` case validation** against a single-select's options, and the multi-select rejection;
+- the **literal `formatDate` format probe**;
+- **wait inside a loop**, and the `before_*` restrictions on waits and `agent` steps;
+- the **lint** — `create_records` id reuse (an error), possible self-retrigger, deep link chains,
+  a button action with no `validate` guard (warnings).
+
+There is no separate verify endpoint: the loop is `set` → read the returned diagnostics → fix →
+`set`. Diagnostics arrive **batched** — independent errors across the whole body come back in one
+round trip, not one per fix — and raw TypeScript shape errors are rewritten into field-naming,
+fix-stating messages before you see them.
+
+## A worked body
+
+An app action that creates an order after checking for a duplicate, then returns the new id.
+
+```js
+const i = trigger.app_workflow.inputs;
+
+const dup = await query_records({
+  table_id: "tbl_orders",
+  filters: {
+    node_type: "condition",
+    field_key: "fld_order_code",
+    operator: "equals",
+    value: i.order_code,
+  },
+});
+
+validate({ checks: [{
+  fail_when: size(dup.records) > 0,
+  field_key: "fld_order_code",
+  message: `Order code ${i.order_code} already exists.`,
+}]});
+
+await create_records({
+  table_id: "tbl_orders",
+  records: [{
+    fld_order_code: i.order_code,
+    fld_customer: [i.customer_id],
+    fld_status: "opt_open",
+    fld_opened_on: formatDate(now(), "yyyy-MM-dd"),
+    fld_note: i.note,          // omitted optional input → undefined → key dropped
+  }],
+});
+
+// create_records ids are not reusable — re-read by the unique code we just wrote.
+const created = await query_records({
+  table_id: "tbl_orders",
+  filters: {
+    node_type: "condition",
+    field_key: "fld_order_code",
+    operator: "equals",
+    value: i.order_code,
+  },
+});
+
+// A path can't hang off a helper call — bind it, then read.
+const top = requireFirst(created.records);
+
+return({
+  status: "success",
+  message: "Order created.",
+  data: { order_id: top.id },
+});
+```

package/package.json

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