@lotics/cli 0.289.0 → 0.291.0

package/dist/src/client.js

@@ -62,6 +62,9 @@ async function uploadParts(options) {
 var CLI_CAPABILITIES_HEADER = "x-lotics-cli-capabilities";
 var CLI_CAPABILITIES = ["docs-fallback"];
 
+// ../shared/src/proxy_upload_limit.ts
+var PROXY_UPLOAD_MAX_BYTES = 100 * 1024 * 1024;
+
 // src/client.ts
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -126,6 +129,7 @@ function getMimeType(filename) {
   return MIME_MAP[ext] ?? "application/octet-stream";
 }
 var MULTIPART_THRESHOLD_BYTES = 8 * 1024 * 1024;
+var PROXY_BATCH_MAX_BYTES = PROXY_UPLOAD_MAX_BYTES / 2;
 var LoticsRequestError = class extends Error {
   constructor(message, status, body) {
     super(message);
@@ -578,25 +582,37 @@ var LoticsClient = class {
     );
   }
   async uploadFiles(filePaths, options) {
-    const small = [];
+    const files = [];
+    const errors = [];
     const large = [];
+    let batch = [];
+    let batchBytes = 0;
+    const sendBatch = async () => {
+      const sent = batch;
+      batch = [];
+      batchBytes = 0;
+      try {
+        const result = await this.uploadFileBytes(sent);
+        files.push(...result.files);
+        errors.push(...result.errors);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push(...sent.map((item) => ({ filename: item.filename, error: message })));
+      }
+    };
     for (let i = 0; i < filePaths.length; i++) {
       const absolutePath = path.resolve(filePaths[i]);
       const filename = options?.filenames?.[i] ?? path.basename(absolutePath);
       const { size } = await fs.promises.stat(absolutePath);
       if (size >= MULTIPART_THRESHOLD_BYTES) {
         large.push({ absolutePath, filename, size });
-      } else {
-        small.push({ bytes: await fs.promises.readFile(absolutePath), filename });
+        continue;
       }
+      if (batch.length > 0 && batchBytes + size > PROXY_BATCH_MAX_BYTES) await sendBatch();
+      batch.push({ bytes: await fs.promises.readFile(absolutePath), filename });
+      batchBytes += size;
     }
-    const files = [];
-    const errors = [];
-    if (small.length > 0) {
-      const result = await this.uploadFileBytes(small);
-      files.push(...result.files);
-      errors.push(...result.errors);
-    }
+    if (batch.length > 0) await sendBatch();
     for (const item of large) {
       try {
         files.push(await this.uploadLargeFile(item));

package/docs/cli_reference.md

@@ -31,7 +31,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | — | **The exit code reports the WORK, not just the call — for the two tools that RUN one.** `run_app_workflow` and `run_app_agent` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`) exit non-zero and print `<tool> → <status>: <message>` to stderr, so `lotics run … && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE — an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` is data, and exits 0. |
 | `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |
 | `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes — harvested records **only**, never files / external calls / notifications. **Not a rollback**; a rollback is structurally impossible here. A partial cleanup exits non-zero so a script cannot read it as success. |
-| `lotics file upload <file\|dir...>` (alias `lotics upload`) · `--stdin` · `--base64` · `--url <url>` | Upload files/directories. **The transport is chosen by size and is not a flag**: under 8 MiB the file is POSTed to `/v1/files` in one request, and several such files go in the same one; at or above it the CLI takes presigned part URLs and PUTs the bytes straight to object storage, so they never pass through the API. That threshold matches the AWS CLI's own `multipart_threshold`, and the number matters less than there being nothing to choose — one verb, any size, up to the 2 GiB a workspace may store. A large upload reads one part at a time, so memory stays flat regardless of file size, and a failure part-way abandons the parts already sent rather than leaving them billable and invisible. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** — an attachment decoded in memory, a generated document, a signed download link — each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY — `Buffer.from(s, "base64")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |
+| `lotics file upload <file\|dir...>` (alias `lotics upload`) · `--stdin` · `--base64` · `--url <url>` | Upload files/directories. **The transport is chosen by size and is not a flag**: under 8 MiB the file is POSTed to `/v1/files`, several such files to a request up to half that route's 100 MiB cap; at or above it the CLI takes presigned part URLs and PUTs the bytes straight to object storage, so they never pass through the API. That threshold matches the AWS CLI's own `multipart_threshold`, and the number matters less than there being nothing to choose — one verb, any size, up to the 2 GiB a workspace may store. A large upload reads one part at a time, so memory stays flat regardless of file size, and a failure part-way abandons the parts already sent rather than leaving them billable and invisible. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** — an attachment decoded in memory, a generated document, a signed download link — each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY — `Buffer.from(s, "base64")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |
 | `lotics file download <file_id> [<path>]` · `-o <dir>` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` → fetch the presigned URL and write it where you asked. **The two spellings mean two different things, and neither is read by shape: the positional `<path>` is the FILE to write, `-o <dir>` is the DIRECTORY to save into.** That is `cp` and `curl -o`, so nothing here consults an extension. A named file is written as named, its parent created, overwriting what is there — the point of naming it is that the next command opens that exact path. A directory is created if missing and written into under the stored filename (the response's `Content-Disposition`), taking a free spelling beside a file of that name already there so a repeat download never clobbers the first; with no destination at all, that filename lands in cwd. Give the destination once — a positional and `-o` together is refused, as is a positional that names an existing directory or ends in a separator (`a directory goes in -o`). The first argument is a **file id**, so a path in that slot is refused rather than sent as an id. The written path goes to **stdout** (under `--json`, `{file_id, path, filename, stored_filename}`) and the narration to stderr, so a download pipes into whatever opens it. `lotics file download record <record_id> <field_key> [-o <dir>]` spreads every file on a record's file field over a DIRECTORY — there is no single file for N files to be. |
 | `lotics file list [--limit <n>] [--cursor <token>]` | The workspace's files, newest first — id, upload time, bytes, MIME type, filename on stdout, one per line (`--json` for the object). `GET /v1/files` with no `file_ids`. A file holding the content of a knowledge doc or template you cannot use is left out. **A page, not a dump**: the store only ever grows, so the last line prints the command for the next page and `next_cursor` is null on the last one. The cursor is opaque and keyset — pass it back as given — so an upload landing mid-sweep cannot make a walk skip or repeat a row. Every other file verb takes an id, so this is the only answer to "what is in here" short of reading Postgres. |
 | `lotics file delete <file_id>` | Archive a stored file, over the `delete_file` tool. **Refused while a record cell, a comment, a knowledge doc, a document template or a voice session still references it** — the refusal names the referents, so this is safe to try. The bytes are left in object storage; the row no longer serves them, which is what "deleted" means here. There is no `lotics delete`: the verb needs its noun. |

package/docs/data_model.md

@@ -129,8 +129,8 @@ What `create_table` (on the CLI or in chat) and `update_table` take in `add_fiel
 `select_record_link`, `files`, `formula`, `rollup`, `lookup`, `autonumber`. `button` is retired: an
 existing button field keeps running, but none is created, converted to or edited.
 
-A URL, an email, markdown, a checkbox, a datetime, a currency or a percentage is a `format` on
-another type, never a `type`:
+A URL, an email, markdown, a checkbox, a datetime, money, a quantity or a percentage is a `format`
+or a `notation` on another type, never a `type`:
 
 | Wanted | Field |
 |---|---|
@@ -138,8 +138,9 @@ another type, never a `type`:
 | Email or phone | `{ type: "text" }` |
 | Markdown | `{ type: "text", format: "markdown" }` |
 | Checkbox | `{ type: "boolean" }` |
-| Money | `{ type: "number", format: "currency", currency: "USD" }` |
-| Percentage | `{ type: "number", format: "percentage" }` |
+| Money | `{ type: "number", notation: { style: "currency", currency: "USD" } }` |
+| Quantity | `{ type: "number", notation: { style: "unit", unit: "kg" } }` |
+| Percentage | `{ type: "number", notation: { style: "unit", unit: "percent" } }` |
 | Datetime | `{ type: "date", format: "datetime" }` |
 | Date range | `{ type: "date", format: "date_range" }` |
 
@@ -150,14 +151,18 @@ may itself hold an object (`formula`, `aggregate_option`, `filter`, `order_by`);
 inside it. Each type takes only its own:
 
 - **text** — `format?` (`"text"` | `"link"` | `"markdown"`), `unique?`, `default_value?` (a string).
-- **number** — `format?` (`"number"` | `"currency"` | `"percentage"`), `currency?` (an ISO 4217
-  code), `unit?`, `unit_field?`, `currency_field?`, `default_value?` (a number). On `update_fields`,
-  null clears `currency`, `unit`, `unit_field` or `currency_field`.
-  - `unit`, beside format `"number"`: a measured code — g, kg, t, l, m3, cbm, mm, cm, m, km, m2,
-    min, h, day — or a counted noun such as `kiện`. A change between two units of one dimension
-    converts every stored figure; any other change relabels.
-  - `unit_field`: A single select on the same row, or a lookup of one through a one-link, whose chosen option is that row's unit: every option label is a unit as `unit` takes one. In place of `unit`; only beside format "number".
-  - `currency_field`: A single select on the same row, or a lookup of one through a one-link, whose chosen option is that row's currency: every option label is an ISO 4217 code. In place of `currency`; only beside format "currency".
+- **number** — `notation?`, `default_value?` (a number). `notation` is how the figure reads, one
+  of three; on `update_fields` a stated one replaces the field's whole.
+  - `{ style: "decimal" }` — a plain number, as a field stating none reads.
+  - `{ style: "currency", currency: "VND" }` — money in an ISO 4217 code.
+  - `{ style: "unit", unit }` — a quantity: `"percent"` (10 reads "10%", never multiplied), a
+    measured code — g, kg, t, l, m3, cbm, mm, cm, m, km, m2, min, h, day — or a counted noun such
+    as `kiện`. A change between two units of one dimension converts every stored figure; any other
+    change relabels.
+  - A currency or unit read on each row is `{ per_row: "ĐVT" }` in its place: a single select on
+    the same row, or a lookup of one through a one-link, named by name or key, whose chosen option
+    is that row's currency or unit — every option label an ISO 4217 code, or a unit as `unit`
+    takes one.
 - **date** — `format?` (`"date"` | `"datetime"` | `"date_range"` | `"datetime_range"`), `timezone?`,
   `derive_from?`, `default_value?` (a date string). `derive_from: "created_at"` stamps the row's
   creation once, `"updated_at"` re-stamps on every update; the field is then read-only, takes no
@@ -186,7 +191,7 @@ not exist yet, and option keys (`opt_…`) in `update_fields`.
 Read-only in records. `formula` is one key holding an object; a rollup's and a lookup's properties
 are separate keys on the field — `rollup: {…}` and `lookup: {…}` are refused as unrecognized.
 
-formula: { expression, format?, currency?, unit?, unit_field?, currency_field? }
+formula: { expression, notation?, link? }
 
 - `{Field Name}` or `{fld_key}` names a field of the same table, stored as its key, so a rename never
   breaks the formula. A reference to no field, or a call to something that is no helper, is refused.
@@ -194,9 +199,10 @@ formula: { expression, format?, currency?, unit?, unit_field?, currency_field? }
   `includes({Tags}, "opt_…")` for a multi.
 - The operators, the helpers and how an empty cell reads are the `model` reference, section `formula` — a model
   names fields by alias where a table tool names them by name or key; the language is the same.
-- On `update_fields` a key left out keeps its stored value, and null clears `currency`, `unit`,
-  `unit_field` or `currency_field`. `get_table` marks a formula that is null when every field it
-  reads is empty.
+- `notation` is how a number result reads, as a number field's; `link: true` says the result is a
+  URL, drawn as a link that opens.
+- On `update_fields` a key left out keeps its stored value, and a stated `notation` replaces the
+  stored one whole. `get_table` marks a formula that is null when every field it reads is empty.
 
 rollup — `source_field_key`, `aggregate_option: { field_key?, operation }`, `filter?`
 
@@ -207,9 +213,10 @@ rollup — `source_field_key`, `aggregate_option: { field_key?, operation }`, `f
   `min`, `max`, `range`; date: `earliest`, `latest`, `date_range`.
 - The cell's type comes from the OPERATION: `earliest` and `latest` hold a date, every other
   operation a number (`date_range` counts days). A "most recent linked date" is `latest` — `min` and
-  `max` are numeric and refuse a date. A rollup takes no format, currency or unit of its own: `sum`
-  over money carries the aggregated field's currency, over a weight its unit.
-- Over a figure read in each row's own unit or currency (`unit_field` / `currency_field`), `sum`,
+  `max` are numeric and refuse a date. A rollup takes no notation of its own: `sum` over money
+  reads in the aggregated field's currency, over a weight in its unit, a count as a plain number
+  and a `percent_*` in the unit `percent`.
+- Over a figure read in each row's own unit or currency (a notation's `per_row`), `sum`,
   `avg`, `median`, `min`, `max` and `range` hold only where that select is a lookup, through the
   link paired with `source_field_key`, of a single select on this table — the total reads in this
   row's option of it. A lookup of such a field has no unit.
@@ -227,13 +234,14 @@ lookup — `source_field_key`, `lookup_field_key`, `order_by?`
 ### Examples
 
 ```
-{ name: "Giá bán", type: "number", format: "currency", currency: "VND" }
-{ name: "Trọng lượng", type: "number", unit: "kg" }
-{ name: "Số lượng", type: "number", unit_field: "ĐVT" }
+{ name: "Giá bán", type: "number", notation: { style: "currency", currency: "VND" } }
+{ name: "Trọng lượng", type: "number", notation: { style: "unit", unit: "kg" } }
+{ name: "Số lượng", type: "number", notation: { style: "unit", unit: { per_row: "ĐVT" } } }
+{ name: "Chiết khấu", type: "number", notation: { style: "unit", unit: "percent" } }
 { name: "Trạng thái", type: "select", options: [{ name: "Mới" }, { name: "Xong" }] }
 { name: "Mã đơn", type: "autonumber", template: "SR-{YEAR}-{N:4}" }
 { name: "Khách hàng", type: "select_record_link", table_id: "tbl_x", sync_both_ways: true }
-{ name: "Total", type: "formula", formula: { expression: "{Price} * {Qty}", format: "currency", currency: "VND" } }
+{ name: "Total", type: "formula", formula: { expression: "{Price} * {Qty}", notation: { style: "currency", currency: "VND" } } }
 { name: "SL đã giao", type: "rollup", source_field_key: "Giao hàng", aggregate_option: { operation: "sum", field_key: "Số lượng" } }
 { name: "Customer Name", type: "lookup", source_field_key: "Customer", lookup_field_key: "Name" }
 { name: "Latest note", type: "lookup", source_field_key: "Calls", lookup_field_key: "Note", order_by: { field_key: "At", direction: "desc" } }

package/docs/examples.md

@@ -35,7 +35,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "booked_on", "type": "date"},
         {"alias": "parts_ready_on", "type": "date"},
         {"alias": "arrived_on", "type": "date"},
-        {"alias": "hours", "type": "number", "format": "number", "unit": "h"},
+        {"alias": "hours", "type": "number", "notation": {"style": "unit", "unit": "h"}},
         {"alias": "report", "type": "text", "format": "markdown"},
         {"alias": "completed_on", "type": "date"}
       ]
@@ -120,7 +120,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "booked_on", "type": "date"},
         {"alias": "parts_ready_on", "type": "date"},
         {"alias": "arrived_on", "type": "date"},
-        {"alias": "hours", "type": "number", "format": "number", "unit": "h"},
+        {"alias": "hours", "type": "number", "notation": {"style": "unit", "unit": "h"}},
         {"alias": "completed_on", "type": "date"}
       ]
     },
@@ -379,7 +379,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         },
         {"alias": "on_hand", "type": "number"},
         {"alias": "minimum", "type": "number"},
-        {"alias": "price", "type": "number", "format": "currency", "currency": "USD"},
+        {"alias": "price", "type": "number", "notation": {"style": "currency", "currency": "USD"}},
         {"alias": "supplier_page", "type": "text", "format": "link"},
         {"alias": "last_counted", "type": "date"},
         {"alias": "counted_by", "type": "select_member"},
@@ -394,7 +394,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "quantity", "type": "number"},
         {"alias": "shipped", "type": "number"},
         {"alias": "picked", "type": "number"},
-        {"alias": "unit_price", "type": "number", "format": "currency", "currency": "USD"},
+        {"alias": "unit_price", "type": "number", "notation": {"style": "currency", "currency": "USD"}},
         {"alias": "amount", "type": "formula"},
         {"alias": "category", "type": "lookup"}
       ]
@@ -493,7 +493,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "phone", "type": "text"},
         {"alias": "website", "type": "text", "format": "link"},
         {"alias": "account_manager", "type": "select_member"},
-        {"alias": "credit_limit", "type": "number", "format": "currency", "currency": "USD"},
+        {"alias": "credit_limit", "type": "number", "notation": {"style": "currency", "currency": "USD"}},
         {"alias": "outstanding", "type": "rollup"},
         {"alias": "over_limit", "type": "formula"},
         {
@@ -746,7 +746,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         {"alias": "sale", "type": "select_member"},
         {"alias": "xu_ly", "type": "select_member"},
         {"alias": "can_bo_sung", "type": "boolean"},
-        {"alias": "phi_dich_vu", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "phi_dich_vu", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {
           "alias": "loai_can",
           "type": "select",
@@ -758,7 +758,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           ]
         },
         {"alias": "can_boc", "type": "text"},
-        {"alias": "hoa_hong_sale", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "hoa_hong_sale", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {"alias": "ngay_thu_phi", "type": "date"},
         {"alias": "ngay_nhan_giay_to", "type": "date"},
         {"alias": "ngay_lap_ho_so", "type": "date"},
@@ -812,7 +812,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
         },
         {"alias": "ngay_sinh", "type": "date"},
         {"alias": "cccd", "type": "text"},
-        {"alias": "thu_nhap", "type": "number", "format": "currency", "currency": "VND"}
+        {"alias": "thu_nhap", "type": "number", "notation": {"style": "currency", "currency": "VND"}}
       ]
     },
     {
@@ -828,7 +828,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           ]
         },
         {"alias": "ho_so", "type": "select_record_link", "target_entity": "ho_so", "cardinality": "one"},
-        {"alias": "so_tien", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "so_tien", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {
           "alias": "hinh_thuc",
           "type": "select",
@@ -1471,7 +1471,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           "target_entity": "nha_cung_cap",
           "cardinality": "one"
         },
-        {"alias": "so_tien", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "so_tien", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {"alias": "han_thanh_toan", "type": "date"},
         {
           "alias": "trang_thai",
@@ -1520,6 +1520,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
       "register": {
         "columns": ["nguoi_de_nghi"],
         "filters": ["nguoi_de_nghi", "du_an"],
+        "group": "du_an",
         "create": ["noi_dung", "loai", "du_an", "nha_cung_cap", "so_tien", "han_thanh_toan", "nguoi_de_nghi"],
         "readings": [
           {
@@ -1595,7 +1596,7 @@ Every key: the `model` reference, at the pages each section names under **Keys**
           "type": "select",
           "options": [{"alias": "thu", "color": "green"}, {"alias": "chi", "color": "rose"}]
         },
-        {"alias": "so_tien", "type": "number", "format": "currency", "currency": "VND"},
+        {"alias": "so_tien", "type": "number", "notation": {"style": "currency", "currency": "VND"}},
         {"alias": "bien_dong", "type": "formula"},
         {
           "alias": "doi_tuong",

package/docs/filters.md

@@ -49,8 +49,9 @@ pass the whole list in one condition rather than splitting it across calls.
 | `equals`, `not_equals`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to` | a number |
 | `is_empty`, `is_not_empty` | none |
 
-A number whose field states `unit_field` or `currency_field` is read in each row's own unit or
-currency, so a comparison on it states `unit_option`: the option of that select its value is in.
+A number whose `notation` reads its unit or currency on each row (`{ "per_row": <select> }`) is
+read in each row's own, so a comparison on it states `unit_option`: the option of that select its
+value is in.
 Rows holding another option are out; measured units of one dimension convert.
 
 ```

package/docs/workflows.md

@@ -6,9 +6,10 @@ Only the forms below are accepted; anything else is refused at save with the lin
 what to write instead. A save that succeeds may still return `warnings` — advisory hints such as a
 loop that may never end. Read them.
 
-The same grammar serves an automation, a table's lifecycle workflow and an app's workflow. Only an
-automation's source opens with a trigger declaration; a lifecycle workflow takes its trigger from its
-table and event, an app workflow from the app that calls it.
+The same grammar serves an automation, a table's lifecycle workflow and an app's workflow, and the
+expressions of a table check. Only an automation's source opens with a trigger declaration; a
+lifecycle workflow takes its trigger from its table and event, an app workflow from the app that calls
+it.
 
 ## Triggers
 
@@ -63,10 +64,10 @@ await send_email({
 | return | `return({ status: "success" \| "error", message: <expr>, field_errors: { ... }? });` |
 | validate | `validate({ checks: [{ fail_when: <expr>, field_key: "...", message: <expr> }, ...] });` |
 
-`return` is a call, not a JavaScript `return` statement. `validate` refuses the write when a check's
-`fail_when` is truthy; the check's `field_key` names the control its message lands on — a field of the
-trigger table in a lifecycle workflow; in an app workflow a declared input, or the `fld_` key of a
-field on a table the body names; in an automation it is not checked.
+`return` is a call, not a JavaScript `return` statement. `validate` ends the workflow with an error
+when a check's `fail_when` is truthy; the check's `field_key` names the control its message lands on —
+in an app workflow a declared input, or the `fld_` key of a field on a table the body names; a field of
+the trigger table in a lifecycle workflow; in an automation it is not checked.
 
 The name in `const x = await tool({...})` is the step's id; later expressions read its output as
 `x.records`, `x.id` and so on. A `// id: my_step` comment directly above a statement sets an explicit
@@ -122,8 +123,7 @@ step — summarize a record, classify, draft text.
 - `output` — `{ mode: "text" }` resolves to a string; `{ mode: "object", schema }` to a typed object.
 
 Only `x` comes back: in text mode `x` is the string itself, in object mode `x.field` reads a field the
-`schema` declares. The agent's own tool calls are not readable. An agent step cannot give a
-synchronous verdict, so a `before_*` lifecycle workflow refuses it.
+`schema` declares. The agent's own tool calls are not readable.
 
 ## Keys, not names
 
@@ -264,25 +264,6 @@ field when there is none. Use `coalesce(x, fallback)` only for a real fallback v
 
 ## Examples
 
-Refuse a duplicate before it is created (a `before_create` lifecycle workflow; the keys come from
-`get_table`):
-
-```
-const dup = await query_records({
-  table_id: "tbl_orders",
-  filters: { node_type: "group", logic: "and", children: [
-    { node_type: "condition", field_key: "fld_ref", operator: "equals", value: record["fld_ref"] },
-    { node_type: "condition", field_key: "fld_closed_at", operator: "is_empty" },
-  ]},
-});
-
-validate({ checks: [{
-  fail_when: size(dup.records) > 0,
-  field_key: "fld_ref",
-  message: "An open order already has this reference.",
-}]});
-```
-
 Compare a link by id. Display text is not unique, and a link reads as a list of ids — `==` against a
 string is a type error:
 
@@ -302,16 +283,14 @@ if (customer && includes(record["fld_customer"], customer.id)) {
 
 A lifecycle workflow is bound to one table and one event, and its source has no `on({...})` line:
 
-- `before_create` / `after_create` — a create, and a draft's submit (the moment it becomes a record).
-- `before_update` / `after_update` — every field edit, a draft's included: a `before_update` check
-  runs while someone fills in a draft, not only once it is submitted.
-- `before_delete` / `after_delete`.
+- `after_create` — a create, and a draft's submit (the moment it becomes a record).
+- `after_update` — every field edit, a draft's included.
+- `after_delete`.
 
-A `before_*` workflow runs before the write commits and may refuse it, with `validate` or
-`return({ status: "error", ... })`; its errors come back as field errors on the write. It cannot
-`wait`, `wait_for_event`, `wait_for_approval` or run an `agent` step. An `after_*` workflow runs after
-the commit, with every step; its errors are logged and never fail the write. An `after_update`
-workflow that writes its own table saves with a `loop_potential` warning: its write fires it again.
+A lifecycle workflow runs after the write commits, with every step; its errors are logged and never
+fail the write. What refuses a write before it lands is a table check (see **Table
+checks**). An `after_update` workflow that writes its own table saves with a `loop_potential`
+warning: its write fires it again.
 
 | reads | on |
 |---|---|
@@ -334,3 +313,63 @@ that cares about some events only skips the rest:
 
 In `if_source`, `runtime.change_origin` is the origin of the write that fired it; in the body, it is
 the workflow's own.
+
+## Table checks
+
+A table check is one condition its table's record writes must not meet, declared beside the table's
+`unique`. It is not a workflow: it reads the write and a few lookups and answers yes or no, so it
+cannot change data. It runs inside the write, on every create, update or delete it is `on`, whichever
+surface makes it — a person, the API, the CLI, an agent, a workflow. A refusal writes nothing and
+answers with the check's message, under its field when the check names one, and names the check.
+
+On the CLI or in chat, `set_table_check` creates one, or changes one when given its `table_check_id`
+and only the parts that change, and `remove_table_check` removes one. `get_table` lists a table's
+checks in the source they are written in.
+
+| part | what it holds |
+|---|---|
+| `on` | the writes it checks: any of `create`, `update`, `delete` |
+| `when` | optional expression; the check runs only on a write where it is truthy. It cannot read lookups. |
+| `lookups` | optional, by name, the rows to read: `{ table_id, filter, limit }`, the filter as `query_records` takes it, `limit` from 1 to 50 (50 when left out). A filter value may read the record. |
+| `fail_when` | expression; truthy refuses the write |
+| `message` | expression for the refusal's text — a fixed text is a quoted string |
+| `field_key` | optional; the field the refusal is shown under |
+
+Every expression is written in the grammar above and reads:
+
+- `record` — the record as it will be stored; on a delete, the record being deleted.
+- `prev_record` — on an update or a delete, the record before.
+- `changes` — on an update, the fields it changes.
+- `lookups.<name>` — in `fail_when` and `message`, the rows that lookup read.
+- `runtime.timezone`, `runtime.workspace_id`, `runtime.organization_id`, `runtime.change_origin` (the
+  write's origin), `runtime.triggered_by_member_id` (the member writing; null for a write no member
+  made), and `now()`.
+
+A check on several operations reads only what all of them carry, so one on creates and updates reads
+neither `prev_record` nor `changes`.
+
+A lookup reads with the access of the member who last saved the check, so saving one requires reading
+every table its lookups read. It reads committed rows: two writes at the same moment can each pass a
+check the other would fail, so values no two rows may share are the table's `unique`, not a check.
+
+A `when`, a lookup or a `fail_when` that cannot decide — it fails, or the write's time runs out —
+refuses the write. A draft is checked when it is submitted, as a create; its edits before that are
+not. A restored record is checked as a create. Cloning a table copies its checks to the member who
+clones it, and is refused when that member cannot read a table a check's lookup reads.
+
+One open order per reference, a row never counting against itself:
+
+```
+{
+  "table_id": "tbl_orders",
+  "name": "One open order per reference",
+  "on": ["create", "update"],
+  "when": "isNull(record[\"fld_closed_at\"])",
+  "lookups": {
+    "same_ref": "{ table_id: \"tbl_orders\", filter: { node_type: \"group\", logic: \"and\", children: [ { field_key: \"fld_ref\", operator: \"equals\", value: record[\"fld_ref\"] }, { field_key: \"fld_closed_at\", operator: \"is_empty\" } ] }, limit: 2 }"
+  },
+  "fail_when": "some(lookups.same_ref, (r) => r.id != record.id)",
+  "message": "\"An open order already has this reference.\"",
+  "field_key": "fld_ref"
+}
+```

package/package.json

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