@lotics/cli 0.315.17 → 0.316.0

package/docs/agent_surface.md

@@ -6,19 +6,23 @@ reach them, over MCP and as `lotics run <tool>`:
 
 | Tool | Answers |
 |---|---|
-| `get_app_capabilities` | The app's queries and workflows by alias: each one's description, its params or inputs with their types and legal values, and under a query's line its output columns (`returns`) — beside what each table they name holds, in its owner's words |
+| `get_app` | The app's `catalog`: its queries and workflows by alias, each one's description, its params or inputs with their types and legal values, and under a query's line its output columns (`returns`) — beside what each table they name holds, in its owner's words |
 | `run_app_query` | The rows, a count or the groups of one query — or of several in one call |
-| `run_app_workflow` | One write — or several in order — or a preview of it that writes nothing |
+| `run_app_workflow` | One write — or several in order — or a dry run of it that writes nothing |
 
-An app stated in a model generates this surface from the model; the model declares what the screen never
-asks (§ Declaring more). An app's logs (`logs`) are part of it: a log's list, its rows by id, its record's
-blocks and its acts are queries and workflows of the same app, named by the log's entity as the register's
-are by its own — `get_app_capabilities` lists them in the one roster, and nothing of a log is another app's. What only a log reads or runs answers the organization's own members alone, never a caller through the app's public link. A custom-code app's surface is the queries and workflows bound on it
-(`lotics docs app_bindings`).
+An app generates this surface from its tree; Query and Workflow nodes declare what the screen never
+asks (§ Declaring more). An app's logs (its further Lists at the root, which a change may add at any time) are part of it: a log's list, its rows by id, its record's
+Lists and its Acts are queries and workflows of the same app, named by the log's table as the register's
+are by its own — `get_app` lists them in the one roster, and nothing of a log is another app's. What only a log reads or runs answers the organization's own members alone, never a caller through the app's public link. A custom-code app's surface is the queries and workflows bound on it
+(`app_bindings`).
+
+## Finding what an app offers
+
+`get_workspace` maps the workspace. Its `search` matches the keys and descriptions of the Query and Workflow nodes an app declares, and the app's line names the matching keys; it never matches the generated `act_`, `create_` or `update_` aliases. `get_app` then gives the contracts. An agent runs a declared node before it falls back to `aggregate_records`.
 
 ## What every app generates
 
-A name in angle brackets is the model's alias for that thing. `get_app_capabilities` lists the ones a given
+A name in angle brackets is the app's alias for that thing; an `<entity>` is the alias of a table the app reads. `get_app` lists the ones a given
 app has.
 
 ### Queries
@@ -27,24 +31,27 @@ app has.
 
 | Called | What it says of itself | Takes | Generated for |
 |---|---|---|---|
-| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per `register.filters` field holding one value — a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter — none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter — none over `books`, none for a looked-up link or member, none for a number read in each row's own unit or currency | every entity the app draws; the filter params on the app's own entity alone |
-| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list's; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each of `register.tabs`; none over `books`, none for a tab whose period reads a date holding a span |
-| `<entity>_totals_<tab>` | The <child> rows added per <entity> row, by "<link>", over the period from `from` to `to`, dated by "<date>": . | `from`; `to` | each of `register.tabs` stating `totals` |
+| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per List `filters` field holding one value — a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter — none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter — none over Books, none for a looked-up link or member, none for a number read in each row's own unit or currency | every entity the app draws; the filter params on the app's own entity alone |
+| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list's; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each Tab of the register; none over Books, none for a Tab whose period reads a date holding a span |
+| `<entity>_totals_<tab>` | The <child> rows added per <entity> row, by "<link>", over the period from `from` to `to`, dated by "<date>": . | `from`; `to` | each Tab of the register stating `totals` |
 | `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |
-| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each block of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |
-| `<child>_by_<link>_days` | The <child> rows of the <entity> rows handed in whose "<day>" falls from one day to another. | `<entity>_ids`; `from`; `to` | `register.roster` |
+| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each List of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |
+| `outside_<key>_one` | One row of <entity> by its id. | `record` | each Outside: the record a link opens, projected to the fields the Outside states |
+| `outside_<key>_<child>` | The <child> rows under one <entity>, through "<link>". | `record` | each List of an Outside: the rows under the record a link opens, projected to the List's columns |
+| `<child>_by_<link>_days` | The <child> rows of the <entity> rows handed in whose "<day>" falls from one day to another. | `<entity>_ids`; `from`; `to` | a roster List: the List of its cells |
 | `<entity>_<link>_pick` | The <target> rows "<link>" may point at, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a written link a write rule narrows (`options_where`, `same`) |
-| `<child>_by_<link>_picks` | The <child> rows no <entity> holds through "<link>" yet, that one <entity> may pick, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a block that picks existing rows into the record |
-| `register_reading_<n>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list's; `from`? / `to`? where the reading states `over`, or its `tab` is dated `in` a period; `to` where its `tab` is of rows `open` on a day | each of `register.readings` by its place among them, counted from 0 — but the work against its plan (`progress`), which reads the list's own rows; none over `books`. A reading stating `alias` is called by it |
-| `dashboard_reading_<n>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each of a dashboard's readings, counted from 0; a reading stating `alias` is called by it |
-| `block_reading_<n>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each reading, list or funnel block of the record, by its place among the record's blocks, counted from 0; a reading stating `alias` is called by it |
-| `<entity>_register_reading_<n>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list's; `from`? / `to`? where the reading states `over` | each of a log's `register.readings` by its place among them, counted from 0, named by the log's entity; a reading stating `alias` is called `<entity>_<alias>` |
-| `<entity>_block_reading_<n>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each reading, list or funnel block of the record a row of a book or of a log opens, by its place among that record's blocks, counted from 0, named by the book's or the log's entity |
-| `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading's | a metric whose value `records.limits` bounds: the bound's sum, beside the reading's own |
-| `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list's | a `register.export` that fills a template |
-| `<entity>_export_rows_of_<book>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list's | a report of some of an app's `books`: their rows alone, each book named in turn |
+| `<child>_by_<link>_picks` | The <child> rows no <entity> holds through "<link>" yet, that one <entity> may pick, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a List with `pick`: it picks existing rows into the record |
+| `<reading key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list's; `from`? / `to`? where the reading states `over`, or its `tab` is dated `in` a period; `to` where its `tab` is of rows `open` on a day | each Reading of the register List, called by its `key` (`register_reading_<n>`, n counted from 0, only for an app stored before trees) — but the work against its plan (Progress), which reads the list's own rows; none over Books |
+| `<reading key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each Reading of a dashboard, called by its `key` (`dashboard_reading_<n>` only for an app stored before trees) |
+| `<reading key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each Reading of the record and each List or funnel on it, called by its `key` (`block_reading_<n>` only for an app stored before trees) |
+| `<entity>_<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list's; `from`? / `to`? where the reading states `over` | each Reading of a log's List, called `<entity>_<key>` (`<entity>_register_reading_<n>` only for an app stored before trees) |
+| `<entity>_<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a list stating `same` | each Reading of the record a row of a Book or of a log opens and each List or funnel on it, called `<entity>_<key>` by the Book's or the log's entity (`<entity>_block_reading_<n>` only for an app stored before trees) |
+| `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading's | a Reading whose value `records.limits` bounds: the bound's sum, beside the Reading's own |
+| `<reading>_on_hand` | <label> / <on-hand entity>: how many <on-hand entity> rows there are, per "<field>". Each row carries `<field>`, `__count`. | none: every row of its entity its `where` keeps, whatever the place | a Reading with `on_hand` (a shortfall): the on-hand rows' groups, beside the Reading's own |
+| `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list's | an Export of the register that fills a template |
+| `<entity>_export_rows_of_<book>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list's | an Export over some of an app's Books: their rows alone, each Book named in turn |
 | `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |
-| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads — the rows with no <place> counted apart. |  | a `plan` register: its places' counts of present rows |
+| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads — the rows with no <place> counted apart. |  | a register laid out as a `plan`: its places' counts of present rows |
 
 <!-- generated:end queries -->
 
@@ -53,10 +60,8 @@ splits by, or per day. Each row carries the alias of each field it splits by, `_
 day, `__count`, and `__sum` where it sums a number; its description states which. An average is `__sum`
 over `__count`, both over the rows holding a value.
 
-A reading that states no `alias` is called by its place, so moving it in the model changes the name it is
-called by. A place that generates no query keeps its number, so the names may skip one. A reading an agent
-or a published API calls states its `alias` (`lotics docs model/readings`). A log's reading is called by the
-log's entity before either name: `<entity>_register_reading_<n>`, or `<entity>_<alias>`.
+A Reading is called by its `key` (`model/reading-node`), so moving it in the tree changes no name. A log's Reading is called by the
+log's table before the name: `<entity>_<key>`.
 
 A register reading's query reads the rows it names, whatever a screen has open: the rows of its `tab` where
 it states one, every tab's where it states none — its description says which. One placed in time (`over`)
@@ -64,19 +69,19 @@ reads every day unless the call states `from` or `to`.
 
 ### Queries the screen runs for itself
 
-They run like any other, and `get_app_capabilities` leaves them out: each feeds one control, and takes ids
+They run like any other, and `get_app` leaves them out: each feeds one control, and takes ids
 the screen already holds.
 
 <!-- generated:start screen-queries -->
 
 | Called | What it says of itself | Takes | Generated for |
 |---|---|---|---|
-| `<child>_<link>_target` | One <entity> row by its id, where a <child> row's "<link>" may point at it. | `<entity>_id` | a picking block whose link a write rule narrows |
+| `<child>_<link>_target` | One <entity> row by its id, where a <child> row's "<link>" may point at it. | `<entity>_id` | a List with `pick` whose link a write rule narrows |
 | `<entity>_<field>_values` | Each "<field>" the <entity> rows hold, once, most held first, narrowed by what the reader typed. | `search`? | a text field a write rule offers values to (`suggest`) |
 | `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |
 | `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. |  | an app stating `scope` |
 | `<task>_progress_by_<link>` | How many <task> rows each <entity> row handed in holds, at each status. | `<entity>_ids` | rows whose task rows are counted done |
-| `<rows>_measured_by_<link>` | The share of each <entity> row handed in its <rows> rows add, day by day. | `<entity>_ids` | a `progress` reading stating `measured` |
+| `<rows>_measured_by_<link>` | The share of each <entity> row handed in its <rows> rows add, day by day. | `<entity>_ids` | a Progress node stating `measured` |
 | `<lane>_lanes` | The <lane> rows of one <scope entity>, each a lane of the board. | `<scope entity>_id` | a lanes board inside an app stating `scope` |
 | `<entity>_same_<link>` | The <entity> rows naming one "<link>". | `same`; `before` where its line reads rows before a moment | a statement line that carries rows (`parts`) |
 
@@ -91,32 +96,29 @@ the screen already holds.
 | `create_<entity>` | Opens one row of <entity>. | every field the add asks, and the link it files the row under | an entity the app adds rows of |
 | `update_<entity>` | Changes one row of <entity>; every input but the row is optional, and one left out is left as it is. | `record_id`, and each field a person edits — a files field or a link to several rows as `<field>_added` / `<field>_removed` | an entity the app edits |
 | `remove_<entity>` | Removes one row of <entity>. | `record_id` | an entity the app removes rows of |
-| `act_<act>` | <label> — on one row of <entity>, refused where its conditions do not hold. | `record_id` — `record_ids` on an act over several rows — and what the act asks | each of `acts` that names no workflow of its own |
-| `archive_<act>` | Hands back every file of <label> on one row of <entity> as one archive. | `record_id` | an act making a set of papers (`templates`) |
-| `record_activity` | Lists one record's activity, newest first: each save with its fields before and after and who made it, and whether the caller may put it back. `next` is the `after` of the next page. | `record_id`; `after`? | every register app, unless `record.activity` is `false` |
-| `record_activity_undo` | Puts back one change entry of a record's activity, as the caller's own save, each field where the record still holds what the entry wrote. The fields kept are handed back with why. | `record_id`; `entry_id` | every register app, unless `record.activity` is `false`, where the app edits that entity |
-| `<workflow>_<book>` | The workflow of that name as one of the app's `books`, or a log of it, runs it, where its own table or page makes it differ. | that workflow's | an app stating `books` or `logs` |
+| `act_<act>` | <label> — on one row of <entity>, refused where its conditions do not hold. | `record_id` — `record_ids` on an act over several rows — and what the act asks | each Act that names no workflow of its own |
+| `archive_<act>` | Hands back every file of <label> on one row of <entity> as one archive. | `record_id` | an Act making a set of papers (`templates`) |
+| `<workflow>_<book>` | The workflow of that name as a Book of the app, or a log of it, runs it, where its own table or page makes it differ. | that workflow's | an app with Books or logs |
 
 <!-- generated:end workflows -->
 
-A workflow the model declares (`workflows`) and an act that names its own are called by the alias the model
-gives them.
+A Workflow node is called by its `key`; an Act that names its own `workflow` is called by that workflow's alias, and every other Act by `act_<key>`.
 
 ## Calling a query
 
 ```
