@lotics/cli 0.318.31 → 0.318.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -31,9 +31,9 @@ app has.
31
31
 
32
32
  | Called | What it says of itself | Takes | Generated for |
33
33
  |---|---|---|---|
34
- | `<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 sources, 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 |
35
- | `<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 sources, none for a Tab whose period reads a date holding a span |
36
- | `<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` |
34
+ | `<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 sources, 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; a root List after the first over an entity, whose chips differ from the first's, adds one of its own, called by its key |
35
+ | `<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, and of each later root List over an entity, called by its key; none over sources, none for a Tab whose period reads a date holding a span |
36
+ | `<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`, and of each later root List over an entity, called by its key |
37
37
  | `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |
38
38
  | `<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 |
39
39
  | `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 |
@@ -78,7 +78,6 @@ the screen already holds.
78
78
  | `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |
79
79
  | `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. | | an app stating `scope` |
80
80
  | `<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 |
81
- | `<rows>_measured_by_<link>` | The share of each <entity> row handed in its <rows> rows add, day by day. | `<entity>_ids` | a Reading stating `planned`, `done` and `measured` |
82
81
  | `<entity>_sub_counts_by_<link>` | How many <entity> rows stand under each <entity> row handed in, through <link>, at each status. | `<entity>_ids` | a record's rows block over a hierarchy (`nests`), for the rows it draws |
83
82
  | `<entity>_plan_places` | Every <place> the <entity> rows stand at, with what the plan draws of each. | | a register laid out as a `plan`: the places its rows stand at |
84
83
  | `<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` |
