@hotmeshio/long-tail 0.22.2 → 0.23.0

package/docs/hitl/escalation.md

@@ -100,11 +100,23 @@ The declaration folds into the row at creation, inside the same Leg1 commit:
 - `metadata.batch_keys` — the immutable declared list (progress = `batch_keys` minus `batch_pending`)
 - `envelope.batch_items` — the accumulated `Record<itemKey, payload>` map (payloads are plumbing, so they live on the unindexed envelope; payload keys are caller-owned)
 - `envelope.batch_filled_at` — `Record<itemKey, iso8601>`, stamped by the database clock inside each fill statement — the collection timeline as row truth
+- `envelope.batch_filled_by` — `Record<itemKey, userId>`, the actor of each fill, written in the same statement (every API fill records its caller)
 
 Items are submitted via `POST /api/escalations/:id/resolve-batch-item`, `POST /api/escalations/resolve-batch-item-by-signal-key` (the deterministic home signal id — no UUID lookup, no facet duplication), or `POST /api/escalations/resolve-batch-item-by-metadata` (see [Resolution — Batch items](resolution.md)). Each item validates against the same versioned role form a single-item resolver gets, `schemaVersion` pins included. Each fill is one guarded statement: the payload lands only while its key is still pending (duplicates return `duplicate-item` untouched), and the LAST fill resolves the row, stores the assembled collection as `resolver_payload`, and wakes this wait — atomically. The completing submission's `$resolution` rides the delivered collection.
 
 `timeout` and cancellation keep their standard semantics (`false` / `null`); a plain resolve on a batch row remains an admin override that resolves the whole row with the payload given. Add `partialOnTimeout: true` (hotmesh 0.29.0+) and the timer instead resumes the wait with the items filled so far plus `$trigger: 'timeout'`, the same value the expired row stores as `resolver_payload`.
 
+Entries already satisfied before the wait begins go in `filled` (hotmesh 0.31.0+), keyed by item key with their `payload`, the `at` they were satisfied (from the source of record, never a clock read in the workflow), and an optional `actor`. The row starts with that progress: those keys are left out of `batch_pending`, their payloads, times, and actors are written beside the rest, and the completing wake delivers them with the collection. Every key in `filled` must be declared in `batch`, and at least one must stay open; a `filled` that covers every key throws, so skip the wait instead.
+
+```typescript
+const parts = await conditional<Record<'cut' | 'weld' | 'paint', StationResultV1>>(signalId, {
+  role: 'assembly',
+  metadata: { orderId },
+  batch: ['cut', 'weld', 'paint'],
+  filled: { cut: { payload: { station: 'cut-1', ok: true }, at: cutRecord.completedAt, actor: cutRecord.userId } },
+});
+```
+
 ### Open accumulation — items arrive over time
 
 Declare `accumulate` and the escalation becomes an open container: items join it one at a time through `accumulateItem` while the row stays pending, and the wait resumes with the ordered collection when the container is full, when its window closes, or when someone resolves it by hand. A timeout is a delivery, never a failure, so the wait has no `false` branch; `conditionalAccumulator` types that contract.

package/docs/hitl/lookups.md

@@ -1,45 +1,52 @@
 # Versioned Knowledge Lookups
 
-An escalation can pin **versioned knowledge lookups** — enumerated lists (select options, checklist items, cascade maps) that live once in the knowledge store and are referenced by thousands of rows. The refs ride the escalation; the content does not. Forms address the resolved content through the `lookup.*` context domain, so the full x-lt vocabulary works against it: `x-lt-options`, `x-lt-source`, `x-lt-showIf`, `x-lt-help`.
+An escalation can reference **versioned knowledge lookups** — enumerated lists (select options, checklist items, cascade maps) that live once in the knowledge store and are referenced by thousands of rows. The refs ride the escalation; the content does not. Forms address the resolved content through the `lookup.*` context domain, so the full x-lt vocabulary works against it: `x-lt-options`, `x-lt-source`, `x-lt-showIf`, `x-lt-help`.
 
 ---
 
 ## The Ref
 
 ```json
-{ "domain": "catalog", "key": "materials", "version": 2, "as": "materials" }
+{ "domain": "catalog", "key": "materials", "as": "materials" }
+{ "domain": "catalog", "key": "materials", "version": 2 }
 ```
 
 | Field | Required | Meaning |
 |-------|----------|---------|
 | `domain` | yes | Knowledge domain |
 | `key` | yes | Entry key within the domain |