-lotics run get_app_capabilities '{"app_id":"app_…"}'
-lotics run run_app_query '{"app_id":"app_…","alias":"hire_list","params":{"status_is":"opt_…","due_back_to":"2031-03-14"}}'
+get_app {"app_id":"app_…"}
+run_app_query {"app_id":"app_…","alias":"order_list","params":{"status_is":"open","due_on_to":"2031-03-14"}}
 ```
 
 | Argument | Does |
 |---|---|
-| `params` | The query's declared params. A required one is always sent; an optional one left out narrows nothing. A select takes an option's value, a link a record id, a member a member id, a date `yyyy-mm-dd` |
-| `filters` | Narrows the result further, by the query's output columns (`lotics docs filters`) |
+| `params` | The query's declared params. A required one is always sent; an optional one left out narrows nothing. A select takes the option's alias as `get_app` lists it in `select(label=alias|…)` — a link a record id, a member a member id, a date `yyyy-mm-dd` |
+| `filters` | Narrows the result further, by the query's output columns (`filters`) |
 | `fields` | The output columns to return, in place of all of them; each row then holds them and the id of the record it is |
 | `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 |
+| `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), `bands` (a number column of `by` grouped by its breakpoints), 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. Buckets are by day only: a period's total is one call per period, with `from` and `to` or a date filter |
 | `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 |
 
@@ -131,7 +133,7 @@ take are the ones on the query's `returns` line.
 A list's params are how a person narrows that register: `search`, the row's id on an app that works inside
 one row (`scope`), and a param for each filter the register states that one value or a range narrows. A
 filter with no param — on a looked-up link or member, on a number read in each row's own unit or currency,
-on a date holding a span, or on a register of several tables (`books`) — is narrowed by `filters`, where a
+on a date holding a span, or on a register of several tables (Books) — is narrowed by `filters`, where a
 number condition names the unit its value is in as `unit_option`, an option of the figure's select by label
 or key. Each tab of a register is a query of its own, taking the list's params and the period its rows are
 read over.