@@ -117,7 +116,7 @@ run_app_query {"app_id":"app_…","alias":"order_list","params":{"status_is":"op
117
116
  | `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 |
118
117
  | `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 |
119
118
  | `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` |
120
- | `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 |
119
+ | `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`), `sum` (a number column, answered as `__sum`) and `avg` (a number column averaged over the group's rows that hold one, answered as `__avg`), 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 |
121
120
  | `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 |
122
121
  | `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 |
123
122
 
@@ -286,8 +285,8 @@ Acts: every figure or list whose definition is the business's own (open orders,
286
285
  It reads under the app's `rows` (every row, where the app states none of the table) and, on the app's own table, exactly the rows its list reads —
287
286
  so never the table of an app whose List reads `sources`, several tables. A condition reading an
288
287
  optional param narrows nothing when the call leaves it out; no param compares a number read in each row's
289
- own unit or currency, or a date holding a span. `"reading"` in place of `"fields"` returns a count or a sum —
290
- `{ "value": "price", "by": "item" }` — as a Reading does. A Query, a Workflow and
288
+ own unit or currency, or a date holding a span. A Query returns its `fields`; a caller counts, sums or
289
+ averages them with `run_app_query`'s `aggregate`. A Query, a Workflow and
291
290
  a Reading's `key` take no name the app generates (`reference/app.generated-name`).
292
291
 
293
292
  **A workflow** — a write no Act of the record makes, typed in the app's tree and its code set on the app:
@@ -305,9 +304,9 @@ a Reading's `key` take no name the app generates (`reference/app.generated-name`
305
304
  }
306
305
  ```
307
306
 
308
- `set_workflow` sets its code (`workflows`). A query set on an app outside
309
- the tree (`set_app_queries`, on the CLI) is removed by the next write, whose answer notes it; declared as a Query
310
- node, it is the tree's. A caller sees the description and
307
+ `set_workflow` sets its code (`workflows`). A query the app holds that
308
+ the tree does not declare is listed by `get_app` as `unstated_queries` and removed by the next write,
309
+ whose answer notes it; declared as a Query node, it is the tree's. A caller sees the description and
311
310
  each input's `description` and nothing else, so each says what the value is and what leaving it out means;
312
311
  the check notes one that says nothing.
313
312
 
@@ -1,6 +1,6 @@
1
1
  # App architecture — a worked split
2
2
 
3
- The rule that splits a business into apps is in `first_build`, § 3: one app per main entity, and everything that belongs to a row on that row's page. This is one split it produces, settled before any tree is written, since it decides who sees what.
3
+ The rule that splits a business into apps is in `first_build`, § 3: one app per main entity, and everything that belongs to a row on that row's page. This is one split it produces, settled before any tree is written.
4
4
 
5
5
  One bakery's wholesale arm, five people, seven apps:
6
6
 
@@ -38,4 +38,4 @@ record, one page. The owner reads the figures each register leads with. Each app
38
38
  }
39
39
  ```
40
40
 
41
- Then `set_access` gives each person only the apps beside their name (`first_build`, § 3). How each tree is composed is `design`.
41
+ Then `set_access` gives each app to all who work its rows (`first_build`, § 3). How each tree is composed is `design`.
@@ -5,17 +5,29 @@ under an alias — a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):
5
5
 
6
6
  | Binding | Declared with | The app calls it with | An agent calls it with |
7
7
  |---|---|---|---|
8
- | Query | `set_app_queries` (CLI) | `useQuery("<alias>", params?)` | `run_app_query` |
8
+ | Query | `set_app`, a `Query` node | `useQuery("<alias>", params?)` | `run_app_query` |
9
9
  | Workflow | `set_workflow` | `useWorkflow("<alias>")({ ...inputs })` | `run_app_workflow` |
10
10
 
11
11
  Each runs under the app's authority (`{ type: "app", app_id }`), the app owner's reach — never the
12
12
  calling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next
13
13
  call uses it. `get_app` lists an app's aliases with their params and inputs.
14
14
 
15
- Each reader returns a fingerprint of what it read — `get_workflow`'s `version`, and on the CLI
16
- `get_app_query`'s `sha` — and a write built on that read passes it back:
17
- `set_app_queries`' `expected_shas` (alias → `sha`), and `set_workflow`'s `expected_version`. The write is
18
- refused, and writes nothing, when the binding changed since; omit it for an unconditional write.
15
+ Each reader returns a fingerprint of what it read, and a write built on that read passes it back:
16
+ `get_workflow`'s `version` as `set_workflow`'s `expected_version`, and `get_app`'s version as `set_app`'s
17
+ `base_version_id`. The write is refused, and writes nothing, when it changed since; omit it for an unconditional write.
18
+
19
+ ## API apps
20
+
21
+ An API app is one a customer's own server calls. It holds only `Query` and `Workflow` nodes, so no address serves it, and it cannot be shared publicly.
22
+
23
+ 1. `set_app` with a tree of those nodes, naming the tables they read in `uses`. The answer carries the link where an admin creates its key, and `get_app` states it again.
24
+ 2. `set_workflow` sets each workflow's code.
25
+ 3. An admin opens the link and creates an app key (`lak_…`). It reaches this app alone and only calls it; no other route and no tool answers it, and that can never be widened. Its secret is shown once, so it goes straight into the server's secrets, and no tool creates or reads one.
26
+ 4. To promise the shape to that server, an admin's `set_app` states `{ "app_id": "…", "api_published": true }`: a numbered contract and an OpenAPI document, and a later write that would break it is refused.
27
+
28
+ The server sends `Authorization: Bearer lak_…` to `POST /v1/apps/{app_id}/queries/{alias}` and `POST /v1/apps/{app_id}/workflows/{alias}/execute`. The answer holds what the app declares, with each row's own id and timestamps: no member's email, no field id, and a failed run a generic message beside its `execution_id`. A browser cannot call them, and a key never goes in a page.
29
+
30
+ A `Query` node reads one table or List with `rows` or `list`. A wider read states the whole query as `ast`, below.
19
31
 
20
32
  ## Queries
21
33
 
@@ -36,10 +48,13 @@ A save checks what a deploy checks: every table is in this workspace and within
36
48
  every projected, filtered and sorted field resolves, every param token is declared, and a key a
37
49
  node's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.
38
50
 
39
- On the CLI, `set_app_queries` takes `{ <alias>: <declaration> }`, one alias or several, and merges each: send
40
- only the fields you change, `null` clears `params`, `description` or `templates` (never `ast`), and a
41
- new alias needs an `ast`. Any other field is refused by name. An alias it omits is kept.
42
- An alias set to `null` is unbound, under the same `expected_shas`; `get_app_query` reads one back.
51
+ `set_app` states one as a `Query` node: `{ "type": "Query", "key": "<alias>", "ast": { … } }`, beside `params`,
52
+ `description` and `templates`. On an app made from a tree it stands among the tree's `children`, and a `nodes` patch
53
+ replaces its `ast`, `params` or `templates` whole. On an app that serves
54
+ code, `nodes` takes `{ "<alias>": { … } }` and merges each: send only the fields you change, `null` clears `params`,
55
+ `description` or `templates` (never `ast`), a new alias needs an `ast`, and an alias set to `null` is unbound. Its
56
+ `children` state the list whole, each query entire, and an alias they omit is unbound. Any other field is refused by
57
+ name, and `get_app`'s `body` reads them back by alias.
43
58
 
44
59
  ### The query tree
45
60
 
@@ -105,7 +120,7 @@ name → `{ type, required?, description?, …per type }`. An entry is required
105
120
  | `array` | `items` — one entry |
106
121
 
107
122
  Nesting stops at depth 8. A `field`-form select tracks the field's options as they change; an
108
- inline `options` set is a fixed list.
123
+ inline `options` set is a fixed list. A query's select param takes an option by alias, label or key, each condition reading it by its own field's options, and a value that is none of them is refused naming the options.
109
124
 
110
125
  ## Outputs
111
126
 
@@ -154,7 +154,7 @@ people differ; a table with none is read whole by everyone the app is shared wit
154
154
  | Team leads see people, not salaries | an app that draws no salary field — what it does not show, no one reads through it |
155
155
 
156
156
  A child read under a ruled row states its own rule, through its link to the parent; only a status history inherits.
157
- Admins are not narrowed in an app; someone on a public link, signed in as no one, reads no row a `self` clause would
157
+ An admin and the app's owner are narrowed like anyone, and the write says so when a rule hides rows from them. Someone on a public link, signed in as no one, reads no row a `self` clause would
158
158
  choose. An app never reads past its owner's own access. A table's own `read_scope` governs opening the table directly.
159
159
  Working inside one row of a folder (`scope`) narrows the view, not who may read: a branch app shared with every manager
160
160
  still states the branch rule.
@@ -179,7 +179,7 @@ The contract, and nothing more:
179
179
  - The app is a static bundle on the app host and reaches data only through the SDK.
180
180
 
181
181
  What the app reads and writes is bound on the app, never in the project: `lotics run
182
- set_app_queries` binds named queries, `lotics run set_workflow` a workflow body, and each mints a
182
+ set_app` binds named queries (`app_bindings`), `lotics run set_workflow` a workflow body, and each mints a
183
183
  version. `useQuery("<alias>")` and `useWorkflow("<alias>")` call them. A deploy uploads the build
184
184
  and carries every binding forward unchanged.
185
185
 
@@ -249,4 +249,4 @@ standing process the app expects that agent to carry out belongs there and nowhe
249
249
  **A caller outside the team gets its own app.** Sharing an app publicly, or giving an API key
250
250
  access to it, reaches every alias the app declares; no alias can be held back. So whatever
251
251
  outsiders may call is a SECOND app over the same tables: only the queries they may read and the
252
- workflows they may run. The desk the team works in stays a separate, private app.
252
+ workflows they may run. The desk the team works in stays a separate, private app. One only a server calls is an API app: `lotics docs app_bindings` § API apps.
@@ -28,7 +28,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
28
28
  | `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or stdin behind the `-` sentinel (`cat args.json \| lotics run <tool> -`) — both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). **Stdin is asked for, never guessed.** `lotics run <tool>` with no payload runs the tool with no arguments and returns at once. `lotics report` takes the same sentinel. In PowerShell use `@file`: quotes inside an inline argument are consumed by the shell, and the CLI reports the JSON it received with its quotes gone — the error names both escapes. |
29
29
  | `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |
30
30
  | `lotics run <tool>` — **file cells** | A file in a tool's result carries its `fil_…` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file — this surface resolves no URL for a cell. Reach the bytes with `lotics file download <file_id>`, which takes the id straight from the cell; the text output says so whenever a result carries one. |
31
- | — | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_query`) and every one that builds: `set_tables` (a list of table documents), `set_app` (one app), `set_app_queries`, `set_workflow`. A command exists only for work that touches a local file: `app apply`, `app create --custom`, `app pull`, `app deploy`. |
31
+ | — | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_query`) and every one that builds: `set_tables` (a list of table documents), `set_app` (one app), `set_workflow`. A command exists only for work that touches a local file: `app apply`, `app create --custom`, `app pull`, `app deploy`. |
32
32
  | — | **An app's queries and workflows take more than their params and inputs** (`lotics docs agent_surface`). `run_app_query '{"app_id","alias","params"}'` also takes `filters` and `sort` over the query's output columns, `fields` (the columns to return), `count` with `count_by` or `count_where`, `aggregate`, `limit` (200 rows at most; 50 where none is stated) and `cursor`, and `runs` — up to 20 reads in one call, each `{"alias", …}`, a refused one answered with its `error`; one call's rows total at most 262,144 bytes. `export: {"key", …narrowing}` instead of the read arguments makes the file an app's Export makes (`lotics docs agent_surface`). `run_app_workflow '{"app_id","alias","inputs"}'` also takes `dry_run: true` — a rehearsal on the real inputs, nothing written or sent; the answer is what the run would return, with the reads it made under `dry_run.reads`, the calls it would make under `dry_run.writes` and the papers it rendered under `dry_run.papers` and the parts of the answer it could not say under `dry_run.unpredicted`; a workflow no dry run is offered of answers `status: "not_previewed"` — and `runs` — up to 50 runs in order, the first refused, failed or not previewed ending the call, an input `{"from_run": <index>, "path": "data.<key>"}` reading an earlier run's answer. |
