@lotics/cli 0.306.1 → 0.307.1

package/docs/workflows.md

@@ -291,36 +291,206 @@ row of an `.xlsx`, `.xls` or `.csv` sheet in one call, each an object keyed by t
 A sheet past what one call reads is refused with its size, never cut short: the step's entry in
 `workflow_steps` states the bounds.
 
-A table can hold more rows than one page of `query_records` answers, so the body never reads "the
-table" to see what it lacks. It takes the sheet fifty rows at a time — what one `create_records` call
-writes — asks the table for those rows' codes alone, and writes the rest in one call:
+`import_rows`, a workflow step, matches those rows to a table by a key and writes what differs. `match`
+names the fields that identify a row, compared as trimmed text with case ignored: a row matching no live
+row is added, one matching a row changes only the cells that differ, and one that changes nothing is
+counted and not written, so the same file run twice writes nothing the second time. `values` holds a
+row's cells by field key, as `create_records` takes them; a key the row omits is left as the table holds
+it, and `null` is an empty cell, which differs from a filled one as any other value does.
+
+A `match` field may also be a link field holding one row, compared by the row linked: lines keyed by
+their parent and a line number state `match: ["fld_invoice", "fld_line"]`, the parent given as its
+record id or as `{ lookup: "<text>" }`.
+
+What the step is not certain of is held — answered with why, and not written: a row carrying `hold`
+(its text is the message); a row whose key several live rows carry, or an earlier row of the same call;
+a row the table's checks refuse, or whose row is locked; with `create: false`, a row matching none. A
+held row never fails the step, and the rows beside it are written. A row whose key names a row outside
+the rows the run may write is held `refused` with nothing of that row: no `record_id`, no `changes`.
+
+The step removes no row, and a row the source leaves out is never touched. A row carrying
+`remove: true`, with its key in `values`, proposes moving the row its key names to the trash: it is
+always held, whatever `create` and `conflicts` say, and a key naming no row is counted unchanged.
+
+`conflicts` states what a matched row does where a live cell holds another value: `"hold"` writes the
+row's empty cells and holds the differing ones, `"overwrite"` writes over them, `"fill_empty"` leaves
+them. `conflicts.fields` gives one field its own. A number and the field its unit or currency is read
+from on each row are one cell, under the number's policy: both are written, or both held.
+
+A link cell takes `{ lookup: "<text>" }` in place of record ids: the linked row is the one row holding
+that text in the linked table's unique or autonumber field, else the one titled it, among the rows the
+run reads of that table. A text naming no row, or several, holds the row, and the rows it could be are
+answered beside it. A link holding many rows takes a list, `[{ lookup: "<text>" }, …]`: each text is
+resolved by itself.
+
+The step keeps nothing of its own: its answer is everything it did. `written` lists each record it
+wrote — a changed one with each field from old to new as text, a created one by its id alone — and
+`held_rows` each row it held: its `kind`, `reason` and `message`, the `record_id` of the row it matched,
+its `key`, the `changes` it would make, the `links` it could not resolve with their `candidates`, and
+`values` — its key and the cells it would write, as the call gave them. A later call given a held row's
+`values` under `conflicts: { default: "overwrite" }` writes it. Both lists are read under the run's own
+reach of the table, and a workflow hands its caller only what it returns. Two calls matching one table
+by the same fields take turns, so the second matches the rows the first added. The step's entry in
+`workflow_steps` states its bounds.
+
+`undo_record_changes`, a workflow step, puts back what one run wrote on records of a table. It takes the
+table, up to 500 record ids and the run — what `runtime.execution_id` held in it. A field goes back
+where the row still holds what the run wrote. A row the run created goes to the trash
+where nothing else has written it or linked a row to it since; in a table where a workflow writes each
+new row, every row created reads as written since, and is kept. A row the run moved to the trash comes
+back where nothing has touched it since, without the links to it that its removal took off other rows.
+A row the run brought back from the trash stays out of it. A write of the run that was itself an undo is
+not put back. What the step leaves as it stands is answered in `kept`, one entry a record and reason:
+something changed it since, it is outside the rows the member may write, the table refused the write,
+what the run wrote on it cannot be read, or the run brought it back from the trash.
+
+Two more workflow steps read and settle one record's saves: `get_record_activity`, a workflow step,
+lists them, and `undo_record_change`, a workflow step, puts one back. What they read is the run's to
+read; inside an app's workflow it is what the app reads — the fields of the app's entity over the table,
+a record that entity's own read reaches. An undo, of one save or of a run's writes, is the own save of the
+member the run acts for — whoever started the app's workflow, pressed the button, or made the write a
+table's workflow followed: that member holds the table's write as the step runs, each row within the
+rows they may write, and the table's locks, checks and write rules answer for them. A run that acts for
+no member — a schedule's, a public visitor's — reads, and its undos are refused.
+
+What a business keeps of an import — the file, its counts, the lines waiting for a person — is rows of
+its own tables, written by the workflow that ran the step. A garden centre brings its grower's price
+sheet into its plants, and keeps each sheet and its lines. A line names its plant through a link
+holding many rows: one holding a single row would make the line that plant's own, and a plant its
+lines belong to is not moved to the trash.
+
+These tables are shown beside the plants, in the same app: the sheets as a log of the plants' register
+(`logs`, `lotics docs model/logs`), a sheet's lines on the page it opens. A line keeping what a cell held
+and what it holds now in two fields reads one against the other (`compare`, `lotics docs model/blocks`).
 
 ```
 const sheet = await excel_get_rows({ // a workflow step
   file_id: trigger.app_workflow.inputs.file,
-  columns: ["Code", "Filed", "Amount"],
+  columns: ["Code", "Name", "Price"],
 });
 
-for (let start = 0; start < sheet.row_count; start += 50) {
-  const rows = uniqueBy(slice(sheet.rows, start, start + 50), (row) => toString(row["Code"]));
-  const held = await query_records({
-    table_id: "tbl_declarations",
-    filters: { field_key: "fld_code", operator: "is_any_of", value: rows.map((row) => toString(row["Code"])) },
-    pagination: { offset: 0, limit: 1000 },
+const imported = await import_rows({ // a workflow step
+  table_id: "tbl_plants",
+  match: ["fld_code"],
+  rows: sheet.rows.map((row, at) => ({
+    line: at + 2,
+    hold: isNull(row["Price"]) ? "The sheet states no price" : null,
+    values: {
+      fld_code: toString(row["Code"]),
+      fld_name: toString(row["Name"]),
+      fld_price: toNumber(row["Price"]),
+    },
+  })),
+});
+
+const kept = await create_records({
+  table_id: "tbl_price_sheets",
+  records: [{
+    fld_file: [trigger.app_workflow.inputs.file],
+    fld_run: runtime.execution_id,
+    fld_read: imported.read,
+    fld_created: imported.created,
+    fld_changed: imported.changed,
+    fld_held: imported.held,
+  }],
+});
+const sheet_id = kept.record_ids[0];
+
+for (let start = 0; start < size(imported.written); start += 50) {
+  await create_records({
+    table_id: "tbl_sheet_lines",
+    records: slice(imported.written, start, start + 50).map((one) => ({
+      fld_sheet: [sheet_id],
+      fld_plant: [one.record_id],
+      fld_line: one.line,
+      fld_outcome: one.kind,
+      fld_changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "—"} → ${change.after ?? "—"}`), "; "),
+    })),
+  });
+}
+for (let start = 0; start < size(imported.held_rows); start += 50) {
+  await create_records({
+    table_id: "tbl_sheet_lines",
+    records: slice(imported.held_rows, start, start + 50).map((one) => ({
+      fld_sheet: [sheet_id],
+      fld_plant: isNull(one.record_id) ? [] : [one.record_id],
+      fld_line: one.line,
+      fld_outcome: "held",
+      fld_why: one.message,
+      fld_code: one.key["fld_code"],
+      fld_name: toString(one.values["fld_name"]),
+      fld_price: toNumber(one.values["fld_price"]),
+      fld_changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "—"} → ${change.after ?? "—"}`), "; "),
+    })),
+  });
+}
+
+return({ status: "success", message: `${imported.created} added, ${imported.changed} changed, ${imported.held} held` });
+```
+
+A held line keeps the `values` the step answered for it — its key and each cell it would write — in
+fields of its own. It is applied by the act on it, whose workflow hands the step those values again and
+lets it write over what the plant holds. A cell the line holds none of is left out, so a held line
+never empties a cell of the plant:
+
+```
+const line = await get_record({ table_id: "tbl_sheet_lines", record_id: trigger.app_workflow.inputs.record_id });
+const values = {
+  fld_code: line.data["fld_code"],
+  ...(isEmpty(line.data["fld_name"]) ? {} : { fld_name: line.data["fld_name"] }),
+  ...(isNull(line.data["fld_price"]) ? {} : { fld_price: line.data["fld_price"] }),
+};
+
+const applied = await import_rows({ // a workflow step
+  table_id: "tbl_plants",
+  match: ["fld_code"],
+  conflicts: { default: "overwrite" },
+  rows: [{ values }],
+});
+if (applied.held > 0) {
+  return({ status: "error", message: applied.held_rows[0].message });
+}
+
+await update_records({ table_id: "tbl_sheet_lines", record_ids: [line.id], set: { fld_outcome: "applied" } });
+return({ status: "success", message: "Applied." });
+```
+
+A sheet is undone by the act on it, whose workflow hands the step the run the sheet kept and the
+plants its lines name, 500 at a time:
+
+```
+const sheet = await get_record({ table_id: "tbl_price_sheets", record_id: trigger.app_workflow.inputs.record_id });
+
+let reverted = 0;
+let left = 0;
+let offset = 0;
+let more = true;
+while (more) {
+  const lines = await query_records({
+    table_id: "tbl_sheet_lines",
+    filters: {
+      logic: "and",
+      children: [
+        { field_key: "fld_sheet", operator: "has_any_of", value: [sheet.id] },
+        { field_key: "fld_outcome", operator: "is_any_of", value: ["created", "changed"] },
+      ],
+    },
+    pagination: { offset, limit: 500 },
   });
-  const known = held.records.map((r) => toString(r.data["fld_code"]));
-  const fresh = filter(rows, (row) => !includes(known, toString(row["Code"])));
-  if (size(fresh) > 0) {
-    await create_records({
-      table_id: "tbl_declarations",
-      records: fresh.map((row) => ({
-        fld_code: toString(row["Code"]),
-        fld_filed: isString(row["Filed"]) ? row["Filed"] : null,
-        fld_amount: toNumber(row["Amount"]),
-      })),
+  if (size(lines.records) > 0) {
+    const undone = await undo_record_changes({ // a workflow step
+      table_id: "tbl_plants",
+      record_ids: flatten(lines.records.map((line) => line.data["fld_plant"])),
+      workflow_execution_id: toString(sheet.data["fld_run"]),
     });
+    reverted += undone.reverted;
+    left += size(undone.kept);
   }
+  more = size(lines.records) == 500;
+  offset += 500;
 }
+
+return({ status: "success", message: `${reverted} put back, ${left} left as they stand` });
 ```
 
 ## Table checks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.306.1",
+  "version": "0.307.1",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
     "generate:model-reference": "node --import tsx dev/model_reference_gen.ts",
     "generate:examples": "node --import tsx dev/examples_gen.ts",
     "generate:snapshots": "node --import tsx dev/factory_snapshots.ts",
+    "generate:agent-surface": "node --import tsx dev/agent_surface_gen.ts",
     "typecheck": "tsgo --noEmit",
     "lint": "oxlint",
     "test": "vitest run",