@@ -139,50 +141,54 @@ read over.
 ## Calling a workflow
 
 ```
-lotics run run_app_workflow '{"app_id":"app_…","alias":"act_check_out","inputs":{"record_id":"rec_…"},"preview":true}'
-lotics run run_app_workflow '{"app_id":"app_…","alias":"act_check_out","inputs":{"record_id":"rec_…"}}'
+run_app_workflow {"app_id":"app_…","alias":"act_hand_over","inputs":{"record_id":"rec_…"},"dry_run":true}
+run_app_workflow {"app_id":"app_…","alias":"act_hand_over","inputs":{"record_id":"rec_…"}}
 ```
 
 | Argument | Does |
 |---|---|
 | `inputs` | The workflow's declared inputs. An update takes the record and only the fields that change |
-| `preview` | `true`: nothing is written, and the answer is what the run would return, with the calls it would make — or `status: "not_previewed"` where the workflow cannot be previewed (§ A preview) |
-| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not previewed ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run's answer at that path. A run states its own `preview`, or takes the call's |
+| `dry_run` | `true`: the run is made and taken back, so nothing is kept, and the answer is what the run would return, with the calls it would make — or `status: "not_previewed"` where the workflow cannot be dry-run (§ A dry run) |
+| `as_member` | With `dry_run`, for a workspace admin: the run is judged as that member would press it — their stage owners, row rules and app access — and writes nothing. Anyone else is refused; `dry_run` on a record tool takes it the same way, and so do `query_records`, `aggregate_records` and `get_record`, which answer what that member would read |
+| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not dry-run ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run's answer at that path. A run states its own `dry_run`, or takes the call's. Dry runs one after another share their rows, taken back together, so a run reads what the one before it made; a run reads a dry run's answer only from a run dry-run in that stretch |
 
 ```
-lotics run run_app_workflow '{"app_id":"app_…","runs":[
-  {"alias":"create_hire","inputs":{"customer":"rec_…","machine":"rec_…","due_back":"2031-03-14"}},
-  {"alias":"act_check_out","inputs":{"record_id":{"from_run":0,"path":"data.record_id"}}}
-]}'
+run_app_workflow {"app_id":"app_…","runs":[
+  {"alias":"create_order","inputs":{"customer":"rec_…","item":"rec_…","due_on":"2031-03-14"}},
+  {"alias":"act_hand_over","inputs":{"record_id":{"from_run":0,"path":"data.record_id"}}}
+]}
 ```
 
-## A preview
+## A dry run
 
-A previewed run makes every read the run would make and none of its writes. Its answer carries `status`,
-`message`, `field_errors` and `data` as the run would return them, and under `preview`:
+A dry run is the run itself on the real inputs, taken back: it is made in a transaction that is rolled back, so a read after a write reads that write, a branch or a loop walks the values the run would hold, and a call fed by an earlier call's answer gets it. No row, number, event, audit entry or table workflow outlives it. A write of the workspace's rows is made by its table — checks, write rules, stage owners — and the first refusal is the dry run's answer. A connected service's read-only call is made; a service write, a send, a notification or a button that runs another workflow is not, and is answered as a "would" with its payload. A guard (`when`, `requires`, a check, a lock) refuses it with the press's own sentence. A paper it makes is rendered for the answer and its file is removed with the dry run; an act that makes a paper is dry-run like any other, never refused for it. A body that sets the record's status also answers `moves`. Its answer carries `status`,
+`message`, `field_errors` and `data` as the run would return them, and under `dry_run`:
 
 | Key | Holds |
 |---|---|
 | `available` | `true` |
 | `writes` | The calls the run would make that are not reads, in order. The app's owner and an admin, who may read the workflow's body, read each call's `step_id`, `tool_name` and `input`. Another member reads each step that would write once: its `step_id` and `tool_name`, and where the step states them outright, the `table_id` it names and how many `records` it lists |