33
33
  | — | **The exit code reports the WORK, not just the call — for the tool that RUNS one.** `run_app_workflow` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`, or `not_previewed` — a dry run asked for and not given) 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. |
34
34
  | `lotics run <tool> '<json>' -o <dir>` | Also save every **signed link** the answer carries — an object with a `url`, a `filename` and the `expires_at` its signature ends at, at any depth, such as `screenshot_app`'s images. Each is fetched into `<dir>` (created if missing) under its `filename`, taking a free spelling beside a file of that name already there, and a link's `snapshot` text is written beside it as `<name>.txt`. The written paths follow the answer on **stdout**, one per line (on stderr under `--json`, whose stdout stays the one object). A link is signed for an hour; one the store no longer serves exits non-zero. A workspace file states no `expires_at` and is left to `lotics file download`. |
@@ -47,8 +47,8 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
47
47
  | `lotics knowledge rm <id...>` | Delete docs via `set_knowledge` (`{ knowledge_doc_id, delete: true }`), one call per id: each must be a live doc you manage that no app or workflow names, and the command reports which succeeded and which failed. Sharing and history are kept. The REST execute path does not gate `needsApproval`, so this runs unattended. |
48
48
  | `lotics knowledge restore <id...>` | Bring deleted docs back via `set_knowledge` (`{ knowledge_doc_id, restore: true }`), one call per id: each must be a deleted doc you manage, and the command reports which succeeded and which failed. Refuses the no-argument form. |
49
49
  | `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`) and links `[path]` (default `./<name>`, made when absent) to it by writing `package.json#lotics` (the app and its workspace, which is how `app deploy` in that directory finds both) — into the project's own `package.json` when it has one, every other key kept, otherwise a `package.json` holding the link alone. Nothing else is written and nothing is installed: the project is yours. `app deploy` needs `@lotics/app-sdk` (React 19) and an `npm run build` that writes a static `dist/` with an `index.html`. A directory already linked to an app is refused before the app row exists. The app has no version until the first `lotics app deploy`. `--custom` is required: a JSON app is made by `lotics app apply` (the tool `set_app`). The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` once the project installs it. |