-| `version` | yes | The immutable edition this escalation reads |
+| `version` | no | An edition to pin. Absent or `"current"`, the ref follows the newest edition |
 | `as` | no | The ref's form-context address, when the key alone is ambiguous |
 
-`version` is required by design. A ref names an **immutable edition**, never a moving target: every escalation created against edition 2 renders edition 2 forever, however the entry evolves afterward. Refs live under the reserved `envelope.lookups` key — the unindexed, render-only bag beside `formDefaults`. They ride the engine's atomic write but never touch the GIN-indexed metadata surface: refs are form plumbing, not facets.
+**Current refs** (no `version`, or `"current"`) read the entry's newest edition. A pending row reads the edition in force when its form renders, so a row that stays open for days shows today's list. A resolved or cancelled row reads the edition that was current when it closed, so its history shows the list its work was done against. Form schemas stay pinned (`schemaVersion`); the lists they read follow the knowledge entry.
+
+**Pinned refs** (`version: N`) name an immutable edition: every escalation created against edition 2 renders edition 2 forever, however the entry evolves afterward. Pin when the form must read one exact edition.
+
+A value picked from a current list is validated against the edition in force at submit, so an option removed while the form was open is refused with the canonical 422 and the person picks again.
+
+Refs live under the reserved `envelope.lookups` key — the unindexed, render-only bag beside `formDefaults`. They ride the engine's atomic write but never touch the GIN-indexed metadata surface: refs are form plumbing, not facets.
 
 ## Creating an Escalation with Lookups
 
-Pass `lookups` to `conditional` — the same compile-time-literal discipline as `schemaVersion`:
+Pass `lookups` to `conditional`:
 
 ```typescript
 const decision = await conditional<CascadeResolverV1>(signalId, {
   role: 'catalog-picker',
   description: 'Pick a material for this order',
   lookups: [
-    { domain: 'catalog', key: 'materials', version: 2 },
-    { domain: 'catalog', key: 'geo', version: 1 },
+    { domain: 'catalog', key: 'materials' },          // the newest edition
+    { domain: 'catalog', key: 'geo', version: 1 },    // pinned
   ],
   schemaVersion: 1,
 });
 ```
 
-The refs fold into `envelope.lookups` as a pure transform — a pinned wait costs exactly what an unpinned one does. A malformed ref (missing field, non-integer version) throws before the row is written; over the HTTP create surface the same validation answers with a 400.
+The refs fold into `envelope.lookups` as a pure transform — a wait with refs costs exactly what one without does. A malformed ref (missing field, a version that is not a positive integer or `"current"`) throws before the row is written; over the HTTP create surface the same validation answers with a 400.
 
 ## Pinning on a Workflow Config
 
-An invoke form pins editions the same way. Declare `inputLookups` beside `inputSchema` on the worker config and the form reads them under `lookup.<as ?? key>`:
+An invoke form references editions the same way. Declare `inputLookups` beside `inputSchema` on the worker config and the form reads them under `lookup.<as ?? key>`:
 
 ```typescript
 const fleetToolsConfig: LTWorkerConfig = {
@@ -54,29 +61,31 @@ const fleetToolsConfig: LTWorkerConfig = {
 "serialNumber": { "type": "string", "title": "Serial", "x-lt-options": "lookup.serials.items" }
 ```
 
-The Invoke Tool page fetches `GET /api/workflows/:type/input-lookups` once per workflow; the grant is the invoke predicate, so whoever may start the workflow reads exactly the pinned editions. The invoke API resolves the same refs into the gate, so a value outside the edition is refused with the canonical 422. The registry detail page edits the refs under **Lookups** in its Invocation column; the preview renders against the resolved editions.
+The Invoke Tool page fetches `GET /api/workflows/:type/input-lookups` each time the form opens; the grant is the invoke predicate, so whoever may start the workflow reads exactly the entries the config names. The invoke API resolves the same refs into the gate, so a value outside the edition is refused with the canonical 422. The registry detail page edits the refs under **Lookups** in its Invocation column; the preview renders against the resolved editions.
 