-| `unpredicted` | The parts of the answer left out — `message`, `field_errors`, `data` — because each reads what a call the preview did not make would answer |
-
-A preview says nothing of a call its target refuses when it is made — a locked record, a required field, a
-permission — nor of what a write sets off in turn: a table's own workflows, its computed fields.
-
-A workflow is not previewed where its body reads the answer of a call the preview does not make, to branch,
-loop, check or feed another call, where it reads a linked record after such a call, where it runs an agent,
-where it waits, where a step cannot be evaluated or sends its call an input the call refuses, and where the
-run is past what one preview walks — its steps, the passes of a loop, its reads or the time it takes. The
+| `reads` | The reads made for real, in order, each with its `input` and what it `returned` (cut at 2,000 characters, `truncated`), for the app's owner and an admin |
+| `papers` | Each paper rendered: its `step_id` and `filename`. The file is not kept |
+| `unpredicted` | The parts of the answer left out — `message`, `field_errors`, `data` — because each reads what a call the dry run did not make would answer |
+
+What a write sets off once it commits — a table's own workflows, its events — does not happen in a dry run.
+
+A workflow is not dry-run where its body reads the answer of a call that leaves the workspace, to branch,
+loop, check or feed another call, where it reads or writes rows after such a call (the run would find them as
+that call left them), where it runs an agent, where it waits, where a step cannot be evaluated, fails
+for a reason that is no table's refusal, or sends its call an input the call refuses, and where the run is past
+what one dry run walks — its steps, the passes of a loop, 50 reads, 50 writes or 20 seconds, which the runs of
+one call share and the database holds it to: a lock wait that outlasts them ends the dry run. The
 answer is then `status: "not_previewed"` with
-`preview: { "available": false, "reason" }`, and nothing ran — within `runs`, it ends the call. The same
+`dry_run: { "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
+`updates` (each with its `record_id`), each row's `data` holding only the fields that change, by field alias, 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; the platform adds a `sha` to every row. Call it again with the same inputs and `approved`,
 `{ "updates": [{ "record_id", "sha" }], "creates": [{ "key", "sha" }] }`, listing the rows to write with the `sha` each
@@ -190,24 +196,28 @@ carries in the proposal, copied as it came — never computed — and the platfo
 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…"}]}}}'
+run_app_workflow {"app_id":"app_…","alias":"match_statement","inputs":{"record_ids":["rec_…"],"statement":"fil_…"}}
+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,
+The answer's `data.applied` names the run (`execution_id`), the records `updated`, what each held before (`previous`), 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 that `execution_id` as its `workflow_execution_id` takes back both. An act over every
+that moved is recorded by the same run. `applied.previous` holds, for each record in `updated`, what the fields the call wrote held before (null for an empty one): `update_records` with it as `set` puts them back, and `delete_records` of a `created` record takes that row away. 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,
-whose step it is, a row the caller may not see. A run that is refused writes nothing and answers
-`status: "error"` with the sentence a person would read as `message`, and under `field_errors` the sentence
-for each input it was refused over. A value of the wrong type, a missing required input and an unknown
+A workflow re-checks on the server what the screen shows of its own act or save: what an act requires, a
+duplicate, whose step it is, a row the caller may not see. Each write it makes also meets the table's own
+rules (a bound, a span, a stage's owner, its lock), which hold on every path a record is written by. A row its table
+locked is refused in every app's act and save, naming who can change it; an app's own Check only makes a row read-only
+in that app. An unlock in an app's run is judged as the member it runs for, never the app's owner. A run refused
+before it writes writes nothing; one whose later write a table's rule refuses keeps the writes before it.
+Either answers `status: "error"` with the sentence a person would read as `message`, and under `field_errors`
+the sentence for each input it was refused over. A value of the wrong type, a missing required input and an unknown
 alias are refused before the body runs: the call itself fails with the sentence, and `field_errors` where
 an input is at fault — within `runs`, a run refused for its inputs answers `status: "error"` in its place,
 and the runs before it stand. A refused read fails the same way, naming the param or the column; within
@@ -215,58 +225,58 @@ and the runs before it stand. A refused read fails the same way, naming the para
 
 ## Declaring more
 
-What a person would ask an agent in the app, and no screen draws, is stated in the model beside the app's
-acts. Both are checked by `check_model` and compiled by `apply_model` (`lotics docs model/queries`, `lotics docs model/workflows`).
+What the business asks an agent in the app again and again, and no screen draws, is stated in the app's tree as Query and Workflow nodes, beside its
+Acts: every figure or list whose definition is the business's own (open orders, what a customer owes, low stock) and every recurring operation (close the month, send to the accounting service, chase overdue invoices), each with a `description` written for an agent. A question asked once stays on `aggregate_records`. A Workflow gets an Act only where a person presses it; work only an agent does has no button. Both are checked and compiled when the tree is written (`set_app`; `model/query-node`, `model/workflow-node`).
 
-**A query** — the rows of one entity, or one figure of them, in the model's own aliases:
+**A query** — the rows of one table, or one figure of them, in the app's own aliases:
 
 ```jsonc