50
- | `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (the identity alone) as its source; an app whose stored tree does not read in this release is pulled as it is stored, with a warning giving the reason `get_app` gives (where the stored value is not a JSON object, nothing is pulled and the reason is the error); an app that shows the caller no body (the caller does not author it, or it has no version) is refused. **A JSON app**: the tree is written as JSON to `[path]` (a directory receives `./<name>.app.json`; default `./<name>.app.json`), and the app's id and current version beside it in `<file>.lotics.json` (`{ "app_id": "…", "version_id": "…", "digest": "…" }`, the digest being the file as the CLI last left it; a record without all three is refused by `app apply`, naming `lotics app pull`) — a custom-code project records both in `package.json#lotics`, a single file has no such place — so the next `lotics app apply <file>` edits that app, and is refused if the app has since moved past that version. An existing file is overwritten only when its `.lotics.json` names this same app and the file is unchanged since it was last pulled or applied; a file with edits, or whose record names the app but no digest, is refused, naming `--force`, which overwrites it. `--force` is a flag of `app pull` alone. `--json` prints `{workspace_id, app_id, path, outcome}`. **A custom-code app**: its live source, as a project ready to deploy on it. The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** — but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`GET /v1/apps/{id}/types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). |
51
- | `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ "body": … }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` — a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `"type": "App"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour) only, and no `<file>.lotics.json` records it, since an identity write makes no version — its source deploys with `app deploy`. **The file is never rewritten**: a node the tree leaves out draws as the rows call for it and is stored nowhere (`lotics docs design`). It prints what `set_app` answered and reports its `outcome`: its notes and findings, every finding at once, and the saves, adds and Deletes the write grants and removes. **`--check` sends `dry_run`** (a flag of `app apply` alone, as is `--app`) — what would refuse the tree, and what it would grant and remove — and writes nothing, the file and its sibling included; an `outcome` of `refused` exits 1. A tree the app already has, or one `set_app` answers `unchanged`, records the version the app stays at in the sibling. **To go back to an earlier version, apply the earlier tree again.** Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, app_id, outcome, write}`, `outcome` being `set_app`'s: `created`, `updated`, `unchanged` or `refused` (with `--check`, what it would be). |
50
+ | `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (its identity and Query nodes) as its source; an app whose stored tree does not read in this release is pulled as it is stored, with a warning giving the reason `get_app` gives (where the stored value is not a JSON object, nothing is pulled and the reason is the error); an app that shows the caller no body (the caller does not author it, or it has no version) is refused. **A JSON app**: the tree is written as JSON to `[path]` (a directory receives `./<name>.app.json`; default `./<name>.app.json`), and the app's id and current version beside it in `<file>.lotics.json` (`{ "app_id": "…", "version_id": "…", "digest": "…" }`, the digest being the file as the CLI last left it; a record without all three is refused by `app apply`, naming `lotics app pull`) — a custom-code project records both in `package.json#lotics`, a single file has no such place — so the next `lotics app apply <file>` edits that app, and is refused if the app has since moved past that version. An existing file is overwritten only when its `.lotics.json` names this same app and the file is unchanged since it was last pulled or applied; a file with edits, or whose record names the app but no digest, is refused, naming `--force`, which overwrites it. `--force` is a flag of `app pull` alone. `--json` prints `{workspace_id, app_id, path, outcome}`. **A custom-code app**: its live source, as a project ready to deploy on it. The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** — but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`GET /v1/apps/{id}/types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). |
51
+ | `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ "body": … }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` — a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `"type": "App"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour) and, where the file states `children`, its Query nodes, which replace every query it holds; a file stating none leaves its queries alone and no `<file>.lotics.json` records it, since an identity write makes no version — its source deploys with `app deploy`. **The file is never rewritten**: a node the tree leaves out draws as the rows call for it and is stored nowhere (`lotics docs design`). It prints what `set_app` answered and reports its `outcome`: its notes and findings, every finding at once, and the saves, adds and Deletes the write grants and removes. **`--check` sends `dry_run`** (a flag of `app apply` alone, as is `--app`) — what would refuse the tree, and what it would grant and remove — and writes nothing, the file and its sibling included; an `outcome` of `refused` exits 1. A tree the app already has, or one `set_app` answers `unchanged`, records the version the app stays at in the sibling. **To go back to an earlier version, apply the earlier tree again.** Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, app_id, outcome, write}`, `outcome` being `set_app`'s: `created`, `updated`, `unchanged` or `refused` (with `--check`, what it would be). |
52
52
  | `lotics app deploy [-m <message>]` | **Build this directory and upload it as a new version of the live app.** Rewrites `.lotics/` with the declarations of the app's live bindings (`GET /v1/apps/{id}/types`, replacing each file there), then runs the project's `npm run typecheck` (warned about when absent; a type error in the app's own files stops the deploy, one inside an installed package is reported and does not) and `npm run build`, tars the source (without `node_modules`, `dist`, `.git`, `*.tsbuildinfo`) and `dist/`, and posts both to `POST /v1/apps/{id}/versions` on the version `package.json#lotics.current_version_id` names, then stamps the new one there. The version carries the app's queries, workflows, agents and capabilities forward unchanged — those are written through their tools. A project with no `build` script, or whose `package.json#lotics` still declares `queries`, `workflows`, `agents` or `capabilities`, is refused before anything is built; the refusal names the tool that sets each. **A 409 because another version went live since this directory's last deploy** (a deploy from elsewhere, a rollback) prints the server's sentence and the version that is live, and names `lotics app pull`: run in this directory, it brings an unedited project up to date, and lists the files a project with edits changed, to carry over into a fresh pull. `-m` (or a bare positional) is the version's message, optional. The workspace comes from `package.json#lotics.workspace_id` unless `--workspace` / `LOTICS_WORKSPACE` names another. |
53
53
  | `lotics docs` \| `lotics docs <area>[/<section>]` \| `lotics docs [<area>[/<section>]] --grep <text>` | **This CLI's own references, carried inside the binary** — the model reference, this index, and every doc under `docs/` — so the doc a reader opens describes the binary answering, listed by the job a reader comes to do. Capped at ONE PAGE: a doc that does not fit prints its opening and the addresses of what it holds (`lotics docs <area>/<section>`, each section's size beside it, or a table's row names), and every address prints within a page. **A reference the binary's copy lacks, or a part of one the server serves, is read from the server's `docs` tool** with this machine's credential, after the copy's refusal — a page the server added since this binary was built, which a server refusal can cite. A name matching more than one reference, or a part missing from a guide to this CLI, is answered by the copy alone. **`--grep` searches the references the server serves** (not this CLI's own guides, which it refuses), with this machine's credential, narrowed to the area or section named: literal text unless `--regex`; a literal search that finds nothing while the pattern read as an expression matches (`a|b`) returns those lines under a note saying so, and `--literal` keeps the literal zero; with `--case-sensitive`, `--diacritic-insensitive`, `--context-lines <n>` and `--limit <n>` — the dialect the knowledge lines of `get_workspace` with `search` are read in — each hit under the address that opens its page; any of those options without `--grep` is refused. A custom-code app's SDK reference ships inside `@lotics/app-sdk` in the app's `node_modules`. |
