@hotmeshio/long-tail 0.22.1 → 0.22.3

package/docs/dashboard.md

@@ -274,7 +274,7 @@ Accessible at `/admin/roles/:role`. One page per role — a quiet header carryin
 - **Escalations List Schema** — shows the list-schema version in use and links to the [Escalations List Schema](#escalations-list-schema) editor page.
 - **Metadata Schema** — JSON Schema that validates each escalation's `metadata` at creation time. Its keys appear in faceted search autocomplete.
 
-**Members** — who holds the role: admins manage it; members work its queue according to their read/write work-surface scope (read = which items appear; write = which they can claim and resolve). A `member` grant carries a scope chosen from five named profiles: full worker (`all`/`all`, default), see-all-act-own (`all`/`self`), own-items-only (`self`/`self`), read-only auditor (`all`/`none`), and read-only own (`self`/`none`). The picker enforces **write ⊆ read**. `admin` and `superadmin` grants always work the whole queue.
+**Members** — who holds the role: admins manage it; members work its queue according to their read/write work-surface scope (read = which items appear; write = which they can claim and resolve). A `member` grant carries a scope chosen from five named profiles: full worker (`all`/`all`, default), see-all-act-own (`all`/`self`), own-items-only (`self`/`self`), read-only auditor (`all`/`none`), and read-only own (`self`/`none`). The picker enforces **write ⊆ read**. `admin` and `superadmin` grants always work the whole queue. **Badge at this station** sets how a badge behaves on this role's devices (`properties.badge_grant`): how long a badge scan lasts and how many acts it covers, e.g. ten minutes and unlimited at a high-volume placing bench, one act per scan at a workstation. Empty fields keep the badge scheme's policy. See [Scan codes — identity schemes](scan-codes.md#identity-schemes-and-acting-identity).
 
 **Pins** — two live-save groups. **Link Variables** leads: the facet names members bind per device (`properties.link_variables` — name, optional label, optional default). A pin below may reference a variable as a facet value, `facets={"facility":"{lt:facility}"}`; each member device opens it scoped to its own binding (set from the user menu → Link variables), falling back to the declared default or, unbound, applying no filter. A caption under each templated pin previews the binding on the viewing device (`facility = 'soleful'` / `facility = <empty>`). **Default Pins** follows — the pinned-view seeds this role hands its members (`default_pins`): label, dashboard-relative URL, optional badge. A badge counts the list its URL opens, with every list filter it carries (role, type, subtype, priority, search, facets, status), so two pins that differ only by subtype count differently. Members see them in their Pinned nav section from first login (marked role-provided) and may promote, hide, or reorder them via preferences; promoting a templated pin copies the template, so it keeps following the device's bindings. See [Faceted Routing — Link variables](faceted-routing.md#link-variables).
 

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/x-lt-scan.md

@@ -0,0 +1,51 @@
+# Scan fields: `x-lt-scan`
+
+A form field that takes a scan. While a claimed form is open and editable, a scan whose scheme a field accepts fills that field instead of running as a global scan. A scan that no field accepts, and every badge scan, goes to the global scan pipeline as usual.
+
+```json
+{
+  "type": "object",
+  "x-lt-scan-submit": true,
+  "required": ["containerCode"],
+  "properties": {
+    "containerCode": {
+      "type": "string",
+      "title": "Container",
+      "x-lt-scan": {
+        "schemes": [14],
+        "expect": ["metadata.containerCode", "envelope.offeredContainers"],
+        "expect-error": "This item goes in {{expected}}."
+      }
+    },
+    "parts": {
+      "type": "array",
+      "items": { "type": "string" },
+      "x-lt-scan": { "schemes": [16], "expect": ["envelope.expected_upcs"], "multiplicity": "count" }
+    }
+  }
+}
+```
+
+## Field tokens
+
+| Key | Meaning |
+|---|---|
+| `schemes` | The scan scheme versions the field accepts. Required. |
+| `value` | `"target"` (default) writes the scanned target; `"code"` writes the code as scanned. |
+| `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. |
+
+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.
+
+## 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.
+
+## `x-lt-scan-submit`
+
+Root-level `true`: once every required scan field holds a value and the form validates, the form submits on its own. On a shared station the submit raises the usual badge prompt, so the motion is: scan the container into the open form, scan your badge.

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

@@ -24,6 +24,7 @@ This works because the form is data: a JSON Schema stored on the role, versioned
 | Rename the resolve footer, or claim-and-submit in one gesture | Footer tokens | [x-lt-footer.md](hitl/x-lt-footer.md) |
 | Block the resolve until embedded work drains, then auto-close when it does | `x-lt-submit-guard` | [x-lt-embed.md](hitl/x-lt-embed.md) |
 | Start another workflow from inside the form, mapped from the record, directly or in a prefilled dialog | `x-lt-invoke` | [x-lt-invoke.md](hitl/x-lt-invoke.md) |
+| Fill a field by scanning a container, checked against what the record expects | `x-lt-scan` | [x-lt-scan.md](hitl/x-lt-scan.md) |
 | A role's pinned views laid out as named pages of live panels | `portals` on the role | [portal.md](hitl/portal.md) |
 | A fully custom UI nothing above can express | Iframe viewport | [iframe.md](hitl/iframe.md) |
 | The same rich form for starting a workflow from the Invoke Tool page | `inputSchema` on the worker config | [invoke-form.md](hitl/invoke-form.md) |
@@ -69,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
@@ -94,6 +95,7 @@ Ordered as a learning path — each file adds one capability to the same form:
 | List schema (`active-history`, `active`, `facet-table`, `facet-board` cards) | [x-lt-list-schema.md](hitl/x-lt-list-schema.md) |
 | Embedded widgets (`link`, `escalation`, `escalation-list`) and the submit guard | [x-lt-embed.md](hitl/x-lt-embed.md) |
 | Starting a workflow from the form (`x-lt-invoke`) | [x-lt-invoke.md](hitl/x-lt-invoke.md) |
+| Scan fields and scan-to-submit (`x-lt-scan`, `x-lt-scan-submit`) | [x-lt-scan.md](hitl/x-lt-scan.md) |
 | Pinned views, role default pins, link variables | [pinned-views.md](hitl/pinned-views.md) |
 | Role portals: named matrices of pins rendered as pages | [portal.md](hitl/portal.md) |
 | Footer labels, claim-and-submit, and the list-driven "start" action | [x-lt-footer.md](hitl/x-lt-footer.md) |