-The refs are checked twice on save. Shape first: a missing `domain` or `key`, a `version` that is not a positive integer, or an empty `as` answers `400` with the field named. Existence second: a ref whose edition does not exist answers `400` naming the editions that do (`Lookup ref fleet/serial-numbers v3 names no edition (editions: v1, v2)`), from `PUT /api/workflows/:type/config` and from the MCP `upsert_workflow_config` tool alike. On the worker boot path a malformed ref fails the boot; a ref whose edition is not yet written logs a warning, since seeds commonly run after registration. At run time the resolver reads each edition once and holds it in memory (editions are immutable), a missing edition answers `missing: true` for that ref without failing the batch, the Invoke Tool page shows which pinned editions are unavailable, and the fields that read them follow the `x-lt-options` rules: a plain path falls back to the typed input, an interpolated path stays a disabled select and fails closed.
+The refs are checked twice on save. Shape first: a missing `domain` or `key`, a `version` that is not a positive integer or `"current"`, or an empty `as` answers `400` with the field named. Existence second: a ref with no edition behind it answers `400` naming the editions that do (`Lookup ref fleet/serial-numbers v3 names no edition (editions: v1, v2)`; a current ref to an entry with no editions says `current`), from `PUT /api/workflows/:type/config` and from the MCP `upsert_workflow_config` tool alike. On the worker boot path a malformed ref fails the boot; a ref whose edition is not yet written logs a warning, since seeds commonly run after registration. At run time the resolver holds each edition in memory once read (editions are immutable; a current ref first looks up which edition is newest), a missing edition answers `missing: true` for that ref without failing the batch, the Invoke Tool page shows which editions are unavailable, and the fields that read them follow the `x-lt-options` rules: a plain path falls back to the typed input, an interpolated path stays a disabled select and fails closed.
 
 ## Versioning
 
 Every knowledge entry carries a `current_version`, and every write that changes its data mints an immutable snapshot automatically — no publish step:
 
 1. **Add items** — write the entry (`storeEntry`, `set_knowledge_field`, the dashboard editor). The data change bumps `current_version` and snapshots the new edition. Writes that leave the data unchanged mint nothing.
-2. **Repin** — update the workflow's `lookups` literal to the new version, evolving the resolver payload type alongside when the new items change what the form can answer.
-3. **Rows in flight keep their edition** — an escalation pinned to v1 renders v1's list even after v5 exists.
+2. **Current refs follow** — every pending row with a current ref shows the new edition on its next render. Nothing to repin.
+3. **Pinned rows keep their edition** — an escalation pinned to v1 renders v1's list even after v5 exists. Repin the literal (and evolve the resolver payload type) when a pinned form should move.
 
 Inspect the lineage with `GET /api/knowledge/entry/versions?domain=catalog&key=materials`, `ltc kb versions catalog materials`, or the `list_knowledge_versions` MCP tool. Fetch a specific edition with `?version=N` on the entry endpoint.
 
 ## The Grant
 
-The refs on the row ARE the grant. Any user who may read the escalation may fetch exactly the pinned editions it names:
+The refs on the row ARE the grant. Any user who may read the escalation may fetch exactly the entries it names, at the editions those refs resolve to:
 
 ```
 GET /api/escalations/:id/lookups
-→ { "lookups": [{ "domain": "catalog", "key": "materials", "version": 2, "data": { "items": [...] } }] }
+→ { "lookups": [{ "domain": "catalog", "key": "materials", "version": 4, "current": true, "data": { "items": [...] } }] }
 ```
 
+`version` is the edition served; `current: true` marks a ref that follows the newest edition.
+
 The general knowledge API (`/api/knowledge/*`) is a builder surface — superadmin or engineer. A member never queries the knowledge store directly; the escalation-scoped endpoint serves them precisely the editions their work item carries, and nothing else. A ref whose snapshot does not exist answers with `missing: true` for that ref — the batch never fails.
 
 ## Form Addressing
