@lotics/app-sdk 0.124.8 → 0.124.9

package/dist/index.js

@@ -7613,7 +7613,11 @@ var TOOL_INPUT_SEMANTICS = {
     // Each entry's {field, op, value} carries a field-key position, but the
     // field is a sibling-dependent runtime value, not a single `table_from`
     // kind — the tool's own resolveSurgicalKeys validates it at execute time.
-    field_edits: { kind: "dynamic" }
+    field_edits: { kind: "dynamic" },
+    // The lock the call leaves, the deleted records it brings back, and the approval it files for a locked one: none holds a field key.
+    locked: { kind: "scalar" },
+    restore: { kind: "scalar" },
+    request_change: { kind: "scalar" }
   },
   create_records: {
     table_id: { kind: "table_ref", rows: "change" },
@@ -7674,21 +7678,11 @@ var TOOL_INPUT_SEMANTICS = {
     as_member: { kind: "scalar" },
     removal: { kind: "table_field_array" }
   },
-  restore_records: {
-    table_id: { kind: "table_ref", rows: "change" },
-    record_ids: { kind: "record_refs" },
-    filters: { kind: "filter_tree", table_from: "table_id" }
-  },
   lock_records: {
     table_id: { kind: "table_ref", rows: "change" },
     record_ids: { kind: "record_refs" },
     filters: { kind: "filter_tree", table_from: "table_id" }
   },
-  unlock_records: {
-    table_id: { kind: "table_ref", rows: "change" },
-    record_ids: { kind: "record_refs" },
-    filters: { kind: "filter_tree", table_from: "table_id" }
-  },
   request_locked_record_change: {
     table_id: { kind: "table_ref", rows: "none" },
     record_id: { kind: "record_ref" },
@@ -7697,18 +7691,6 @@ var TOOL_INPUT_SEMANTICS = {
     changes: { kind: "dynamic" },
     reason: { kind: "text" }
   },
-  // The record names its own table; an entry's id is the trail's.
-  undo_record_change: {
-    record_id: { kind: "record_ref" },
-    entry_id: { kind: "scalar" }
-  },
-  // `table_id` names the table whose rows the undo changes, moves to the trash and brings back; a run's id is the
-  // trail's.
-  undo_record_changes: {
-    table_id: { kind: "table_ref", rows: "remove" },
-    record_ids: { kind: "record_refs" },
-    workflow_execution_id: { kind: "scalar" }
-  },
   // ─── Query surfaces ────────────────────────────────────────────────────
   query_records: {
     table_id: { kind: "table_ref", rows: "none" },
@@ -7724,6 +7706,10 @@ var TOOL_INPUT_SEMANTICS = {
     archived_only: { kind: "scalar" },
     include_timestamps: { kind: "scalar" },
     as_member: { kind: "scalar" },
+    comments: { kind: "scalar" },
+    record_ids: { kind: "record_refs" },
+    // Nested {field_key, operation} shapes and a group_by key: resolved at execute time, as the aggregate tool did.
+    aggregate: { kind: "dynamic" },
     // Each entry pairs its OWN table_id with its OWN filter tree, so the table a
     // filter resolves against is per-element rather than a sibling kwarg — no
     // top-level kind can say that. Opaque to the save-time walker, which is the
@@ -7775,7 +7761,8 @@ var TOOL_INPUT_SEMANTICS = {
     // Keys on the record's own table, which `table_id` names when supplied and
     // the record resolves otherwise — the same position it holds on a query.
     field_keys: { kind: "field_key_refs", table_from: "table_id" },
-    as_member: { kind: "scalar" }
+    as_member: { kind: "scalar" },
+    comments: { kind: "scalar" }
   },
   // ─── Buttons (table-scoped field with action) ─────────────────────────
   press_button: {
@@ -9682,7 +9669,8 @@ async function tableOf(walk, input) {
 async function predictUpdate(walk, input) {
   const table = await tableOf(walk, input);
   const ids = input.record_ids === void 0 ? null : asIds(await attempt(walk, input.record_ids));
-  if (table === null || ids === null || input.filters !== void 0 || input.rows !== void 0 || input.field_edits !== void 0) {
+  const serverDecided = input.restore !== void 0 || input.locked !== void 0 || input.request_change !== void 0;
+  if (table === null || ids === null || serverDecided || input.filters !== void 0 || input.rows !== void 0 || input.field_edits !== void 0) {
     note(walk, { kind: "unknown", table_id: table });
     return;
   }

package/docs/ai.md

@@ -13,7 +13,7 @@ Don't run a structured extraction through `askAi` (the result is stranded in a c
 
 ## Declared agents — what `useAgentRun` runs
 
-`useAgentRun` runs an agent already bound to the app; none can be added or changed any more, and `remove_app_binding` with `kind: "agent"` unbinds one. A new job for an agent is a declared Query or Workflow node of the app, which an outside agent runs with `run_app_query` and `run_app_workflow`. `.lotics/app_agents.d.ts`, generated from the app's live bindings by `lotics app create --custom` and `lotics app deploy`, types `useAgentRun("<alias>")` by the agent's input and output shapes.
+`useAgentRun` runs an agent already bound to the app; none can be added, changed or removed any more. A new job for an agent is a declared Query or Workflow node of the app, which an outside agent runs with `run_app_query` and `run_app_workflow`. `.lotics/app_agents.d.ts`, generated from the app's live bindings by `lotics app create --custom` and `lotics app deploy`, types `useAgentRun("<alias>")` by the agent's input and output shapes.
 
 ---
 

package/docs/members_and_options.md

@@ -194,10 +194,10 @@ three gates are observable as an `error` on the hook:
    resolves to `{ members: [] }`.
 
 Name the group by the `grp_…` id the workflow input's `group` declares — the binding below, set
-with `set_app_workflow`:
+with `set_workflow`:
 
 ```jsonc
-// set_app_workflow — the declaration that unlocks useMembers
+// the header of a set_workflow source — the declaration that unlocks useMembers
 {
   "alias": "assignOrder",
   "inputs": {

package/docs/mutations.md

@@ -24,7 +24,7 @@ const result = await createOrder({ customer_id, quantity: 3 });
   against the alias's declared input schema, and executes the workflow under the **app
   owner's** authority (never the viewer's — see [security](./security.md) for attribution,
   privilege gates, and public-app semantics).
-- Binding is server-side and live: `set_app_workflow` binds an alias as a new version of the app,
+- Binding is server-side and live: `set_workflow` binds an alias as a new version of the app,
   and a deploy never touches it. The declaration also types `useWorkflow` (below).
 - Invoking an alias that is not bound resolves with `status: "error"` and a message naming
   the missing binding.
@@ -170,7 +170,7 @@ envelope's grammar — `message` is required, `field_errors` never reaches the a
 
 - **Typed for free — persisted at `set`.** The alias's `outputs` schema is derived at save
   time from the inferred type of the body's `return({ data })`. When the binding declares
-  **no** `outputs`, `set_app_workflow` stores the derived schema as the alias's `outputs`. An
+  **no** `outputs`, `set_workflow` stores the derived schema as the alias's `outputs`. An
   **explicitly declared** `outputs` is authoritative and never overwritten;
   declare one only to narrow beyond what's inferred. A shape the checker can't pin down degrades
   to untyped `json`, never to a wrong schema.
@@ -214,7 +214,7 @@ if (r.status === "success" && r.data) {
 An alias's declaration is `{ inputs?, outputs?, workflow_id? }` — `workflow_id` is the server's
 half, stamped by the first bind, so an alias an author has only just written carries none.
 `inputs` maps each input name to a typed declaration; it is authored beside the body and
-travels with it (`set_app_workflow` takes both), and the schema the body was verified against is
+travels with it (`set_workflow` takes both), and the schema the body was verified against is
 canonical. It drives three things at once: compile-time typing of the `useWorkflow` payload,
 compile-time typing of `trigger.app_workflow.inputs.*` inside the body, and runtime payload
 validation at the execute boundary.
@@ -283,7 +283,7 @@ When the alias declares `inputs`, the server validates the payload before the wo
   added after authoring is accepted, a removed one rejected
   (`select input "<path>" value "<v>" is not one of its current options (<label>=<value>, …)`) with no
   redeploy. A `field` that doesn't exist or names a non-select field is rejected at bind time
-  (`set_app_workflow`) with
+  (`set_workflow`) with
   `select input references field "<key>", which does not exist in this workspace` /
   `… which is a <type> field, not a select`. Prefer `field` for any select backed by a real
   field; keep `options` for a fixed enum the app owns. Populate pickers from `useFieldOptions`
@@ -460,7 +460,7 @@ return({ status: "success", message: "Updated." });
 ```
 
 `update_records` has no bypass flag — a locked record's values change only through the
-approval flow below (or the table's owner or an admin explicitly unlocking the record first; `unlock_records` is
+approval flow below (or the table's owner or an admin explicitly unlocking the record first; `update_records` with `locked: false` is
 owner- or admin-gated — in an app's run, judged as the member who pressed, never the app's owner — so don't build an unlock→edit→relock workflow around the approval flow — the
 lock exists to route changes through review).
 
@@ -553,7 +553,7 @@ What the steps cannot tell before they run is never guessed:
   looks for a row to reuse draws nothing until the server says which it did. A `catch` block and a
   `while` or counted `for` loop wait too.
 - A pause (`wait`, `wait_for_event`, `wait_for_approval`): every write after it waits for the answer.
-- A step that changes rows it cannot draw — `lock_records`, `restore_records`, a pressed button, an
+- A step that changes rows it cannot draw — `lock_records`, `update_records` with `restore` or `locked`, a pressed button, an
   agent whose tools can change rows, a `create_records` matching on a field, a filtered update or
   delete: every read over the tables it may touch (every read, where it names none) is `pending`
   until the answer lands.

package/docs/recipes.md

@@ -121,11 +121,7 @@ Two **separate** layers; set both.
 
 **Launcher chrome** — `lotics run set_app '{"app_id":"…","body":{"icon":"truck","color":"blue"}}'`.
 `icon` is any Lucide name (the full library, validated at write time — a wrong name is rejected, not
-silently boxed). Don't guess the kebab spelling:
-
-```
-lotics run search_app_icons '{"query":"shipping"}'   → ["truck","ship","package",…]
-```
+silently boxed). Don't guess the kebab spelling: a wrong name is refused with the nearest Lucide names.
 
 `color` is a named palette colour: `red orange amber yellow lime green emerald teal cyan sky
 blue indigo violet purple fuchsia pink rose slate gray zinc neutral stone`. `null` in `body` clears

package/docs/workflows.md

@@ -1,6 +1,6 @@
 # Workflows — the body-authoring reference
 
-The grammar of a **workflow body**: what `set_app_workflow` takes as an alias's `source`, the
+The grammar of a **workflow body**: what `set_workflow` takes as a `source` bound to an app's alias, 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.
@@ -17,7 +17,7 @@ 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 when it is read (`get_app_workflow`), so a
+  stored form. The stored tree renders back to source when it is read (`get_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
@@ -31,10 +31,10 @@ if (order.data["fld_status"] == "opt_open") { … }
 
 ## Where a body lives
 
-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 an earlier body is restored by writing it again. Input declaration vocabulary and validation:
+A body is the app's, stored on the server and bound to an alias: `set_workflow` takes a
+`source` whose `on({ type: "app", app_id, alias, inputs?, outputs? })` header names the alias and its `inputs`
+(leave `outputs` off to let the body's `return({ data })` derive it), then the body. The server verifies the body and the write lands live, as a new
+version of the app; `get_workflow` reads it back, and an earlier body is restored by writing it again. Input declaration vocabulary and validation:
 [mutations](./mutations.md#declaring-workflow-inputs).
 
 An app workflow body carries **no trigger declaration** — the binding supplies the trigger
@@ -250,7 +250,7 @@ only the dialog. What it may name depends on who renders the refusal:
 
 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 — and by a `verify_only` call before that. `return({ field_errors })` keys are not checked.
+`set_workflow`, by an agent binding one — and by a `dry_run` call before that. `return({ field_errors })` keys are not checked.
 
 ### `wait_for_approval` — the one wait worth binding
 
@@ -460,7 +460,7 @@ 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 read.** Inlining erases it: `get_app_workflow` returns
+**A declared `function` does not survive a read.** Inlining erases it: `get_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.
 
@@ -834,7 +834,7 @@ genuinely recursive.
 
 ## The check loop
 
-`set_app_workflow` with `verify_only: true` gives the verdict a save would, and writes nothing. The
+`set_workflow` with `dry_run: 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, table reach, the `field_key` rule and the published-API guard. **Green means the save will take
@@ -849,8 +849,8 @@ fix-stating messages before you see them.
 
 `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 `set_app_workflow` with
-`verify_only: true` and a `record_id` (the row an Act would run on) or `preview_inputs` (the values of a
+rejects, or read a path that is null on real data. The rehearsal for that is `set_workflow` with
+`dry_run: true` and a `record_id` (the row an Act would run on) or `preview_inputs` (the values of a
 workflow that takes inputs and no row): the draft is walked by the engine an Act's preview uses, under the
 app's authority, with the production expression evaluator. Reads are real; writes and service sends are
 said, not made, and a document a step renders is made as a paper no listing shows. It answers `preview`
@@ -865,7 +865,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
-// set_app_workflow { "alias": "log_visit", "inputs": … }
+// the header of a set_workflow source: on({ type: "app", app_id, alias: "log_visit", inputs: … })
 "inputs": {
   "site": { "type": "record_link", "table_id": "tbl_sites" },
   "recording": { "type": "object", "fields": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.124.8",
+  "version": "0.124.9",
   "description": "The SDK a Lotics custom-code app reads and writes through — typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {