@lotics/app-sdk 0.88.2 → 0.89.0

package/AGENTS.md

@@ -18,7 +18,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 four read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`/`useCount` — the last for a number with no rows, sharing the `(alias, params, filter)` count key the paginated hook uses, so a list and a badge over one set buy one count; a count is a full scan and stays its OWN request so rows paint without waiting for it, and `rows.length` is never a count since rows truncate silently at 10,000), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), runtime `sort`/`filter` keys typed against the query's own projection (`AppQueryColumns`, `ColumnKeyOf`), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — **realtime push** (a table one of your queries reads changes and that query refetches within about a second, alias-precise, records-only, host-embedded apps only) — and the fourth source, **this app's own successful write**, which re-reads every mounted query immediately rather than waiting on that push (→ [mutations](./docs/mutations.md)), data discipline, the pagination count as a second full execution (and `total` to suppress it), 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, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
-| [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + link descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
+| [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 + explicit `linked()` 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 verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), 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/workflows.md

@@ -71,7 +71,7 @@ compile-time "cannot find name", not a runtime `undefined`.
 | `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 |
+| `prev_record` | table `*_update` / `*_delete` | the prior record state — same shape as `record` |
 | `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 |
@@ -109,28 +109,39 @@ executes under — see [security](./security.md) and `current_member_in_any_grou
 |---|---|
 | `["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 |
+| `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`).
-
-**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.
+directly (`rows.records[0].id`). `linked(...)` is the exception because it is grammar rather than
+a helper — the path continues through it.
+
+**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`
+item or a lambda parameter, or read it off a diff. An id goes wherever an id is wanted —
+`record_id: ids[0]`, a `record_ids` input, a link write — with no `.id` and no unwrapping.
+
+**To read a linked row's own fields, fetch it: `linked(...)`.**
+`linked(order.data["fld_link"])[0]["fld_name"]` fetches that row and reads a field off it; bare
+`linked(order.data["fld_link"])` is every linked row and is legal wherever an array is — a helper
+argument, a `for-of` iterable, a step input. The fetch is scoped to the run's authority,
+null-tolerant, and cached per execution, but it is never free: one row per fetch, and a second hop
+is a second call (`linked(linked(order.data["fld_a"])[0]["fld_b"])[0]`). A linked row that was
+deleted, or that the run may not read, stays a positional `null`, so `linked(P)[i]` is always the
+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
+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
+member access (`linked(row["fld_link"])` off a bound ROW is fine), and
+`linked(changes["fld_link"]?.next_value)`, since a diff is not a record — read
+`linked(record["fld_link"])` or `linked(prev_record["fld_link"])`, which hold the same ids.
+`linked` is grammar, not a helper: it cannot be shadowed, bound, called as a method, or awaited.
 
 ## Step forms
 
@@ -175,13 +186,13 @@ 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.
+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.
 
 ### `return` — the envelope
 
@@ -571,7 +582,7 @@ Value shapes, which the generated types enforce exactly:
 | 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 |
+| `select_record_link` | array of ids — `linked(...)` fetches the rows | array of ids: `fld_customer: [customer.id]`, or a link read fed straight back |
 | `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
@@ -579,12 +590,12 @@ linked record id as `RecordId<"tbl_…">`. They come out branded from a record r
 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]`.
+A link **read** is an id array, so it feeds straight back: `set: { fld_link: record["fld_link"] }`,
+and the same for `prev_record["fld_link"]` and for a diff's `changes["fld_link"]?.next_value` /
+`?.prev_value`. What does not feed back is a ROW: a link field takes ids, so from rows you already
+hold write `pluck(rows.records, (r) => r.id)`, or `[x.id]` for one. Never route a link read through
+`linked(...)` to get its ids back — it holds them already, and the fetch costs one read per row and
+yields `null` where a row is deleted or unreadable, which the write then rejects.
 
 ### A write that will be re-run
 
@@ -707,19 +718,12 @@ pair will happily show an improvement that is only drift.
 
 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.
+- **`linked(...)` inside a loop body is a fetch per linked row per iteration.** Over 200 rows a
+  `linked` read in the body is 200 fetches; the per-execution cache only helps when the same ids
+  come round again. Hoist it, or `query_records` the linked table once and match on the ids.
+- **`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.
@@ -799,8 +803,8 @@ What only the **server** can decide, so `check` stays green and `set` may still
 - **`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).
+- the **lint** — possible self-retrigger, deep link chains, a button action with no `validate`
+  guard (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
@@ -871,7 +875,7 @@ validate({ checks: [{
   message: `Order code ${i.order_code} already exists.`,
 }]});
 
-await create_records({
+const created = await create_records({
   table_id: "tbl_orders",
   records: [{
     fld_order_code: i.order_code,
@@ -882,23 +886,9 @@ await create_records({
   }],
 });
 
-// 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 },
+  data: { order_id: created.record_ids[0] },
 });
 ```

package/package.json

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