@lotics/cli 0.309.0 → 0.311.0

package/dist/src/client.js

@@ -182,6 +182,11 @@ async function pollCliLogin(apiUrl, request_id, secret) {
 function newRequestId() {
   return crypto.randomUUID().replace(/-/g, "").slice(0, 12);
 }
+function unparsedAnswer(text) {
+  if (!/^\s*<(!doctype|html)\b/i.test(text)) return text;
+  const title = /<title[^>]*>([^<]*)<\/title>/i.exec(text)?.[1]?.trim() ?? "";
+  return `a web page, not an answer from Lotics${title === "" ? "" : ` \u2014 "${title}"`}. It came from the network in front of the server.`;
+}
 var LoticsClient = class {
   apiKey;
   workspaceId;
@@ -215,7 +220,7 @@ var LoticsClient = class {
     } catch {
       body = {};
     }
-    const message = typeof body.message === "string" ? body.message : text;
+    const message = typeof body.message === "string" ? body.message : unparsedAnswer(text);
     const hint = typeof body.hint === "string" ? `
   ${body.hint}` : "";
     const trace = requestId === void 0 ? "" : `

package/docs/agent_surface.md

@@ -115,9 +115,13 @@ lotics run run_app_query '{"app_id":"app_…","alias":"hire_list","params":{"sta
 | `sort` | An order in place of the query's own: `[{ "field_key": "<column>", "order": "asc" }]`, `asc` or `desc`, each `field_key` an output column's name |
 | `count` | `true`: `total`, the number of rows, in place of the rows; with `count_by`, `counts` per value of one column, keyed by an option's label, a member's name or a linked row's display; with `count_where` — a map of name → filter, never beside `count_by` — `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |
 | `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), or `day` (a date column, answered as `__day`), and `sum` (a number column, answered as `__sum`), each group with its `__count`. Sent with `params` and `filters` alone |
-| `limit`, `cursor` | A page — 200 rows at most, 50 where no `limit` is stated — and the `next_cursor` of the page before it; `truncated` says more rows matched |
+| `limit`, `cursor` | A page — 200 rows at most, 50 where no `limit` is stated — and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |
 | `runs` | Several reads in one call, 20 at most, each with its own `alias` and arguments, answered in order under `runs`. Never beside an `alias` of the call's own |
 
+A query that states its own `limit` lists at most that many rows: `truncated` is `true` where more match, and `total` is
+the rows the filtered query matches without it. A `count`, `count_by`, `count_where` and an `aggregate` are over every row
+the query matches, never over the rows its `limit` lists.
+
 The rows of one call, across its reads, total at most 262,144 bytes: a read past that is refused, naming
 `fields` and `limit` as what narrows it. The names `filters`, `fields`, `sort`, `count_by` and `aggregate`
 take are the ones on the query's `returns` line.
@@ -172,6 +176,30 @@ answer is then `status: "not_previewed"` with
 `preview: { "available": false, "reason" }`, and nothing ran — within `runs`, it ends the call. The same
 answers a caller outside the app's organization.
 
+## A reviewed act
+
+An act that states `review` runs a workflow that only proposes: call it with the inputs the act asks and it answers,
+writing nothing, the changeset its body proposes in `data.review` — `table_id`, `creates` (each with its `key`) and
+`updates` (each with its `record_id`), each row's `data` holding only the fields that change, by field key, with an
+optional `note` and `ticked` (`false` where the body leaves it for a person to choose), and `unplaced`, what was read
+and matched nothing. Call it again with the same inputs and `approved`,
+`{ "updates": [{ "record_id", "sha" }], "creates": [{ "key", "sha" }] }` — `sha` the SHA-256, in hex, of the row's `data`
+as canonical JSON (every object's keys sorted) as it was read — and the platform writes those rows as that second call
+proposes them, each only where it proposes the values read:
+
+```
+lotics run run_app_workflow '{"app_id":"app_…","alias":"match_statement","inputs":{"record_ids":["rec_…"],"statement":"fil_…"}}'
+lotics run run_app_workflow '{"app_id":"app_…","alias":"match_statement","inputs":{"record_ids":["rec_…"],"statement":"fil_…","approved":{"updates":[{"record_id":"rec_…","sha":"9f2c…"}],"creates":[{"key":"line-4","sha":"41d0…"}]}}}'
+```
+
+The answer's `data.applied` names the run (`execution_id`), the records `updated`, each `created` record by its key,
+and each approved row `left` with its `reason`: `not_proposed` (the second call no longer proposes it), `not_acted`
+(an update of a record the act was not run on), `changed` (the second call proposes other values than were read — read
+the proposal again), `empty` (an update changing no field), `missing`, `locked` or `conflict`. Every approved row is
+checked before any is written, and all are written in one transaction or none; the status history of each row written
+that moved is recorded by the same run, so the workflow step `undo_record_changes` with `execution_id` takes back both. An act over every
+row in view takes no `record_ids`. A `file` input takes the id of a file uploaded to the workspace.
+
 ## A refusal
 
 A workflow re-checks on the server every rule the screen shows: what an act requires, a bound, a duplicate,

package/docs/design.md

@@ -37,7 +37,7 @@ rows in time, a template's act — until the model states it or declines it.
    `figure`, its `due` dates.
 4. **Each app's composition** — the register's `columns` in the order the job reads them, as many as fit a
    desk (one that does not fit is drawn nowhere in the row; what is read only on the way deeper is the
-   record's), the `filters` it narrows by every day (at most 3, each a field the rows show), its `layout`
+   record's), the `filters` it narrows by every day (at most 3, each a field the rows show, or a formula yes/no of fields they show), its `layout`
    and `readings`; the record's `sections` in the order the work reaches them, each one's `fields`, `blocks`
    and `acts`; the `checks` that warn or refuse. A rule the business states — a field needed before an act,
    a quantity bounded, a picker narrowed, a duplicate reused — is the model's (an act's `requires`, a check's
@@ -82,6 +82,7 @@ then check again. A note refuses nothing.
 | Rows that are each a place a record is sent | a rows block with `expect` on the link to those places and `post`: each ticked, the post written there and read as its feed shows it | `model/publish-desk` |
 | Papers an agent reads, where the owner asked for one | an act's `intake` with `fills` | `model/papers-and-recordings` |
 | Calls and visits | an act's `record` | `model/papers-and-recordings` |
+| Changes a workflow proposes that a person approves row by row — a price list applied, a statement matched to what is owed | an act's `workflow` with `review`, asking its file as a `file` input; the body returns a changeset in `data.review` | `model/acts` |
 | Documents covering lines | a rows block with `under` | `model/blocks` |
 | Rows on file a record takes in | a rows block with `pick` | `model/blocks` |
 | One owner's question across jobs | a dashboard app | `model/dashboards` |
@@ -199,7 +200,7 @@ refused. Worked: `examples/approval`.
 #### Readings
 
 `register.readings` stand above the rows and read the rows in view. Lead with the job's headline number —
-its exception as a formula's yes/no in a `metric`'s `where` (what is late, what is short), never a stage the
+its exception as a formula's yes/no in a `metric`'s `where` (what is late, what is short; the rows draw it where every field of its own row it reads is drawn, at that width), never a stage the
 status chips already count — then at most the mix (`breakdown`) and the movement (`trend`), varied by job.
 A `pivot` reads on a dashboard. A dashboard app (`dashboard`) answers one owner's question across jobs, each
 reading windowed by the period the reader picks, and a `list` reading hands over the rows to act on. A

package/docs/workflows.md

@@ -255,6 +255,25 @@ initial value. A callback gets `(item, idx)` (`reduce`: `(acc, item, idx)`) and
 expression — `(x) => <expr>`, `(x) => { return <expr>; }` or `function (x) { return <expr>; }`;
 several statements, `async` and named function expressions are refused.
 
+Look a row up by key rather than filtering for it: a `filter` inside a callback walks its whole list again
+for every item, so a thousand items against a few hundred rows is hundreds of thousands of calls. Group the
+rows once, then read each group by its key. `groupBy` answers an object of lists, and `byCode[code] ?? []`
+is the group a code names, or an empty list:
+
+```
+const parties = await query_records({ table_id: "tbl_parties" });
+const lines = await query_records({ table_id: "tbl_sheet_lines" });
+const byCode = groupBy(parties.records, (p) => p.data["fld_code"] ?? "");
+const holders = lines.records.map((line) => ({
+  line: line.id,
+  parties: (byCode[line.data["fld_code"] ?? ""] ?? []).map((p) => p.id),
+}));
+```
+
+A key is read exactly: a code holding a dot, a slash or a bracket reads its own group, and a name every
+object inherits (`constructor`) reads nothing unless a row made a group of that name. `get(o, "a.b")`
+follows a dotted path instead, so a key that holds a dot is read with `o[key]`.
+
 ## Writing a field: null and undefined
 
 In `update_records`' `set` and `create_records`' `records`:
@@ -493,6 +512,64 @@ while (more) {
 return({ status: "success", message: `${reverted} put back, ${left} left as they stand` });
 ```
 
+A shop matches a bank statement to the notes it is owed by an act that states `review`. That act's workflow only
+proposes: its body calls steps that read and no other, and runs no agent — either is refused when the body is saved —
+and returns in `data.review` one changeset of the act's table, which the platform writes the approved rows of. Called
+with what the act asks, it answers the proposal and nothing is written; called again with
+`approved: { updates: [{ record_id, sha }], creates: [{ key, sha }] }`, the body runs again and the platform writes
+those rows as this second run proposes them, so the body never reads `approved`. `sha` is the SHA-256, in hex, of the
+row's `data` as canonical JSON (every object's keys sorted) as the caller read it: a row the second run proposes with
+other values is left unwritten (`changed`), so the body must propose the same for the same inputs and the rows it reads.
+An update is of a record the act is run over (`record_id`, or one of `record_ids`): one of any other record is left
+unwritten. An act over every row in view is handed no rows: its body reads the rows it may change, and any of them may
+be proposed. A create carries a `key`, a text of the body's own that names the same line on every run
+(`key: toString(line["Reference"])`), unique among the creates; where a confirm repeated must not add a second row,
+the body also writes the key into a field the table keeps unique, so the repeat's create is left as a `conflict`.
+Each row's `data` holds only stored fields that change — never one the platform computes or stamps, nor a file — with
+a `note` and a `ticked` the reader starts from, and `unplaced` lists what was read and matched nothing. Every approved
+row is checked against its fields before any is written, and they are written in one transaction, so a flawed one
+writes none. The status history of every row written that moved, or was made holding a status, is recorded in the
+same run, so the workflow step `undo_record_changes` with the run's id takes back both. A body that stops proposing a row once it is
+written — it matches against what the rows hold now — makes approving twice write once.
+
+```
+const inputs = trigger.app_workflow.inputs;
+
+const sheet = await excel_get_rows({ // a workflow step
+  file_id: inputs.statement,
+  columns: ["Reference", "Amount", "Paid on"],
+});
+const unpaid = await query_records({
+  table_id: "tbl_notes",
+  filters: { field_key: "fld_paid_on", operator: "is_empty" },
+  pagination: { offset: 0, limit: 500 },
+});
+const acted = groupBy(inputs.record_ids, (id) => toString(id));
+const owed = filter(unpaid.records, (one) => size(acted[toString(one.id)] ?? []) > 0);
+const byRef = groupBy(owed, (one) => toString(one.data["fld_ref"]));
+
+const lines = sheet.rows.map((line) => ({
+  line,
+  note: first(byRef[toString(line["Reference"])] ?? []),
+}));
+const updates = filter(lines, (one) => !isNull(one.note)).map((one) => ({
+  record_id: toString(one.note?.id),
+  note: `Transfer of ${toString(one.line["Amount"])}`,
+  ticked: toNumber(one.line["Amount"]) == one.note?.data["fld_amount"],
+  data: { fld_paid_on: toString(one.line["Paid on"]) },
+}));
+const unplaced = filter(lines, (one) => isNull(one.note)).map((one) => ({
+  title: `${toString(one.line["Reference"])}: ${toString(one.line["Amount"])}`,
+  note: "Matches no unpaid note",
+}));
+
+return({
+  status: "success",
+  message: `${size(updates)} of ${size(lines)} transfers match a note`,
+  data: { review: { version: 1, table_id: "tbl_notes", creates: [], updates, unplaced } },
+});
+```
+
 ## 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.309.0",
+  "version": "0.311.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {