@lotics/cli 0.313.5 → 0.315.0

package/docs/agent_surface.md

@@ -263,9 +263,13 @@ its alias in `queries`, it is the model's. A caller sees the description and
 each input's `description` and nothing else, so each says what the value is and what leaving it out means;
 `check_model` notes one that says nothing.
 
-**Shape each for a caller that is not looking at a screen.** Take a list where one job covers many records.
-Make a write survive running twice. Return the ids of what was written under `outputs`, so the next run can
-read them. Gate what cannot be undone behind an approval step.
+**Shape each for a caller that is not looking at a screen.** One job a person hands an agent — a paper read,
+a message answered, a sheet brought in — is one declared workflow named for the job, never a chain of the
+generated per-row workflows. Take a list where the job covers many rows, a record's lines among them. A body
+that writes more than one row makes them in one `save_record` workflow step, all or nothing, and recognises
+what exists by the identity the input itself carries, declared unique on its table, so the same input sent
+twice updates instead of adding. Return the ids under `outputs`, so the next run can read them. Gate what
+cannot be undone behind an approval step.
 
 ## Prove an app as an agent
 
@@ -281,3 +285,5 @@ Run on a throwaway record.
 6. `run_app_workflow` `record_activity` for the record, then `record_activity_undo` with the entry the act
    wrote: each field the act changed reads as it did before step 4, but one written since, which `kept`
    names. A row the act added under the record and a file it made stay.
+7. `run_app_workflow` the app's job workflow with the input a person would hand it — the paper read, the row:
+   it completes in one call. Call it again with the same input: nothing is added.

package/docs/workflow_steps.md

@@ -3246,6 +3246,38 @@ above. A provider's refusal carries the provider's own words.
 | `mime_type` | string | yes |  |
 | `url` | string | yes |  |
 
+### save_record (workflow step)
+
+- Save a record found by its identity, with its lines, all or nothing.
+- A call whose match is carried by no live record adds it; one carried by a record changes the cells of set that differ and appends add_to, so sending the same call twice writes nothing the second time. match holds the record's identity: field keys with their values, exactly the fields of one uniqueness its table declares (a unique field, or fields unique together). set holds its other cells. add_to lists items to append to a files, multi-select or many-link field, keeping what it holds. lines saves rows of other tables that link the record.
+- Each entry names the child table_id, its one-row link field to this table, match (the child fields that with link are one uniqueness of the child table) and rows, each stating every match field. link is set by the step and no row states it.
+- A line found by its match changes the cells that differ; one not found is added; a line not listed is left as it is.
+- Any refusal — a table check, a locked record, a value a field does not take, no write access to a table — saves nothing.
+- Returns { record_id, created, updated_field_keys, lines }: the cells changed on a record that existed, and per entry of lines the ids it added, changed and left unchanged.
+
+**Inputs**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `table_id` | string | yes |  |
+| `match` | object | yes |  |
+| `set` | object \\| null |  |  |
+| `add_to` | object \\| null |  |  |
+| `lines` | object[] \\| null |  |  |
+
+**Answer**
+
+| Name | Type | Required | What it is |
+| --- | --- | --- | --- |
+| `record_id` | string | yes |  |
+| `created` | boolean | yes |  |
+| `updated_field_keys` | string[] | yes |  |
+| `lines` | object[] | yes |  |
+| `lines[].table_id` | string | yes |  |
+| `lines[].created_ids` | string[] | yes |  |
+| `lines[].updated_ids` | string[] | yes |  |
+| `lines[].unchanged_ids` | string[] | yes |  |
+
 ## send
 
 ### send_notification (workflow step)

package/docs/workflows.md

@@ -571,6 +571,61 @@ return({
 });
 ```
 
+### Saving a record with its lines
+
+`save_record`, a workflow step, saves one record and the rows of other tables that hang off it, all or
+nothing, and recognises what exists by the identity the input carries — so a call sent twice updates and
+adds nothing. `match` is the record's identity, `{ field_key: value }`, and must be exactly a uniqueness
+its table declares: one field marked `unique`, or the fields of one of the table's `unique` sets together
+(text, number, date, single select and one-row link fields). A `match` that is no declared uniqueness is
+refused, naming what the table does declare. A live record carrying the match is found and only the cells
+of `set` that differ are written; none is found and it is added with `match` and `set`. `add_to` appends
+to a files, multi-select or many-link field and keeps what it holds.
+
+`lines` saves rows of other tables that link the record. Each entry names the child `table_id`, its
+`link` — a field of the child holding one row of this table, which the step fills and no row states —
+the child fields that, with `link`, are one uniqueness of the child table (`match`), and `rows`, each
+stating every `match` field. A line found by its match changes only the cells that differ, one not found
+is added, and a line the call does not list is left as it is: the step deletes nothing. Two rows of one
+entry cannot share a match.
+
+Everything is checked before the first write, and everything is written in one transaction: a table check
+that refuses one line, a locked record or line the call would change, a value a field does not take, or a
+table the run may not write refuses the call and saves nothing, naming the row. Two calls of one identity
+take turns, so the second finds what the first saved. The answer is `record_id`, `created`,
+`updated_field_keys` (the cells changed on a record that existed) and, per entry of `lines`, the ids it
+added, changed and left unchanged.
+
+```
+const inputs = trigger.app_workflow.inputs;
+
+const sheet = await excel_get_rows({ // a workflow step
+  file_id: inputs.release_order,
+  columns: ["Size", "Quantity"],
+});
+
+const saved = await save_record({ // a workflow step
+  table_id: "tbl_release_orders",
+  match: { fld_number: inputs.number },
+  set: { fld_note: "Read from the paper" },
+  lines: [{
+    table_id: "tbl_release_lines",
+    link: "fld_order",
+    match: ["fld_size"],
+    rows: sheet.rows.map((row) => ({
+      fld_size: toString(row["Size"]),
+      fld_quantity: toNumber(row["Quantity"]),
+    })),
+  }],
+});
+
+return({
+  status: "success",
+  message: `${size(saved.lines[0].created_ids)} lines added`,
+  data: { record_id: saved.record_id },
+});
+```
+
 ## Table checks
 
 A table check is one condition its table's record writes must not meet, declared beside the table's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.313.5",
+  "version": "0.315.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {