@lotics/app-sdk 0.100.1 → 0.101.1

package/docs/workflows.md

@@ -1,11 +1,9 @@
 # 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 grammar of a **workflow body**: what `set_app_workflow` takes as an alias's `source`, the
+JS subset that is accepted, and the rules that decide whether a body saves.
+[mutations](./mutations.md) owns the *call* side; this document owns everything between the
+braces.
 
 ## The mental model
 
@@ -19,8 +17,8 @@ engine, no `eval`, no sandbox. Four consequences shape everything below:
 - **A successful save may still return `warnings[]`** — advisory lint that does not block.
   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).
+  stored form. The stored tree renders back to source when it is read (`get_app_workflow`), so a
+  read 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
@@ -33,29 +31,13 @@ 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:
+A body is the app's, stored on the server and bound to an alias: `set_app_workflow` takes the
+alias, the body's `source`, and the alias's `inputs` (leave `outputs` off to let the body's
+`return({ data })` derive it). The server verifies the body and the write lands live, as a new
+version of the app; `get_app_workflow` reads it back, and `rollback_app` returns the app to a
+version before it. Input declaration vocabulary and validation:
 [mutations](./mutations.md#declaring-workflow-inputs).
 
-**Adding an input to an alias that is already bound reverses that order.** `codegen` types a
-*registered* alias from the server's **bound** schema — the manifest declaration is only the
-fallback for an alias the server has never seen — so a newly-declared input is absent from the
-local globals and `check` rejects every read of it, however correct the body is. `set` pushes the
-manifest's `inputs` with the body and the server verifies against *those*, so the working order
-is `set` → `codegen` → `check`.
-
 An app workflow body carries **no trigger declaration** — the binding supplies the trigger
 context. A stray `on({ … })` line is rejected.
 
@@ -74,17 +56,16 @@ compile-time "cannot find name", not a runtime `undefined`.
 | `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 — always the **innermost** loop's. To use an outer loop's index in a nested body, bind it in the outer one (`const outerIdx = index;`) and read that |
 | `<bind_name>` | inside a `for-of` body | the current item. Each loop keeps its own, so a nested body reads the outer loop's item by its own bind name |
-| `<step_id>` | after the step | that step's output (`rows.records`, `approval.status`, …) |
+| `<name>` | its block, after the declaration | a `const` — a step's output (`rows.records`, `approval.status`, …) or a bound value |
 | `<let_name>` | its block | a mutable `let` binding |
 | `<param>` | inside a helper callback | that lambda's parameter |
+| `(await <tool>({…}))` | anywhere the call runs unconditionally | that call's output, read in place (see *`await` inside a statement*) |
 
-`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.
+`record`, `prev_record` and `changes` are the **canonical** roots. `trigger.data`,
+`trigger.prev_data` and `trigger.changes` are accepted and lower onto them, so 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
+A body bound to an app alias 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.
 
@@ -99,9 +80,6 @@ origin, and spans every write path: `member`, `chat_agent`, `app_workflow`, …)
 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 |
@@ -111,10 +89,20 @@ executes under — see [security](./security.md) and `current_member_in_any_grou
 | `linked(record["fld_link"])[0]["fld_name"]` | fetch the linked rows and read a field off one — see below |
 | `.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`). `linked(...)` is the exception because it is grammar rather than
-a helper — the path continues through it.
+**A path starts at a root, a name, or an awaited tool call** —
+`(await get_record({ … })).data["fld_x"]` reads the call's output in place. It cannot hang off a
+helper call: `first(rows.records).id` is refused. Bind the call (`const top = first(rows.records);`
+then `top.id`) or index the array directly (`rows.records[0].id`). `linked(...)` is the exception
+because it is grammar rather than a helper — the path continues through it.
+
+**A record reads in its declared shape, however it reached you.** Every row a records tool
+returns, the trigger record and its diff, and every row `linked(...)` fetches arrive shaped as the
+generated types declare them: a single select as its option key or `null`, one member as its id
+or `null`, a link as its ids. So a row read through a `let`, a ternary, a callback parameter, a
+helper result, a table id held in a variable, or a value that waited through a pause reads the
+same as one read straight off the call. (A record *tool* run from the CLI or chat serves what is
+stored — a single select as `["opt_x"]` — so take a field's shape from the generated types, never
+from a transcript.)
 
 **A link field reads as an array of ids, in every spelling.** `order.data["fld_link"]` is
 `RecordId<"tbl_…">[]` whether you read it on a path, bind it to a `const`, take it as a `for-of`
@@ -132,8 +120,8 @@ row `P[i]` names.
 
 The argument is a path ending on a link field, off anything record-shaped: `record` /
 `prev_record`, a `for-of` item, a lambda parameter, a `let` binding, or a `get_record` /
-`query_records` output (that one resolves its table only when the call passed a **literal**
-`table_id`, which is what lets the server validate the far field at save). Guard **inside** the
+`query_records` output. The server checks the far field at save only where it can name the table
+before the run — a call with a **literal** `table_id` — and the fetch works either way. Guard **inside** the
 argument — `linked(record?.["fld_link"])[0]` — never on the call: `linked(P)?.[i]` is rejected,
 because the call always returns an array and the guard could never fire. Two more rejections:
 `const ids = record["fld_link"]; linked(ids)`, since the field name comes from the argument's last
@@ -148,10 +136,10 @@ 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, with output | `const <id> = await <tool>({ …kwargs });` — or `let x = await …`, `x = await …` |
 | Tool call, no output | `await <tool>({ …kwargs });` |
 | Bind (compute once, reuse many) | `const <id> = <expression>;` |
-| Mutable binding | `let x = <expr>;` then `x = …`, `x += …`, `x++` |
+| Mutable binding | `let x = <expr>;` then `x = …`, `x += …`, `x++`, `x ??= …`, `o.a.b = …`, `xs.push(…)` |
 | Branch | `if (<expr>) { … } else if (<expr>) { … } else { … }` |
 | Switch | `switch (<expr>) { case "X": { … } default: { … } }` |
 | Iterate | `for (const item of <expr>) { … }` |
@@ -169,6 +157,33 @@ The body is a sequence of statements, each of which maps 1:1 onto a stored step.
 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.
 
+### `await` inside a statement
+
+A tool call is always a step of its own, so an `await` is accepted wherever the statement around
+it runs the call **every time it runs**: the call becomes a step placed just before the
+statement, and its output is read where you wrote the `await`, in JavaScript's evaluation order.
+
+```js
+let supplier = null;
+if (!isNull(i.supplier_id)) {
+  supplier = await get_record({ table_id: "tbl_suppliers", record_id: i.supplier_id });
+}
+const n = size((await query_records({ table_id: "tbl_orders" })).records);
+if ((await get_record({ table_id: "tbl_orders", record_id: i.id })).data["fld_paid"]) { … }
+const owner = i.owner_id ? await get_record({ table_id: "tbl_people", record_id: i.owner_id }) : null;
+```
+
+That covers an assignment, a `let` initializer, a helper or tool argument, an `if` or `switch`
+test, a `return` value, a `for-of` iterable, a template, and a counter loop's init. A ternary
+that awaits in a branch is accepted when it is the **whole** value of a `const`, `let` or
+assignment — it is stored as the `if` it means.
+
+An `await` that would run on some paths only is refused, with the `if` form to write instead:
+inside `&&`, `||`, `??`, `??=` / `||=` / `&&=`, `?.`, a ternary nested in a larger expression, a
+destructuring default, a `validate` check, a `while` / `do…while` test, and a counter loop's test
+or update (those run on every pass — put the call in the body). `wait` and `wait_for_event` have
+no value, so they stay statements.
+
 ### Step ids, names, and comments
 
 The binding name on `const x = await tool({…})` **becomes the step id**, which is how later
@@ -184,14 +199,18 @@ the step's description, which is what the execution log shows.
 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,
-`linked`, 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.
+**Names are block-scoped, as in JavaScript.** A `const`, a `let`, a `for-of` item, a destructured
+name and a `catch (e)` binding live in the block that declares them: two sibling blocks may each
+declare `res`, an inner block may shadow an outer `res`, and a name read outside its block is an
+unknown identifier. A lambda parameter shadows an outer name of the same spelling inside its
+body. Each binding is stored under its own step id; a read prints the names you wrote.
+
+**A local may take a helper's name** — `const size = 3;` is fine. While it is in scope, calling
+`size(…)` is refused, as TypeScript refuses it: rename the local to call the helper. The method
+and namespace forms (`xs.includes(v)`, `Math.max(…)`) still reach the helper. A name may not
+take a tool's name, a reserved root (`record`, `trigger`, `runtime`, `index`, …), `linked`, or a
+declared function's name, and `_s` followed by digits is the parser's own spelling for a hidden
+step, so no binding may use it.
 
 ### `return` — the envelope
 
@@ -205,9 +224,10 @@ return({ status: "success", message: "Order created.", data: { total: subtotal }
   save from its inferred type. Full contract: [mutations](./mutations.md) § "Structured results".
 - `field_errors` maps a key to a message and reaches the app on `result.field_errors`, so a
   form draws each one against the control it names. **The key names the control on the surface
-  that renders it**: for an app workflow that is the alias's declared INPUT name, for a
-  table-triggered one it is the record's `fld_` field key. The runtime keys the map by whatever
-  string you write, so a key naming neither reaches the dialog and lands on nothing.
+  that renders it**: an app's form places it under the control for that declared INPUT name, or
+  under the control that writes that `fld_` field; the record editor behind a table-triggered
+  workflow places it under that `fld_` field. The runtime keys the map by whatever string you
+  write, so a key naming no control reaches the dialog and lands on nothing.
 - 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)).
@@ -227,12 +247,20 @@ failing messages joined — cleanly, not as a crash: it is control flow, so **`t
 not catch it** (nor `return`).
 
 `field_key` is optional, a string literal, and carries the same key `return({ field_errors })`