54
54
  | `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script — the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe — a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |
@@ -55,7 +55,7 @@ express rather than quietly picking the nearest value.
55
55
 
56
56
  A value read through a link or a lookup reads exactly as the same field would on its own row: an option written by its alias in
57
57
  a body and read as its key, a member or a link by its id. A value a check matches
58
- across tables is a link to one table: two selects never compare, and a save that compares them is refused.
58
+ across tables is a link to one table: two selects never compare, and a save that compares them is refused, in a check's lookup too. A filter or a write on another table's select takes a value read from this one by its alias, else its label.
59
59
 
60
60
  A lookup reads as one flat list of the values it looks up, in a check and in every body: `first(record.x)` is the one value through a one-row link and `includes(record.x, v)` asks whether any row holds `v`; two selects never compare, so a value matched across tables is a link to one table. A single member, a single select, a number or a text reads as the value itself, and `first(...)` of one is refused when the body is saved. A rollup that adds up (a sum, a count) over no rows is 0, never empty, as `sum` over an empty list is; a min, a max or an average over no rows is empty.
61
61
 
package/docs/design.md CHANGED
@@ -5,8 +5,7 @@ tree states COMPOSITION — which fields, lists and acts each job's screen holds
5
5
  one way per concept. A node the tree leaves out draws its default, from the table's facts (`records`, the stage, the
6
6
  write rules): a List's Readings band, the stage buttons, the picture, a Record's Sections. State a node to change it,
7
7
  or `false` at it to turn it off (`"readings": false`, a Record's `"row": { "image": false }`). A drawn Field is a control unless it
8
- or its entity is read-only (`edit: false`); a stepped status never is, since Acts move it. Each prop's keys are in `reference`, a treatment
9
- worked in a whole workspace is `examples/<treatment>`, and which apps a business needs is `first_build`, § 3.
8
+ or its entity is read-only (`edit: false`); a stepped status never is, since Acts move it. Which apps a business needs is `first_build`, § 3.
10
9
 
11
10
  **The visual bar.** Every screen is judged against it; a miss is a change to the tree.
12
11
 
@@ -16,8 +15,9 @@ worked in a whole workspace is `examples/<treatment>`, and which apps a business
16
15
  - What needs attention leads the row: `records.mark` on a select or a computed category (a formula stating its options;
17
16
  where it is empty, its seat is blank). A yes that needs attention (papers still owed) is a `Check` of its List over a
18
17
  yes/no formula, in the warning tone on the row's line; every other yes reads in the success tone.
19
- - A list's columns: the name and its lead, the status, then the one or two columns the job reads on every row. Each
20
- fact once: no column repeats the mark, status, subtitle or title.
18
+ - A list's columns: the name and its lead, the status, then the columns the job reads on every row, as many as fit a desk. Each
19
+ fact once: a column the row draws itself stands once. A generated number (`autonumber`) as the title yields
20
+ the row's name to the subtitle's first part and stands first on its line.
21
21
  - A list worked by a date states `sort` on that date's column, newest first; without one, a register reads newest made
22
22
  first and a record's child List in the order its rows were added.
23
23
  - Someone is a face wherever they are read: a link to a table stating `records.party` draws its row's face; a member
@@ -30,13 +30,172 @@ worked in a whole workspace is `examples/<treatment>`, and which apps a business
30
30
  means something.
31
31
  - Every app states its tile's `color`, apart from the workspace's other apps where it can be.
32
32
  - The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the
33
- carrier, the authority) in the Section where that work happens, kept visible after its stage, and the source of a
33
+ carrier, the authority) in the Section where that work happens, and the source of a
34
34
  figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere.
35
35
 
36
36
  **Each shot answers:** can the person find their row? Is what needs doing first, on the row's lead? Is anything
37
37
  repeated or empty? Is anyone shown without their face? Is every paper visible? Across the workspace: can each app be
38
38
  told apart by its own screen, and does any app hold a second entity behind tabs? A failed answer is a change to the tree.
39
39
 
40
+ <!-- generated:start words -->
41
+
42
+ **The words most builds state.** A node's page holds its rules and every other word: `reference/list-node`, `reference/records`, `reference/field`.
43
+
44
+ **Table**
45
+
46
+ - `ref` (alias): A created table's handle in this call
47
+ - `label` (text, required): The table's name in the workspace
48
+ - `singular` (text): One row of this table, in the business's own words
49
+ - `title` (alias): The alias of the field that names a row wherever a link or a record shows one
50
+ - `fields` (map of alias → Field, required): The table's columns, each under its alias, which is its key here and so is never stated inside it
51
+ - `records` (any value): How a row is recognised
52
+ - `checks` (map of alias → table check (`workflows/table-checks`)): The conditions a write of the table's rows may not meet, each under its alias
53
+ - `unique` (list (at least one) of list of alias (at least one)): Sets of fields whose values no two live rows share
54
+
55
+ **Any field**
56
+
57
+ - `label` (text, required): The field's name in the workspace
58
+ - `required` (boolean): Refuse a record whose cell for this field is empty
59
+ - `default_from` (text): Copied when a record is made off the row a one-row link of this entity names
60
+
61
+ **`number` field**
62
+
63
+ - `notation` (notation): How the figure reads
64
+ - `min` (number | text): Refuse a create or update whose value is below this
65
+
66
+ **`select` field**
67
+
68
+ - `options` (list of Select option (at least one), required): The choices, in the order every picker and every ladder lists them
69
+ - `multi` (boolean): Allow multiple selections
70
+
71
+ **`link` field**
72
+
73
+ - `table` (text, required): The table the link points at
74
+ - `multi` (boolean, required): Whether a row links to one row or many
75
+ - `pair` (`true` | alias): Makes the link two-way
76
+
77
+ **`formula` field**
78
+
79
+ - `expression` (text, required): The expression, over fields of THIS entity by alias in braces
80
+ - `output_type` (`"number"` | `"text"` | `"date"` | `"datetime"` | `"boolean"` | `"select"`): Holds a formula to the type its readers need
81
+
82
+ **`rollup` field**
83
+
84
+ - `via` (alias, required): The alias of a link of this table to roll up from
85
+ - `op` (operation, required): The operation over the linked rows
86
+ - `field` (alias): The alias of the field on the linked table the operation reads
87
+
88
+ **`lookup` field**
89
+
90
+ - `via` (alias, required): The alias of a link of this table to look up through
91
+ - `field` (alias, required): The alias of the field on the linked table to show
92
+
93
+ **`autonumber` field**
94
+
95
+ - `prefix` (text): Literal prefix prepended to every display value (e.g. 'KH-' → 'KH-001')
96
+
97
+ **`records`**
98
+
99
+ - `subtitle` (list of alias (1–2)): Up to two fields read under the title wherever a row is drawn (a code, a date, a party)
100
+ - `figure` (alias): The one number the row stands for, read at its right (a total, a quantity left)
101
+ - `status` (Status): The stage a row moves through, a single select, drawn in the record's head, or its Side where the Side states it
102
+ - `due` (list of alias (at least one)): Dates that are deadlines (stored, or computed as a date)
103
+ - `image` (alias): A files field that pictures the row
104
+ - `party` (`"person"` | `"organization"` | `"organisation"`): What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier)
105
+ - `limits` (map of alias → (alias | number)): A number read against a bound
106
+ - `starts` (map of alias → `"today"` | `"me"`): What a field of a row being added starts at, where that start is certain
107
+ - `mark` (alias): A single select (or a lookup of one through a one-row link), or a formula that states its options, whose option leads the row wherever a mark leads it
108
+ - `settled` (alias): A yes/no of the row (stored, a formula: an invoice paid in full, or looked up through a one-row link: a line settled with its parent) that ends its deadlines
109
+
110
+ **`records.status`**
111
+
112
+ - `field` (alias, required): The single select that is the row's state, its options in the order the work goes through them, read as steps by itself on a record whose parts state no `at`
113
+ - `closed` (list of alias (at least one)): Options that end the work
114
+ - `history` (text): A table every write that sets or moves the status appends one row to (its link to this table, the new status, the moment and who)
115
+ - `dates` (map of alias → alias): Option alias → a date field of this entity the record write path stamps with the moment a row moves into that option, or is made at it
116
+ - `stages` (map of alias → Stage): Option alias → who owns that stage and how long it should take
117
+
118
+ **App**
119
+
120
+ - `key` (alias, required): The app's alias, its name among apps
121
+ - `name` (text, required): The job, in the words of the people who do it
122
+ - `children` (list of (List | Sheet | Query | Workflow) (at least one)): The App's Views in order
123
+ - `color` (colour): The launcher tile's colour
124
+ - `pages` (list of Record (at least one)): The page the rows of an entity open, one per entity, each a Record stating its `entity`
125
+
126
+ **List**
127
+
128
+ - `entity` (alias, required): The table whose rows the List draws
129
+ - `create` (boolean | list of alias (at least one)): The fields an add asks
130
+ - `columns` (list of (alias | Edit column)): Fields read after the row's title
131
+ - `label` (text): The register's name in the app's lists and tab strip
132
+ - `filters` (list of (alias | Tiered filter) (at most 3)): Fields the reader narrows by every day, beside the stage chips
133
+ - `children` (list of (Tab | Reading | Export | Act | List) (at least one)): Its Tabs, band Readings, Exports and Acts over ticked rows or every row in view
134
+ - `key` (alias): Names the List among its siblings and in a Query's `list`
135
+ - `sort` (Sort key | list of Sort key (at least one)): The rows' order
136
+ - `layout` (layout): A word, or an object stating one layout with its data
137
+ - `remove` (boolean): Rows offer a Delete
138
+ - `search` (list of alias (at least one)): Fields the search box reads
139
+ - `where` (narrowing): A fixed narrowing on the server, for every reader
140
+ - `group` (alias): A field the rows stand grouped by
141
+ - `expect` (alias | Expect): What a record should hold, shown before it does
142
+ - `opens` (narrowing): The view the register opens on, a chip the reader may take away
143
+
144
+ **Record**
145
+
146
+ - `entity` (alias, required): The table whose rows open on this page
147
+ - `children` (list of (alias | Field | Fieldset | Section | Side | Outside | List | Reading | Statement | Act | Check) (at least one)): Parts (Section, Side), or for a one-part record its Fields, Fieldsets, Lists, Readings and Statements directly
148
+ - `add` (`false` | list of alias (at least one)): What a new row asks where a picker of this entity offers one, anywhere in the App
149
+ - `row` (Record row): How the App reads this entity's rows wherever it lists them
150
+ - `door` (`"page"` | `"drawer"`): How a row opens, on a page or in a drawer
151
+
152
+ **Section**
153
+
154
+ - `title` (text, required): The part's heading
155
+ - `key` (alias): Unique among its siblings
156
+ - `children` (list of (alias | Field | Fieldset | List | Reading | Statement | Act) (at least one)): What the part draws, in reading order
157
+ - `at` (list of alias (at least one)): Options of the record's status during which this part is the work now
158
+ - `when` (condition): Drawn only while this holds
159
+
160
+ **Field**
161
+
162
+ - `field` (alias, required): The field's alias
163
+ - `edit` (boolean): Shows a value nobody changes here
164
+ - `label` (text): The heading of the field's gallery or prose block, where it draws as one
165
+ - `block` (boolean): Gives a field room of its own
166
+
167
+ **Act**
168
+
169
+ - `key` (alias, required): The act's name
170
+ - `label` (text, required): The verb, as the reader says it
171
+ - `when` (condition): The act works only while this holds
172
+ - `set` (map of alias → value): What the act writes
173
+ - `asks` (list of (alias | `{ "field": alias, "starts": "today" | "me" }` | Asked input) (at least one)): What the reader states on pressing
174
+ - `confirm` (`true` | text): The press asks first
175
+ - `requires` (list of alias (at least one)): Fields filled first, each drawn where the act stands
176
+ - `template` (alias): A document template it makes a file from
177
+ - `into` (alias): The record's files field keeping the document
178
+ - `owner` (`"field"` | `"link.field"` | `{ "group": id }`): Who presses it
179
+ - `workflow` (alias): The workflow it runs for what `set` cannot say
180
+ - `danger` (`true`): The act destroys or cannot be undone
181
+
182
+ **Check**
183
+
184
+ - `field` (alias, required): A yes/no or text formula of the page's entity
185
+ - `on` (`"all"` | list of (`"update"` | alias) (at least one)): What the standing check refuses
186
+ - `resolve` (alias): An Act on one row of this entity that clears it
187
+
188
+ **Reading**
189
+
190
+ - `label` (text): What the figure is called
191
+ - `value` (alias | `{ "avg": alias }`): A number field summed over the rows, or `{ avg }` averaged over the rows holding one
192
+ - `by` (alias | Tiered filter): Splits the rows into parts
193
+ - `where` (narrowing): Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date's `{ "now": true }` is read when the rows are), whose field is `{ "empty": true | false }`, or whose member field holds the reader (`{ "me": true }`)
194
+ - `entity` (alias): The List's rows
195
+ - `over` (alias): The date that places a row in time
196
+
197
+ <!-- generated:end words -->
198
+
40
199
  ## Look at it
41
200
 
42
201
  After an apply, `screenshot_app` draws each app as its people see it — the register, and a record by its `path` (`screen`
@@ -51,39 +210,39 @@ send the tree saved before the change as `body` with `app_id`, nulling an App pr
51
210
  A treatment named below is one the answer of `set_app` notes when the rows call for it and nothing draws it, naming the
52
211
  node that would state it; a note refuses nothing. Each kind of row's view is chosen before its List is written:
53
212
 
54
- | The rows are | The treatment | Its props |
213
+ | The rows are | The treatment | Its own page |
55
214
  |---|---|---|
56
- | People or organisations | `records.party`, with a photo or logo as its `image` | `reference/records` |
57
- | Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/records`, `reference/cards` |
215
+ | People or organisations | `records.party`, with a photo or logo as its `image` | |
216
+ | Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/cards` |
58
217
  | Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `reference/calendar`, `reference/layouts` |
59
- | Ranked by a figure, or worked by a date | List `sort: {"field": …, "desc": true}` on that column | `reference/list-node` |
218
+ | Ranked by a figure, or worked by a date | List `sort: {"field": …, "desc": true}` on that column | |
60
219
  | Booked on a resource | List `layout: {"lanes": {"by": …}}`, and the table's `no_overlap` | `reference/lanes`, `reference/write-rules` |
61
220
  | A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |
62
- | Opened to be worked on | the Record's Sections, in the order the work reaches them — `at` where it moves in steps; fields only one kind of row holds (a delay's cause, a safety issue's hours lost) in a Section whose `when` names that kind | `reference/section-node` |
63
- | Rows that each belong to another row | a child List on that row's Record, with `create` and `remove` — and a child's own rows a List in that child's page, as deep as the data goes; a List with `same` where read-only | `reference/list-node` |
221
+ | Opened to be worked on | the Record's Sections, in the order the work reaches them — `at` where it moves in steps; fields only one kind of row holds (a delay's cause, a safety issue's hours lost) in a Section whose `when` names that kind | |
222
+ | Rows that each belong to another row | a child List on that row's Record, with `create` and `remove` — and a child's own rows a List in that child's page, as deep as the data goes; a List with `same` where read-only | |
64
223
  | A related row's value on the list (the newest contract's end date) | a `lookup` field of the table, ordered, as a column | `reference/lookup` |
65
- | Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register's Readings | `reference/act-node`, `reference/status`, `reference/reading-node` |
66
- | Counted over a period | the register's Tabs over one `period`; a Tab's `totals` for a child's sums before, during and through it; an open Tab's `where` reads only what was true at the period's end, never a status the row moves on from | `reference/tab-node` |
67
- | Papers a case gathers | a List with `expect`; the papers made, an Act's `templates` | `reference/list-node`, `reference/act-node` |
224
+ | Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register's Readings | |
225
+ | Counted over a period | the register's Tabs over one `period`; a Tab's `totals` for a child's sums before, during and through it; an open Tab's `where` reads only what was true at the period's end, never a status the row moves on from | |
226
+ | Papers a case gathers | a List with `expect`; the papers made, an Act's `templates` | |
68
227
  | A plan of spans | List `layout: {"gantt": {"start": …}}` | `reference/gantt` |
69
228
  | Stood at a place on a plan, flat or in 3D — pallets, bins | List `layout: {"plan": …}`; places state `plan_place` | `reference/plan` |
70
- | Checked item by item against a standard | a List with `checklist: {"photo": …, "clause": …, "failed": […], "passed": …}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names — a measured verdict, no task or status needed), its photo and the clause it is checked against; with `expect` on the standard's items, each item is a line marked the same way and filled by the block's columns | `reference/list-node` |
71
- | A place before and after the work | a List with `compare: {"before": …, "after": …}`: two files fields read side by side, or two value fields read as one struck-then-new column | `reference/list-node` |
229
+ | Checked item by item against a standard | a List with `checklist: {"photo": …, "clause": …, "failed": […], "passed": …}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names — a measured verdict, no task or status needed), its photo and the clause it is checked against; with `expect` on the standard's items, each item is a line marked the same way and filled by the block's columns | |
230
+ | A place before and after the work | a List with `compare: {"before": …, "after": …}`: two files fields read side by side, or two value fields read as one struck-then-new column | |
72
231
  | Spots on a drawing | `records.pin: {"on": …, "x": …, "y": …}` on the spots' table: a record listing rows that link to them draws the picture with a numbered pin at each; the picture is the `on` row's `records.image` | `reference/record-places-pins-and-cadence` |
73
232
  | Photos that must be taken on site | `records.on_site: {"photos": […]}`: a photo taken through the camera keeps where the device stood, and a record holding one taken away says so | `reference/record-places-pins-and-cadence` |
74
233
  | The real size of the thing (a carton, a piece of furniture, a pallet) | `records.size: {"across": …, "along": …, "up": …}`: three number fields in one length unit, read as one fact "400 × 300 × 250 mm" after the subtitle; a plan register draws each box at that size | `reference/record-places-pins-and-cadence`, `reference/plan` |
75
234
  | A number painted on the thing, or a barcode or QR code on it | `records.scan: "iso6346"` or `"text"` (read off one photo by an agent), or `"code"` (decoded on the device, no agent): the title read on a phone, beside each search matching it | `reference/record-places-pins-and-cadence` |
76
235
  | Who did what on which day | List `layout: "roster"` with the List of its cells inside | `reference/roster` |
77
- | Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record's `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` — a link a member makes of the record, never a seat; the link's page names the record only where the Outside states its title's field | `reference/outside-node` |
78
- | Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | `reference/reading-node` |
79
- | A record's own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (two to eight tiles) | `reference/reading-node` |
236
+ | Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record's `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` — a link a member makes of the record, never a seat; the link's page names the record only where the Outside states its title's field | |
237
+ | Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | |
238
+ | A record's own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (up to eight tiles) | |
80
239
  | Rows that are each a place a record is sent | a List with `expect` on the link to those places and `post`: each ticked, the post written there and read as its feed shows it | `reference/publish-desk` |
81
- | Papers an agent reads, where the owner asked for one | an Act's `intake` with `fills` | `reference/act-node` |
82
- | Calls and visits | an Act's `record` | `reference/act-node` |
83
- | 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`, its body returning a changeset in `data.review` | `reference/act-node` |
84
- | Documents covering lines | a List with `under` | `reference/list-node` |
85
- | Rows on file a record takes in | a List with `pick` | `reference/list-node` |
86
- | One owner's question across jobs | an App of Tabs and Readings and no register | `reference/app-node` |
240
+ | Papers an agent reads, where the owner asked for one | an Act's `intake` with `fills` | |
241
+ | Calls and visits | an Act's `record` | |
242
+ | 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`, its body returning a changeset in `data.review` | |
243
+ | Documents covering lines | a List with `under` | |
244
+ | Rows on file a record takes in | a List with `pick` | |
245
+ | One owner's question across jobs | an App of Tabs and Readings and no register | |
87
246
 
88
247
  What these nodes do not state, a long-form writing page or a bespoke tool, is a custom-code app (`lotics app create <name> --custom`, `building_an_app`), never a new node.
89
248
 
@@ -94,7 +253,8 @@ What these nodes do not state, a long-form writing page or a bespoke tool, is a
94
253
  `records.party` is `"person"` where the rows are people (a contact, a patient, a driver) and
95
254
  `"organization"` where they are companies (a customer, a supplier, a carrier). Every surface drawing one of
96
255
  its rows then draws a face: its `image` (a photo, a logo), else its initials. Without it, a person is drawn as a thing. A workspace
97
- member is a `member` field, and is drawn by their face already. Worked: `examples/party`.
256
+ member is a `member` field, and is drawn by their face already. A column holding a link to several rows of people,
257
+ or several members, draws their faces as a stack that names them on hover. Worked: `examples/party`.
98
258
 
99
259
  #### Image
100
260
 
@@ -195,7 +355,7 @@ register; a register whose job is a strict order, a first-come queue, states `at
195
355
  Who changed what and when is the platform's audit trail, never a table and never shown by an app. When a stage's moment matters
