@hotmeshio/long-tail 0.23.1 → 0.24.0

package/docs/hitl/x-lt-list-schema.md

@@ -17,7 +17,9 @@ Every string is a markdown/text template run through the same `{{domain.path}}`
 | `x-lt-active` | schema | The live item card: `{ title, subtitle?, body?, fields?: [{ label, value }] }` |
 | `x-lt-history` | schema | History column: `{ row: { title, subtitle?, meta? }, limit?, status? }` |
 | `x-lt-columns` | schema | Column definitions for `facet-table` layout: `[{ label, value, format?, priority?, width? }]` |
-| `x-lt-group-by` | schema | `facet-board`: the `"domain.path"` whose value identifies each entity |
+| `x-lt-group-by` | schema | `facet-board`: the `"domain.path"` whose value identifies each entity. `facet-table`: a `"metadata.<key>"` whose rows read as one line (see [Grouped rows](#grouped-rows)) |
+| `x-lt-related` | schema | `facet-table`: named related sets, a row's items or rows in other roles (see [Related sets](#related-sets)) |
+| `x-lt-row-detail` | schema | `facet-table`: sections a row expands into, each listing a related set |
 | `x-lt-card` | schema | `facet-board`: the per-entity card — `{ title, state?, fields?: [{ label, value, format? }] }` |
 | `x-lt-row-action` | schema | The per-row action button: `{ action?, label?, durationMinutes? }` — see below |
 
@@ -144,3 +146,88 @@ Cards are fully interactive (`x-lt-group-by` should be a `metadata.*` path so th
 - **The header magnifier** opens the card's refine dialog — the entity identity plus every field bound to a pure `{{metadata.KEY}}` token, as touch-sized toggle rows. Selections AND into one query: **Filter <role>**, **Search everywhere**, or **Add to filters** (merge into the live set). The same row gesture the facet table carries, always visible — no hover required.
 
 The reference: `examples/seed-fleet-sim.ts` — one advert per machine, a `format: "age"` "Since" field, and role default pins (see [pinned-views.md](pinned-views.md)).
+
+
+---
+
+## Related sets
+
+A `facet-table` row is often a **container**: it holds items (an accumulator or batch row), and other rows are on their way to it. A related set names one of those collections once; columns and row details refer to it by name.
+
+```jsonc
+"x-lt-related": {
+  "contents": { "source": "items" },
+  "coming": {
+    "source": "query",
+    "query": {
+      "segment": "order-prep",                              // or "roles": ["order-prep", "order-check"]
+      "facets": { "destination": "{{metadata.destination}}" },
+      "narrow": { "serviceLevel": "{{metadata.lane}}" },     // applies when the row has a lane
+      "status": "pending"                                   // the default
+    }
+  }
+}
+```
+
+- **`items`**: the row's held items (`envelope.accumulate_items`, or a batch row's `batch_items`). Each item reads through its own `payload` and, for a reciprocal add, through the **reciprocal row** (the item's own escalation).
+- **`query`**: rows in other roles whose metadata contains the row's facets. Facet values are `{{domain.path}}` templates over the host row; a lone token keeps the value's JSON type, so a numeric facet matches a numeric facet. `roles` lists the roles in display order; `segment` names a Pace Board sequence by its first role (the chain composed with `parent_role`), so the sequence and its station titles come from the board. A host whose facets do not resolve shows an em dash and runs no query. `status` defaults to `pending`, which includes claimed rows: a claim leaves a row pending, so an order someone is working still counts as coming. `narrow` facets apply only when the row resolves them, so the facets drive the hierarchy: a lane (a bin carrying `lane`) looks ahead to its own service level only, a bin without lanes to its whole destination, and a grouped tub reads the union of its lanes.
+
+A schema declares up to 4 sets; a query names up to 12 roles.
+
+### Related columns
+
+A column with `related` aggregates its set for each row:
+
+```jsonc
+{ "label": "Holds", "related": "contents", "aggregate": "count",
+  "splitBy": "reciprocal.metadata.serviceLevel", "labels": { "standard": "Standard", "express": "Express" } },
+{ "label": "Coming", "related": "coming", "aggregate": "count", "splitBy": "role" }
+```
+
+The cell reads `3 · Standard 2 · Express 1`: the count, then each split value as a chip. `splitBy` takes:
+
+| Set | `splitBy` |
+|-----|-----------|
+| `items` | `payload.<path>` or `reciprocal.metadata.<key>` |
+| `query` | `role` (chips in sequence order, labeled by role title) or `metadata.<key>` |
+
+`labels` maps split values to display text. A `role` chip opens that role's list filtered to the row's facets.
+
+### Row detail
+
+`x-lt-row-detail` lists sections a row expands into. Each section loads when the row opens, and lists its set's rows with its own columns:
+
+```jsonc
+"x-lt-row-detail": [
+  { "related": "contents", "label": "Holds", "columns": [
+      { "label": "Order",   "value": "{{item.itemKey}}" },
+      { "label": "Service", "value": "{{metadata.serviceLevel}}" },
+      { "label": "Placed",  "value": "{{item.at}}", "format": "date" } ] },
+  { "related": "coming", "label": "Coming", "columns": [
+      { "label": "Order", "value": "{{metadata.orderId}}" },
+      { "label": "At",    "value": "{{escalation.role}}", "format": "role" },
+      { "label": "Since", "value": "{{escalation.created_at}}", "format": "age" } ] }
+]
+```
+
+Item sections read `{{item.itemKey}}`, `{{item.payload.*}}`, `{{item.actor}}` and `{{item.at}}` beside the reciprocal row's domains; query sections read each related row's own domains. `format: "role"` renders a role name as its title. A sub-row opens its own row: an item's reciprocal row, or the related row. A section shows up to its `limit` rows (default 25, at most 100) with the total. The expansion folds with the table at narrow widths and inside a portal panel.
+
+### Grouped rows
+
+On a `facet-table`, `x-lt-group-by: "metadata.<key>"` reads every row sharing that facet as one line, expanding to its members. The list pages by groups, so a page holds whole groups and the total counts groups; a row without the facet is a group of one. Plain columns fold across a group with `group: "first" | "min" | "max" | "sum" | "count" | "distinct"` (default `first`); `min` and `max` compare numbers as numbers and instants as text, and `distinct` lists each value once ("standard, express"). Related columns merge across the group: counts and splits add. A container split finer (one bin per service level in the same tub) keeps reading as one line per tub.
+
+Containment reads by indentation and band: an open line takes a light band; its members are rows of the same table, stepped in under it on a stronger band; a row's detail sections step in past their row on that row's band. The facets carry the hierarchy, so nothing repeats beneath the line that states it: a member leaves blank every value it shares with its group (the group line already shows it), and a detail section drops a column whose every row restates a facet the opened row carries (a lane's look-ahead needs no Service column). A section's first column always stays.
+
+### Scope and cost
+
+Related sets read under the viewer's own read scope, as every list does:
+
+- An item total comes from the host row, so it shows whenever the row does. A split counts only reciprocal rows the viewer reads; when none are readable the cell shows the total with *split restricted*.
+- A query set counts only roles the viewer reads in full. The roles it cannot count are named in the cell's tooltip and in each expansion (*partial*). Granting `read` on those roles is the dial that widens the view.
+- A viewer who cannot read the host role gets a 404.
+
+The server reads the declaration from the role's stored list schema at the version the page rendered, never from the request. `POST /api/escalations/related` aggregates one page of rows in one statement per declared (set, split) pair, whatever the page size or item count; a query set's facet match is served by the metadata GIN index. `POST /api/escalations/related/rows` reads one row's set for its expansion. The list refreshes the sets live on the list tier, from the row's own role events and from the roles each set reads: a query set's roles, and the roles of the reciprocal rows an item split reads, so a held item whose own row changes moves its split. A change refreshes the list when the path that makes it publishes an escalation event on that row's role.
+
+A role's list schema is validated wherever it is written (the role API, the MCP tool, the startup apply): a column naming an undeclared set, an unknown split path, or a malformed query is refused with the path that failed. Keys outside this vocabulary stay free-form.
+
+The reference: `examples/workflows/consolidation/` (roles seeded by `examples/seed-consolidation.ts`). Orders walk two stations and are staged; containers per destination read what they hold by service level and what is coming by station. `npm run consolidation:sim` drives a floor over HTTP; `KEEP=1` leaves it mid-flight.

package/docs/hitl/x-lt-scan.md

@@ -35,16 +35,19 @@ A form field that takes a scan. While a claimed form is open and editable, a sca
 | `expect` | Context paths (`metadata.*`, `envelope.*`, `lookup.*`, …) whose values the field accepts. A path that holds a list contributes every entry. |
 | `expect-error` | The message for a scan outside `expect`; `{{expected}}` lists what the field accepts. Default: `Expected {{expected}}`. |
 | `multiplicity` | Array fields: `"count"` admits a value as many times as `expect` lists it (a part expected twice takes two scans); otherwise each expected value is admitted once. |
+| `prompt` | Array fields: the instruction shown while the field is empty. Default: the field's `description`. |
 
 A string field is replaced by a scan. An array field appends, up to `maxItems`. Manufacturer barcodes compare as GTINs, so a UPC-A matches its 14-digit form.
 
+An array scan field reads as a checklist: its prompt while empty, `n of N` beside the label, and a remove control on each scanned value while the form is editable. `N` is what `expect` admits (each listing under `multiplicity: "count"`, each distinct value otherwise), or `maxItems`, so the count and the admission gate agree. A removed value is admitted again on the next scan.
+
 ## Which field takes the scan
 
 The focused field, when it accepts the scan's scheme. Otherwise the first field in `x-lt-order` that accepts it and still has room. Otherwise the first field that accepts it.
 
 ## Expected values are checked on both sides
 
-A scan outside `expect` shows as an error under the form and leaves the field as it was. The same check runs in the shared validator at submit, so a typed value outside `expect` is a field error in the form and a 422 from the API.
+A scan outside `expect` shows as an error directly under the field that refused it, and leaves the field as it was; an accepted scan shows a confirmation in the same place. Either way the field scrolls into view. The same check runs in the shared validator at submit, so a typed value outside `expect` is a field error in the form and a 422 from the API.
 
 ## `x-lt-scan-submit`
 

package/docs/iam.md

@@ -123,14 +123,14 @@ Use `execute_as` when a workflow needs permissions or credentials that differ fr
 Two ways to set `execute_as`:
 
 1. **Workflow config** — set `execute_as` in `lt_config_workflows`. Every invocation of that workflow runs as the specified service account.
-2. **Per-request override** — pass `executeAs` in the invocation payload. Requires admin or superadmin role.
+2. **Per-request override** — pass `execute_as` in the invocation body. A superadmin may act as any account. A caller holding an admin-type grant may act as an account that holds no superadmin grant and whose every role the caller also holds, at the same or a higher type. No other caller may set it.
 
 In both cases, the original invoker is preserved in `initiated_by`. The audit trail always shows both who asked and who executed.
 
 ### Lifecycle
 
 ```bash
-# Create a service account (admin-only)
+# Create a service account (builder: superadmin or the engineer role)
 POST /api/bot-accounts
 { "name": "data-bot", "description": "Nightly analytics" }
 
@@ -287,13 +287,15 @@ The MCP client also emits debug-level audit logs for every tool invocation:
 | Credential | Scope | Lifetime | Revocation |
 |---|---|---|---|
 | User JWT | Full API (RBAC-scoped) | 24 hours | Logout / expiry |
-| Bot API key | Full API (RBAC-scoped) | Until revoked | Admin deletes key |
+| Bot API key | Full API (RBAC-scoped) | Until revoked | A builder revokes the key |
 | Delegation token | Specific scopes | 5 min (max 1 hr) | Expires naturally |
 | OAuth token | Provider scopes | Provider-set | User revokes in Connections |
 
-Service accounts inherit the same RBAC constraints as human users. A service account with the `member` role cannot access admin endpoints. A service account without `engineer` cannot invoke workflows gated by `invocation_roles`.
+Service accounts inherit the same RBAC constraints as human users. A service account with the `member` role cannot access admin endpoints. A service account that holds none of a workflow's `invocation_roles` cannot invoke it.
 
-The `execute_as` override requires admin role. There is no way for a non-admin to impersonate a service account through the API.
+Invocation roles are checked against the caller's current grants in the database, never the role claims a token carries. A workflow with an empty `invocation_roles` list is open to every authenticated caller. A superadmin, or a holder of the `admin` role at admin type, invokes any invocable workflow. `capabilityInvoke`, which calls tools with system authority, is invocable by superadmins only. Identity context for a compiled workflow comes from the server: a caller-supplied `_scope` in the input data is ignored.
+
+The `execute_as` override never exceeds the caller's own authority. A superadmin may act as any account; a caller holding an admin-type grant may act as a non-superadmin account all of whose roles the caller holds at the same or a higher type. Anyone else is refused with `403`.
 
 ## Key Files