@@ -113,7 +122,7 @@ Option entries are scalars or `{ value, label }` objects (`{ id, label }` accept
 
 The select renders the labels, the submitted answer is the value, and mixed arrays resolve each entry independently (a scalar is both).
 
-Membership is enforced on both sides of the wire: the dashboard constrains the choices, and an `enforce_schema` role's server gate re-resolves the same pinned editions and rejects an out-of-edition value with the canonical 422.
+Membership is enforced on both sides of the wire: the dashboard constrains the choices, and an `enforce_schema` role's server gate re-resolves the same refs (a current ref at the edition in force at submit) and rejects an out-of-edition value with the canonical 422.
 
 ## Cascading Selects
 
@@ -162,9 +171,9 @@ A lookup-sourced checklist can declare `"x-lt-default-checked": true` to start e
 ## Efficiency
 
 - **Refs, not content, ride the rows.** Thousands of escalations sharing one list each store a three-field ref; the list lives once per edition.
-- **One fetch per page.** The resolve UI batch-fetches all refs in a single `GET /:id/lookups` call at load. Pinned editions are immutable, so the response caches for the whole session.
+- **One fetch per page.** The resolve UI batch-fetches all refs in a single `GET /:id/lookups` call each time the page opens (never on focus or a timer), so a current ref shows the newest edition on the next open.
 - **Zero network during execution.** Cascade levels resolve locally from the already-fetched entry data — every keystroke re-resolves in memory.
-- **Server-side, snapshots cache indefinitely.** Enforcement reads come from an in-process LRU keyed by `(domain, key, version)`; the first row referencing an edition pays the read, every later row hits memory.
+- **Server-side, snapshots cache indefinitely.** Enforcement reads come from an in-process LRU keyed by `(domain, key, version)`; the first row referencing an edition pays the read, every later row hits memory. A current ref adds one indexed read (the newest edition by primary key) per resolution.
 
 ## Reference Example
 

package/docs/hitl/resolution.md

@@ -107,7 +107,7 @@ Interim items return `accepted` with the remaining count and publish `escalation
 
 Each item validates against the same versioned role form a single-item resolve uses, canonical 422 included. Batch fills are claim-agnostic — a batch collects contributions from multiple principals, the same rationale as the signal-key path — while `assertClaim: true` (by-id form) opts into the caller's own live-claim assertion inside the guarded statement.
 
-Item keys are non-empty strings up to 128 characters; prefer URL-friendly names (`u1-L`). Payload keys inside each item are caller-owned — the platform reserves no names inside `batch_items` values. Every fill stamps `envelope.batch_filled_at[itemKey]` with the database clock in the same statement, so the row carries the collection timeline as row truth. After an SLA expiry (`conditional` returns `false`) the terminal row retains the partial `batch_items` and their timestamps — read them back with `GET /api/escalations/:id` or `getEscalationBySignalKey` from an activity.
+Item keys are non-empty strings up to 128 characters; prefer URL-friendly names (`u1-L`). Payload keys inside each item are caller-owned — the platform reserves no names inside `batch_items` values. Every fill stamps `envelope.batch_filled_at[itemKey]` with the database clock and `envelope.batch_filled_by[itemKey]` with the caller in the same statement, so the row carries the collection timeline and who filled each item as row truth. After an SLA expiry (`conditional` returns `false`) the terminal row retains the partial `batch_items` and their timestamps — read them back with `GET /api/escalations/:id` or `getEscalationBySignalKey` from an activity.
 
 ### Accumulator items
 

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

@@ -143,7 +143,7 @@ When the envelope carries `left_quantity_options: [0, 1, 2, 3]`, the field rende
 - While the current value is outside the option list (an empty init, options that shrank per-row), the select opens on an explicit disabled **Choose…** placeholder — never an implicit first option.
 - When no path resolves (missing, empty array, no valid entries) the field renders as the plain input for its type and membership is not enforced for that submission — unless any path embeds `{{domain.path}}` interpolation, in which case the field stays a disabled select and a present value fails closed (a cascade child never becomes free text).
 - Membership is enforced on both sides of the wire — always on the option VALUE, never the label: the dashboard constrains the choices, and an enforced role's server gate rejects a payload whose value is outside the row's resolved list with the canonical 422 (`Must be one of: 0, 1, 2, 3`).
-- Option lists can also come from version-pinned knowledge entries (the `lookup` domain), and paths may embed `{{domain.path}}` interpolation segments for cascading selects — a dependent select whose parent is unanswered renders disabled and fails closed. See [lookups.md](lookups.md).
+- Option lists can also come from versioned knowledge entries (the `lookup` domain), and paths may embed `{{domain.path}}` interpolation segments for cascading selects — a dependent select whose parent is unanswered renders disabled and fails closed. See [lookups.md](lookups.md).
 
 ---
 

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

@@ -172,7 +172,7 @@ The field type must be `"object"`. The submitted value is `Record<string, boolea
 `x-lt-source` uses the `"domain.path"` convention (same as `x-lt-showIf` and `x-lt-help` tokens), and may embed `{{domain.path}}` interpolation segments. The token is a single path or an **ordered array of paths** — the first that resolves to items wins, so a lookup-backed row and an envelope-embedded row render the same shared schema interchangeably. The renderer expects an array of `{ id: string; label: string; required?: boolean }` objects at the resolved path.
 
 - `"envelope"` — for item definitions that are render data only (no query cost). The workflow puts them in `conditional`'s `envelope` parameter.
-- `"lookup"` — for item sets shared by many rows: a version-pinned knowledge edition (see [lookups.md](lookups.md)).
+- `"lookup"` — for item sets shared by many rows: a versioned knowledge edition, pinned or current (see [lookups.md](lookups.md)).
 - `"metadata"` — only when items need to be GIN-indexed and searchable as facets. Adds index cost.
 
 ### First-load default (`x-lt-default-checked`)

package/docs/hitl-guide.md

@@ -70,7 +70,7 @@ When you author a HITL-backed workflow, the platform handles:
 - **AI triage** — optional auto-resolution for common patterns
 - **Credential security** — password fields use ephemeral tokens, never stored in plain text
 - **Schema enforcement** — roles with `enforce_schema` validate every resolver payload server-side (dashboard, API, MCP, CLI alike) with the same pass the form runs, rejecting violations as a structured 422 (see [schema-enforcement.md](schema-enforcement.md))
-- **Versioned lookups** — escalations pin immutable knowledge editions for their option lists; the refs grant readers exactly those editions, and cascading selects resolve locally from one batch fetch (see [lookups.md](hitl/lookups.md))
+- **Versioned lookups** — escalations reference knowledge entries for their option lists, following the newest edition or pinned to one; the refs grant readers exactly those entries, and cascading selects resolve locally from one batch fetch (see [lookups.md](hitl/lookups.md))
 - **Telemetry** — trace IDs link escalations to OpenTelemetry traces
 - **Bulk operations** — bulk claim, assign, triage, and cancel for queue management
 - **Cancellation** — cancel pending escalations from the API or dashboard

package/docs/scan-codes.md

@@ -88,7 +88,8 @@ Each step:
     "roles": ["printer-fleet"],        // expected queue(s)
     "status": "pending",               // pending | resolved | cancelled
     "availability": "available",       // available | claimed | mine | any
-    "facets": { "state": "printing" }  // extra metadata guards
+    "facets": { "state": "printing" }, // extra metadata guards
+    "subtypes": ["open"]               // optional: types / subtypes the row must have
   },
   "cardinality": "first",              // first | many
   "verb": "resolve",