196
356
  to the business — reported, filtered, printed — it is a date on the row that `records.status.dates` stamps as the row
197
357
  enters the option, whoever writes: the one way a status is timed, and the moment a stage's `within` runs from (each stage, and
198
- each open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated; a move whose
358
+ each open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated (a record whose parts state no `at` draws it as steps by itself: no date fields or formulas copy it); a move whose
199
359
  day may already be past `asks` that date with `starts: "today"`. `records.status.history` names a child the record write path appends one row to per
200
360
  status move (its link to the row, the new status, the moment and who) for a business that reports on every move: moves
201
361
  per person, or time in a stage a row re-enters. An event with facts of its own — a reason, an amount, a signature — is
@@ -206,7 +366,7 @@ stage is signed once per person, read off who moved the row.
206
366
 
207
367
  A List usually opens with one band of figures or a chart, chosen for what that person watches. Its Readings stand above the rows and its filters and read the rows under the open tab, never narrowed by the controls below them. Lead with the job's headline number —
208
368
  its exception as a formula's yes/no in a Reading's `where` (what is short), never a stage the
209
- status chips already count, nor the overdue rows the register's summary line counts from `records.due` — then at most the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted, and so is a sum: a status register with no single select to split by gets no default band.
369
+ status chips already count, nor the overdue rows the register's summary line counts from `records.due` — then at most the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted; so is a sum, but for the one a status register with a money figure leads with by default: that figure over its open rows. A register with no such figure and no single select to split by gets no default band.
210
370
  A grid (`by` and `across`) reads on a Sheet. A Sheet — a View of Readings at the App's root, beside its Lists or alone —
211
371
  answers one owner's question across jobs, each Reading windowed by the reader's period (the App's `period`), and a
212
372
  List on it hands over the rows to act on. Many Readings stand on several Sheets, each a View the reader picks. A
@@ -234,6 +394,12 @@ an app (`first_build` § 3).
234
394
 
235
395
  #### Sections
236
396
 
397
+ A record is a head, its parts and at most one Side. From three parts it shows one part at a time; fewer stack. State each
398
+ part whole for the work there: a field may stand in any number of parts, and a field an Act requires draws beside it
399
+ unstated. A step may hold nothing but its name. What a person needs in view at every part (who it is for, how to reach
400
+ them) goes in a Side: it leaves the head and stays on the rows. The status stands in the head or the Side, never a
401
+ Section. `row` changes how the app's rows read, never a page.
402
+
237
403
  The Record's Sections, in the order the work reaches them: the fields people write, a Field per paper the record
238
404
  keeps, a child List per child, the Acts at each one's foot. A register's `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record's, and a figure that is final only from a stage is a Field of that stage's Section, never a column read on every row at every stage. A register laid out in time (calendar, lanes, roster) opens the
239
405
  default record: every field a person writes. Behaviour belongs in an Act.