-"queries": {
-  "hires_overdue": {
-    "description": "A customer's hires still out past the day they were due back, longest overdue first.",
-    "params": {
-      "customer": { "type": "record_link", "entity": "customer", "required": false, "description": "Only this customer's hires." },
-      "as_of": { "type": "date", "description": "The day a hire is overdue on: due back before it." }
-    },
-    "rows": "hire",
-    "fields": ["customer", "machine", "due_back", "daily_rate"],
-    "where": { "status": ["out"], "customer": { "param": "customer" }, "due_back": { "to": { "param": "as_of" } } },
-    "sort": { "field": "due_back" }
-  }
+{
+  "type": "Query",
+  "key": "orders_overdue",
+  "description": "A customer's orders still open past the day they were due, longest overdue first.",
+  "params": {
+    "customer": { "type": "record_link", "entity": "customer", "required": false, "description": "Only this customer's orders." },
+    "as_of": { "type": "date", "description": "The day an order is overdue on: due before it." }
+  },
+  "rows": "order",
+  "fields": ["customer", "item", "due_on", "price"],
+  "where": { "status": ["baking"], "customer": { "param": "customer" }, "due_on": { "to": { "param": "as_of" } } },
+  "sort": { "field": "due_on" }
 }
 ```
 
-It reads under the entity's read scope and, on the app's own entity, exactly the rows its list reads —
-so never the entity of an app that states `books`, whose list reads several tables. A condition reading an
+It reads under the table's read scope and, on the app's own table, exactly the rows its list reads —
+so never the table of an app that states Books, whose list reads several tables. A condition reading an
 optional param narrows nothing when the call leaves it out; no param compares a number read in each row's
 own unit or currency, or a date holding a span. `"reading"` in place of `"fields"` returns a count or a sum —
-`{ "value": "daily_rate", "by": "machine" }` — as a reading does. A declared query, a declared workflow and
-a reading's `alias` take no name the app generates (`lotics docs model/app.generated-name`).
+`{ "value": "price", "by": "item" }` — as a Reading does. A Query, a Workflow and
+a Reading's `key` take no name the app generates (`model/app.generated-name`).
 
-**A workflow** — a write no act of the record makes, typed in the model and its body set on the app:
+**A workflow** — a write no Act of the record makes, typed in the app's tree and its code set on the app:
 
 ```jsonc
-"workflows": {
-  "import_bookings": {
-    "description": "Books every hire a booking sheet lists, reusing a hire the sheet already booked.",
-    "inputs": {
-      "sheet": { "type": "file", "description": "The booking sheet, one hire per row." },
-      "booked_by": { "type": "member", "required": false, "description": "Who the hires are booked by; absent, the caller." }
-    },
-    "outputs": { "added": { "type": "number" }, "reused": { "type": "number" } }
-  }
+{
+  "type": "Workflow",
+  "key": "import_bookings",
+  "description": "Books every order a sheet lists, reusing an order the sheet already booked.",
+  "inputs": {
+    "sheet": { "type": "file", "description": "The order sheet, one order per row." },
+    "booked_by": { "type": "member", "required": false, "description": "Who the orders are taken by; absent, the caller." }
+  },
+  "outputs": { "added": { "type": "number" }, "reused": { "type": "number" } }
 }
 ```
 
-`lotics run set_app_workflow` sets its body (`lotics docs workflows`). A query set on a model's app outside
-the model (`set_app_queries`, on the CLI or in chat) is removed by the next apply, whose plan and answer note it; declared under
-its alias in `queries`, it is the model's. A caller sees the description and
+`set_app_workflow` sets its code (`workflows`). A query set on an app outside
+the tree (`set_app_queries`, on the CLI or in chat) is removed by the next write, whose answer notes it; declared as a Query
+node, it is the tree'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.
+the check notes one that says nothing.
 
 **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
+generated per-row workflows. Take a list where the job covers many rows, a record's lines among them. A workflow's code
 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
@@ -274,17 +284,14 @@ cannot be undone behind an approval step.
 
 ## Prove an app as an agent
 
-Run on a throwaway record.
+Run on one of the owner's own rows, moved only as far as its stage; a record made for the run takes a number and a stage move nobody asked for.
 
-1. `get_app_capabilities` — every job the app's `description` names has an alias that does it or reads it.
+1. `get_app` — every job the app's `description` names has an alias that does it or reads it.
 2. `run_app_query` the list with no param, then with each param a person would narrow by; `count: true`
    answers how many without the rows.
 3. `run_app_query` `<entity>_record` with one row's id, and each `<child>_by_<link>` under it.
-4. `run_app_workflow` an act with `preview: true`, then without.
+4. `run_app_workflow` an act with `dry_run: true`, then without.
 5. `run_app_workflow` an act its record is not ready for: the answer is `status: "error"` with the sentence
    the screen would show.
-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:
+6. `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/app_architecture.md

@@ -0,0 +1,39 @@
+# App architecture — a worked split
+
+The questions that split a business into apps are in `first_build`, § 3. This is one split they produce, settled before any tree is written because the split decides who sees what and where each table's rows are worked.
+
+One furniture factory, six people, five apps and a dashboard:
+
+| App (the job's sentence) | Person | Register | Inside it |
+|---|---|---|---|
+| Sales desk: takes an order from quote to dispatch | Sales rep | Orders | Lines, the price book, the quote paper (an Act), the customer as a picker |
+| Production board: runs each work order through its stages | Foreman | Work orders | Steps, machines as lanes, the Acts that move a stage |
+| Purchasing: orders material against shortages | Buyer | Purchase orders | Lines, goods received, the supplier as a picker |
+| Warehouse: receives, issues and counts | Storekeeper | Stock items | Receive and Issue Acts, the log of movements |
+| Quality: inspects each finished lot | Inspector | Inspections | Checklist, photos, a pass or fail Act |
+| Owner's review: the week across jobs | Owner | none (Readings) | Orders late, stock short, margin by month |
+
+Customers, suppliers, machines and the price book are tables with a `records` entry, never apps: each is picked,
+looked up or opened inside the job that uses it. Each app's `name` and `description` is its job's sentence:
+
+```json
+{
+  "type": "App",
+  "key": "sales_desk",
+  "name": "Sales desk",
+  "description": "Takes a customer's order from quote to dispatch.",
+  "children": [{ "type": "List", "entity": "order" }]
+}
+```
+
+```json
+{
+  "type": "App",
+  "key": "production_board",
+  "name": "Production board",
+  "description": "Runs each work order through cutting, assembly and finishing.",
+  "children": [{ "type": "List", "entity": "work_order" }]
+}
+```
+
+Then `set_access` gives the sales desk to the sales group and the production board to the foreman's (`first_build`, § 3). How each tree is composed is `design`.