-does: **the control the message belongs to, on the surface that renders it** — an app workflow's
-declared INPUT name (`order_code`, the key under `lotics.workflows.<alias>.inputs`), a
-table-triggered workflow's `fld_` field key. Each failing check that names one contributes an
-entry to `field_errors`, so the app's form marks that control instead of only the dialog.
-A key naming neither is refused when the body is SAVED — by `lotics app workflow set`, by an
-agent binding one, by a table workflow's save — and by `lotics app workflow check` before that.
+does: **the control the message belongs to, on the surface that renders it**. Each failing check
+that names one contributes an entry to `field_errors`, so the form marks that control instead of
+only the dialog. What it may name depends on who renders the refusal:
+
+| Workflow | `field_key` may name |
+|---|---|
+| app workflow | a declared INPUT name (`order_code`, a key of the binding's `inputs`), or the `fld_` key of a field on a table the body names as a literal (a `table_id: "tbl_…"`, or a `const` holding one) |
+| table-triggered (lifecycle, button) | the `fld_` key of a field on the trigger table |
+| recordless automation (schedule, webhook, email) | anything — nothing renders it, so nothing checks it |
+
+An app workflow whose alias declares no inputs leaves input-shaped keys unchecked, so a body can
+be written before its declaration. A key outside its row is refused when the body is SAVED — by
+`set_app_workflow`, by an agent binding one, by a table workflow's save — and by a
+`verify_only` call before that. `return({ field_errors })` keys are not checked.
 
 ### `wait_for_approval` — the one wait worth binding
 
@@ -321,8 +349,13 @@ for (const line of trigger.app_workflow.inputs.lines) {
 Precedence is JS's: `? :`, `||`, `??`, `&&`, `== != === !==`, `< <= > >=`, `+ -`, `* / %`,
 prefix `!` and `-`. Both equality forms work as in JS — `==`/`!=` loose, `===`/`!==` strict.
 
-Not supported: `**`, bitwise operators, `||=` / `&&=` / `??=`, `in`, `typeof`, `instanceof`,
-`delete`, `void`.
+Not supported: `**`, bitwise operators, `in`, `typeof`, `instanceof`, `delete`, `void`.
+`??=`, `||=` and `&&=` are statements (see *The sugar list*), not expressions.
+
+**`undefined` is `null`.** The name is accepted and means the same value, so `x == undefined` is
+`x == null`. `===` and `!==` against `undefined` are refused (`strict_undefined`): they cannot tell
+a missing key from a null one. Test either with `isNull(x)`, and whether a key was sent with
+`includes(keys(o), "k")` (see *Writing records*).
 
 **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
@@ -330,9 +363,8 @@ 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.
+Each of these is accepted and lowered to a canonical stored form at save, which is why a pulled
+body does not look like what you typed.
 
 | You write | It stores as |
 |---|---|
@@ -354,14 +386,27 @@ typed.
 | `[...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 |
+| `undefined` | `null` |
+| `xs.push(a, b);` | `xs = concat(xs, [a, b])` — statement form |
+| `o.a.items.push(v);` | `o = merge(o, { a: merge(o.a, { items: concat(o.a.items, [v]) }) })` |
+| `o.a.b = v;` | `o = merge(o, { a: merge(o.a, { b: v }) })` — also `o.a.b += v`, `o.n++` |
 | `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 |
+| `x ??= v`, `x \|\|= v`, `x &&= v` | `x = coalesce(x, v)`, `x = x \|\| v`, `x = x && v` |
+| a `const` the body pushes to, or assigns a key of | a `let` (reassigning the `const` itself is refused, as in JavaScript) |
+| `x = await t({…});`, `let x = await t({…});` | the call as its own step, then the assignment |
+| `const x = c ? await t({…}) : d;` | `let x = null; if (c) { x = await t({…}); } else { x = d; }` |
+| `const { records } = await query_records({…});` | one bind per name off a synthetic step id (also `let { … } = await …`) |
 | `function (x) { return e; }` in callback position | the same lambda node as `(x) => e` |
+| a filter node without `node_type` | the one shape its keys name: `field_key`/`operator`/`value` a condition, `logic`/`children` a group, `path`/`condition` a traversal |
 
 `parseInt` is **rejected** rather than aliased: `toNumber` has `parseFloat` semantics and would
 silently drop the radix. Parse with `toNumber(x)`, then `floor` / `ceil` / `round`.
 
+A mutation lands on a name the body declared: a key assignment or a push names its path with
+written keys (`o[k] = v` with a computed `k` is refused), and a loop item is read-only — copy it
+into a `let` first. Arrays and objects stay immutable underneath; each form rebuilds the value
+and reassigns the name.
+
 **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
@@ -408,19 +453,23 @@ A single-expression helper, **top level only**, inlined at every call site.
   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.
+**A declared `function` does not survive a read.** Inlining erases it: `get_app_workflow` 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 source read back.
 
 ### Round-tripping
 
-`pull → set` is a fixed point on the stored tree, not on your text. A pulled body prints the
+`get → set` is a fixed point on the stored tree, not on your text. A body read back 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.
+`toString`/`lower` for a cast or a method call, the arrow spelling for either callback form,
+`null` for `undefined`, `let` for a `const` the body mutates, 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. Awaits print where you wrote them, a ternary that
+awaits prints as the ternary, pushes, key assignments and `??=` print as written, and each
+block-scoped name prints as its own spelling. A local that shadows a helper whose call has no
+other spelling is renamed on read, with a `// id:` line keeping its step id.
 
 ## Helpers
 
@@ -449,17 +498,15 @@ full menu by category, so a miss is one informed retry.
 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
+question — it covers `null`, `undefined`, `""` and `[]`. 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)`.
 `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.
+Exact declarations are the server's; a wrong arity is refused at save with the signature it
+expected, so read that message rather than guessing.
 
 ### Callbacks
 
@@ -472,9 +519,10 @@ Everything else does not — a lambda anywhere else is rejected.
   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.
+- A body may read the reserved roots, the names in scope, enclosing `for-of` items, and an
+  enclosing lambda's parameters. A parameter spelled like an outer name shadows it inside the body.
+- A callback's item reads in its declared shape (see *Path access*), so a callback over rows
+  reads `r.data["fld_status"]` as the option key whatever the rows came from.
 - `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`
@@ -513,12 +561,10 @@ differ from `<` / `>` (code-unit order) and from the database's collation.
 | `field_edits` | `[{ field, op, value }]` | the multi-value ops with the field named by a **string expression** — the only way to target a field chosen at run time. `increment` has no value-form: its payload is a scalar, not an item list |
 
 `add_to`, `remove_from` and `increment` are RELATIVE: the server resolves them against the record
-as it stands when the write lands, inside the lock it already takes. Two runs changing one field at
-the same time therefore each keep their effect — which reading the field and writing the result back
-through `set` does not, since both fold onto the value they read and the later write drops the
-earlier, both reporting success. On a stock count that is a sale that vanishes. Parallel runs are
-ordinary (a trigger firing twice, an agent emitting two calls in one step), so reach for the ops
-rather than a read-modify-write whenever the workflow is CHANGING a field by an amount rather than
+as it stands when the write lands, inside the lock it already takes, so two runs changing one field
+at once each keep their effect — where a read-modify-write through `set` drops the earlier, both
+reporting success. Parallel runs are ordinary (a trigger firing twice, an agent emitting two calls
+in one step), so reach for the ops whenever the workflow CHANGES a field by an amount rather than
 stating its value.
 
 `increment` counts an empty or unset field as 0, so a first decrement leaves a negative — oversold,
@@ -526,8 +572,7 @@ and visibly so. It is rejected on formula, rollup, lookup and autonumber fields:
 their own definition, so change what they aggregate instead.
 
 A **different** delta per record is per-record mode with `row_op: "increment"` — every row value is
-read as a delta rather than a value to write. That is the shape a stock move needs, since each item
-moves by its own quantity:
+read as a delta rather than a value to write:
 
 ```ts
 await update_records({
@@ -539,9 +584,6 @@ await update_records({
 });
 ```
 
-It also removes the read: the deltas are what the workflow already computed, so there is nothing to
-look up first.
-
 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.
@@ -575,13 +617,9 @@ if (includes(keys(i), "phone")) {   // NOT `isNull(i.phone)` — that swallows t
 ```
 
 An omitted input carries no key at all and a cleared one carries the key with `null`, so presence
-is the only test that separates them. It has to be `keys` rather than a comparison against
-`undefined`: the expression subset has no `undefined` identifier, and a body naming it fails to
-save with `Unknown identifier "undefined"`.
-
-`""` is never a clear on any surface: an HTML input emits it for "the user skipped this", so the
-validator coerces it to omitted before the body runs. Reaching for `""` to blank a field fails
-silently — the write reports success and the old value stays. Send `null`.
+is the only test that separates them — and it has to be `keys`: a body reads `undefined` as `null`,
+so `i.phone === undefined` is refused rather than read as a test of whether the input was sent.
+`""` is never a clear: the validator coerces it to omitted before the body runs.
 
 Value shapes, which the generated types enforce exactly:
 
@@ -627,24 +665,15 @@ if (i.undo) {
 ```
 
 There is no version to restore a cell from, so prove it before anyone can call
-it: `lotics app workflow run <alias>` the same input twice, and confirm the
-second run changed nothing.
+it: `run_app_workflow` the same input twice, and confirm the second run changed
+nothing.
 
 ### 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).
+A workflow runs under the **app owner's** authority, so the person who pressed the button is
+`runtime.triggered_by_member_id`, authorized by group with `current_member_in_any_group(["grp_…"])`
+— fail-closed, its `grp_` literals validated at save
+([security](./security.md#gating-privileged-writes-current_member_in_any_group)).
 
 ## Every `await` is a round trip
 
@@ -691,10 +720,9 @@ await create_records({ records: rows, … });
 //   Type 'string' is not assignable to '"opt_bVPEMB" | "opt_nx0KAL" | … | null'.
 ```
 
-`concat` widens a select's option key to `string` the moment it leaves the literal, and the obvious
-repair — `let rows: SomeRecordWrite[] = []` — is rejected by the next pass, because the stored body
-is parsed as a JS subset and type syntax is not in it. The way through is not an annotation: it is
-to let the call site supply the type. Keep the loop for FINDING values and put the writing after it.
+`concat` widens a select's option key to `string` the moment it leaves the literal, and an
+annotation is not in the subset. Let the call site supply the type: keep the loop for FINDING
+values and put the writing after it.
 
 ### Don't buy the same row twice
 
@@ -717,11 +745,9 @@ existed only to feed it, which is usually where the round trips were hiding.
 
 ### Measuring, if you do
 
-`query_workflow_executions` records `started_at` / `completed_at` per run, which is the server's own
-duration with your network and CLI startup excluded. **Run-to-run variance is large** — the same
-body measured twice, minutes apart, can differ by a second — so compare medians of several runs,
-and interleave the two versions rather than measuring one after the other. A single before/after
-pair will happily show an improvement that is only drift.
+`query_workflow_executions` records `started_at` / `completed_at` per run, the server's own
+duration. **Run-to-run variance is large** (a second, minutes apart), so compare medians of several
+interleaved runs, never one before/after pair.
 
 ## Traps
 
@@ -733,9 +759,13 @@ The rules that are easy to get wrong because the failing code looks correct.
 - **`for-of` over a link field iterates ids, over `linked(...)` iterates rows.** Both are legal, so
   pick by what the body needs — `get_record` and a link write take the id, a field read takes the
   row.
-- **`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.
+- **`get_record` needs a literal `table_id` to narrow** — a string literal, or a `const` holding
+  one. 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.
+- **A read the server cannot place before the run gets no save-time help.** Off a row whose
+  table only the run knows (a `let` holding rows of two tables, a `table_id` from an input), a
+  field read still returns the declared shape, but its option literals are not checked at save and
+  a multi-select `==` is not rewritten to `includes(…)` — write `includes(…)` there.
 - **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
@@ -748,8 +778,9 @@ The rules that are easy to get wrong because the failing code looks correct.
   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.
+  the other. It holds on every route a record arrives by — a `let`, a callback parameter, a row
+  from a variable `table_id` — and 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
@@ -781,7 +812,11 @@ table and file ids; evaluation is **deterministic and pure**. So these are bound
 `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.
+computed property keys · loops or assignment inside an expression · an `await` that would run on
+some paths only.
+
+An `await` inside a statement does not cross the first line: the call it names runs as a step of
+its own before the statement, and the expression reads that step's output.
 
 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.
@@ -792,38 +827,22 @@ 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. It is also the *only* local gate on a body: the app project's own `npm run typecheck`
-excludes `src/workflows` (bodies compile against the server's globals, not the app's DOM lib), so
-it never sees one — a fully green app typecheck says nothing about any workflow.
-
-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** — deep link chains, an input the alias declares that this body never reads, and
-  an unguarded `set` in a body that generates a document (all 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,
+`set_app_workflow` with `verify_only: true` gives the verdict a save would, and writes nothing. The
+server runs every check a save runs — the subset parse, the type pass against the alias's
+declared inputs, tool and kwarg resolution, field, option, table and group resolution, `switch`
+case validation, the literal `formatDate` probe, waits in loops, the `before_*` restrictions,
+table reach, the `field_key` rule and the published-API guard. **Green means the save will take
+it, red means real** — do not push through a red check. Lint comes back as warnings, which do not
+fail it.
+
+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.
 
 ### Static green is not a run
 
-`check` and `set` prove parse, types, name resolution, and lint — **none of them evaluates an
-expression**. A body that saves clean can still take the wrong branch, hand a tool a filter it
+`check` and `set` prove parse, types, name resolution, structure, and lint — **none of them
+evaluates an expression**. A body that saves clean can still take the wrong branch, hand a tool a filter it
 rejects, or read a path that is null on real data. The rehearsal for that is `dry_run_workflow`
 (`lotics run dry_run_workflow '<json>'`): pass the `source`, `trigger_type: "app_workflow"`,
 `table_id: null`, the input **values** as `trigger_payload`, and the declared schema as
@@ -836,14 +855,10 @@ recorded, never dispatched**, and nothing is persisted.
 
 **Add `live_reads: true` whenever the body READS.** By default the read-only tools
 (`query_records`, `get_record`, `aggregate_records`) return stubs — an empty result set, a blank
-record — so any branch gated on stored data takes the empty path and the rehearsal quietly proves
-nothing about the branch that matters. A duplicate check finds no duplicate; a lookup that should
-skip because a field is already set doesn't skip. With `live_reads: true` those three dispatch
-against the real workspace under YOUR authority, so the gates are exercised against actual rows
-while writes stay recorded-only. (A table-triggered body gets this from `record_id` + `table_id`,
-which supply the real record as the payload AND turn live reads on; an app workflow has no trigger
-record — its payload is its inputs — so it asks for the reads directly.) Do this before the first
-live run of anything that writes.
+record — so any branch gated on stored data takes the empty path. With `live_reads: true` those
+three dispatch against the real workspace under YOUR authority while writes stay recorded-only. (A
+table-triggered body gets this from `record_id` + `table_id`; an app workflow has no trigger
+record, so it asks 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
@@ -867,7 +882,7 @@ A workflow that files a recording ([mutations](./mutations.md#recording-into-a-w
 declares the platform's `recording` input in exactly this shape, beside its own inputs:
 
 ```jsonc
-// package.json#lotics.workflows.log_visit
+// set_app_workflow { "alias": "log_visit", "inputs": … }
 "inputs": {
   "site": { "type": "record_link", "table_id": "tbl_sites" },
   "recording": { "type": "object", "fields": {
@@ -926,7 +941,7 @@ const dup = await query_records({
 
 validate({ checks: [{
   fail_when: size(dup.records) > 0,
-  // The INPUT name, not the field key: this is what the app's form marks.
+  // The input the form's control sends; the fld_ key of the field it writes works too.
   field_key: "order_code",
   message: `Order code ${i.order_code} already exists.`,
 }]});