@@ -97,6 +98,14 @@ Each step:
 }
 ```
 
+`query.types` and `query.subtypes` narrow steps that locate a row and then
+act on it by id: `show-detail`, `show-list`, `present` (with any choice; each
+choice writes the row shown), `hold`, `fill`, and `accumulate`
+(container-locate mode narrows the container). Claim, cancel, release,
+resolve and escalate steps locate by the target facet inside their atomic
+statement, so the upsert refuses types/subtypes on them; to narrow one, offer
+it as a `present` choice. With `availability: "mine"` each takes one entry.
+
 Verbs are the canonical escalation actions:
 
 | Verb | Effect | Params |
@@ -219,10 +228,32 @@ unsatisfied. Picking one calls `POST /api/scan-codes/execute-choice` with a
 pointer (scheme, category, step index, choice index, escalation id) — and a
 pointer is never authority: the server re-reads live config, re-locates the
 row under the step's query, re-applies the identity gate, and runs the verb
-through the same atomic executors a direct scan uses. A resolve choice
-resolves the exact row the screen presented, re-checked under the step's
-query in the same statement. A row that moved on between render and tap
-answers `conflict`, exactly as a lost double-scan.
+through the same atomic executors a direct scan uses. Every choice writes
+the exact row the screen presented, by id: claim, cancel, resolve and an
+escalate's `closeCurrent` re-check that row (pending, the scanned code, the
+step's roles, no live claim by someone else) in the same statement, and
+release releases that row when it is the actor's claim. When one code names
+several pending rows, the write never lands on a different one. A row that
+moved on between render and tap answers `conflict`, exactly as a lost
+double-scan.
+
+A `present` step names the facts the station states about the row with
+`facts`: up to 12 labeled templates, rendered server-side against the row
+(`{item.<facet>}`) and the scan tokens, shown in order. A token the row cannot
+fill renders as a dash.
+
+```jsonc
+"facts": [
+  { "label": "Bin", "value": "{item.binCode}" },
+  { "label": "Clinic", "value": "{item.facilityName}" },
+  { "label": "Bags", "value": "{item.memberCount}" }
+]
+```
+
+Without `facts`, the station lists the row's metadata, leaving out the
+bookkeeping a bench never acts on: scan provenance (`scannedAt`,
+`scanScheme`, `scanCategory`, `scanStation`, `scanActionName`),
+`resolved_by`, `schema_version`, and the accumulate and batch counters.
 
 A choice's `code` is a short printable token (letters, digits, underscore,
 dash) enabling double-scan selection: scan the object, then scan an action
@@ -271,8 +302,9 @@ set one ("Take the new label from the printer and stick it on C-12").
 Any step that writes may carry `done: { markdown }`: the copy the station shows,
 large, once the write lands and until the next scan ("Place it in
 **{container.containerCode}**. All good."). It reads the same bags its refusal copy
-reads. A fill that leaves items to scan shows its done copy as the progress
-line under the hold.
+reads. A fill or an into-subject add that leaves slots open shows its done
+copy under the hold; without done copy the station shows the count ("2 of 5
+checked off" for a fill, "2 of 5 added" for an add).
 
 The server trusts nothing about the subject. Each request re-parses its
 code, re-reads the row under the station's read scope, requires the row to
@@ -287,8 +319,8 @@ row.
 | Step | What the container scan does |
 |---|---|
 | `accumulate` with `accumulate.from: "subject"` | The held item joins the accumulator the scan names (found by the scheme facet, narrowed by `accumulate.container`). The held row is written as the reciprocal in the same statement, so a held row parked as a one-slot accumulator completes and its workflow wakes. `params.itemKey` names the item, e.g. `{subject.itemId}`. |
-| `accumulate` with `accumulate.into: "subject"` | The held row collects the scanned code (`itemKey` defaults to `{scan.target}`). Use it when the container has no row yet: the first item for a container tells the workflow which container was scanned. |
-| `fill` with `fill.into: "subject"` | One expected item is checked off: the held row is a batch whose keys are codes, and the scan fills the first open key for its code. A code expected twice is declared `<code>#1`, `<code>#2` and takes two scans; a third is refused. The answer carries `progress: { filled, total, remaining }`, the subject stays held while items remain, and the last fill completes the row. `fill.into: "scanned"` fills the row the scan itself names. |
+| `accumulate` with `accumulate.into: "subject"` | The held row collects the scanned code (`itemKey` defaults to `{scan.target}`). Use it when the container has no row yet: the first item for a container tells the workflow which container was scanned. With `accumulate.item`, the scanned code's own pending row is written as the reciprocal in the same statement (see below). On a bounded accumulator the answer carries `progress` and the subject stays held while slots remain. |
+| `fill` with `fill.into: "subject"` | One expected item is checked off: the held row is a batch whose keys are codes, and the scan fills the first open key for its code. A code expected twice is declared `<code>#1`, `<code>#2` and takes two scans; a third is refused. The answer carries `progress: { filled, total, remaining }`, the subject stays held while items remain, and the last fill completes the row. On a `gtin` scheme a refusal's `expected` lists codes as the package prints them (EAN-13, or EAN-8), not the stored 14-digit form. `fill.into: "scanned"` fills the row the scan itself names. |
 
 **`match` and `refuse`** check the pairing before anything is written.
 `match.target` lists templates the scanned target must equal (e.g.
@@ -304,6 +336,37 @@ declares `refuse.conflict` also clears the subject so the next item scan
 reads fresh state. Exactly one of two racing acts wins whenever both name
 the same row: the reciprocal statement writes both rows or neither.
 
+**The item's own row on an into-subject add.** A held container that collects
+item codes (a box being packed from a bin) often has items that each wait on
+their own row. `accumulate.item` locates that row and writes it as the
+reciprocal of the container's entry, so the two land together or not at all:
+
+```jsonc
+// 11:0, item label, while the box is held
+{ "query": { "roles": ["packing"], "status": "pending" }, "verb": "accumulate",
+  "requireActingIdentity": true, "subject": { "schemes": [14] },
+  "match": { "target": ["{subject.memberCodes}"] },
+  "refuse": { "markdown": "Not one of this bin's items.",
+              "missing": "That item is not waiting to be packed." },
+  "done": { "markdown": "{item.itemCode} is in. {container.accumulate_count} of {container.accumulate_max}." },
+  "params": { "itemKey": "{scan.target}",
+    "accumulate": { "into": "subject", "item": { "roles": ["ship"], "facets": { "shape": "consolidated" } } } } }
+```
+
+The item row is a pending accumulator whose scheme facet equals the scanned
+target (a plain row carrying the same code is not a candidate: only an
+accumulator can take the reciprocal entry), in `item.roles` (intersected with the actor's read scope), narrowed by
+`item.types`, `item.subtypes` and `item.facets`; the held row is never a
+candidate. Parked as `max: 1`, it completes in the same statement and its
+workflow wakes with the container's id in `$accumulated`. No such row answers
+`refused` with `refuse.missing` (or falls through without it); two answer
+`conflict`. An item already placed elsewhere is refused with the box still
+held, an item scanned twice into it answers `already` with the box still
+held, and a live claim on the item row by someone else refuses with their
+name (checked before the write; the statement itself does not re-check it). `{item.<facet>}` reads the item row in `itemKey`, the payload,
+metadata and copy; `{container.<facet>}` in the copy reads the held row as the
+add left it.
+
 **One rule, several kinds of held item.** `subject.facets` makes a step
 apply only while the held row carries those facet values; otherwise the step
 is skipped and the next one runs. A placing bench uses it to tell an item
@@ -444,7 +507,10 @@ signed-in user is a **member of exactly that one role** — the station-login
 shape — the dashboard locks the viewport: the left nav is gone entirely, the
 role's escalation list is home (`/` and every other surface redirect to it),
 and the session is held to the list, the escalation detail page, the role's
-portals, and the scan screens (choice, badge). A role that declares
+portals, and the scan screens (choice, badge). The list with neither a
+`role` nor a `facets` filter is every queue at once, so it redirects home
+too, including right after sign-in; a scan's `show-list` (narrowed by
+facets) stays. A role that declares
 [portals](./hitl/portal.md) lands on its first one as home instead of the list. The header toolbar and event feed remain. A user
 holding more than one role, or an admin-type grant, always gets full chrome —
 kiosk is for the single-role floor login, never a way to hide the product from
@@ -470,12 +536,16 @@ submit opens a badge prompt naming that claimant. The resolve fires the moment
 a matching badge primes; a badge that is not the claimant's is named and the
 submit is held.
 
-The gate is on **use**, not on grant lifetime. Acting grants are single-use:
-the claim already spent the grant it was minted with, so the submit owes a
-fresh tap — every write consumes its own grant. A held token proves nothing
-about whether a submit can succeed, so the surface never lets one skip the
-badge. Editing persists nothing locally, so the identity gate sits at the one
-place a record actually changes, once per change.
+The gate is on **use**, not on grant lifetime. A live grant that names the
+claimant and has uses left carries the submit and spends one use, as a scan
+act does (release, cancel and escalate always ask); the badge prompt shows only when no such grant is held. The station
+holds a grant only while it has uses left, so a single-use badge spent by the
+claim makes the submit ask for a fresh tap, while a role's
+`badge_grant: { ttl_seconds: 600, max_uses: 0 }` lets one badge claim and
+submit for ten minutes. A grant bound to a scanned subject (`grant_scope:
+"subject"`) belongs to that scan and still asks. Editing persists nothing
+locally, so the identity gate sits at the one place a record actually
+changes, once per change.
 
 Mutations attribute to the badged person (`assigned_to`, `resolved_by`)
 with the device recorded beside them (`scanStation` in the scan

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -75,7 +75,7 @@
     "@anthropic-ai/sdk": "^0.92.0",
     "@aws-sdk/client-s3": "^3.1017.0",
     "@aws-sdk/s3-request-presigner": "^3.1045.0",
-    "@hotmeshio/hotmesh": "^0.30.0",
+    "@hotmeshio/hotmesh": "^0.31.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.215.0",
     "@opentelemetry/resources": "^2.5.1",