@hotmeshio/long-tail 0.14.4 → 0.16.1

package/docs/hitl/lookups.md

@@ -0,0 +1,145 @@
+# 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`.
+
+---
+
+## The Ref
+
+```json
+{ "domain": "catalog", "key": "materials", "version": 2, "as": "materials" }
+```
+
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `domain` | yes | Knowledge domain |
+| `key` | yes | Entry key within the domain |
+| `version` | yes | The immutable edition this escalation reads |
+| `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.
+
+## Creating an Escalation with Lookups
+
+Pass `lookups` to `conditional` — the same compile-time-literal discipline as `schemaVersion`:
+
+```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 },
+  ],
+  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.
+
+## 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.
+
+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:
+
+```
+GET /api/escalations/:id/lookups
+→ { "lookups": [{ "domain": "catalog", "key": "materials", "version": 2, "data": { "items": [...] } }] }
+```
+
+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
+
+The resolved refs form the `lookup` context domain, keyed by each ref's `as` (or its `key`):
+
+```json
+{
+  "properties": {
+    "material": {
+      "type": "string",
+      "x-lt-options": "lookup.materials.items"
+    },
+    "checks": {
+      "type": "object",
+      "x-lt-widget": "checklist",
+      "x-lt-source": "lookup.checks.items",
+      "x-lt-require-all": true
+    }
+  }
+}
+```
+
+The entry's `data` is addressed directly — a flat option list lives at `data.items`, so the token reads `lookup.<name>.items`. Everything the context domains offer works here: `x-lt-showIf` conditions, `{{lookup.materials.items}}` in `x-lt-help`, dynamic bounds.
+
+Option entries are scalars or `{ value, label }` objects (`{ id, label }` accepted as an alias). An object entry separates what the submitter sees from what the payload stores — a DB-backed pick list shows its text and stores its foreign key:
+
+```json
+{ "items": [
+  { "value": "3f6a…", "label": "Delamination" },
+  { "id": "9c2b…", "label": "Warping" }
+] }
+```
+
+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.
+
+## Cascading Selects
+
+An option path may embed `{{domain.path}}` interpolation segments — the same grammar as `x-lt-help` tokens — so one answer drives the next field's legal set:
+
+```json
+{
+  "properties": {
+    "country": { "type": "string", "x-lt-options": "lookup.geo.countries" },
+    "region":  { "type": "string", "x-lt-options": "lookup.geo.regions.{{resolver.country}}" }
+  }
+}
+```
+
+With a `catalog/geo` entry shaped as:
+
+```json
+{
+  "countries": ["US", "EU"],
+  "regions": {
+    "US": ["CA", "NY", "TX"],
+    "EU": ["DE", "FR", "ES"]
+  }
+}
+```
+
+- **Region renders disabled** (an empty select on the explicit **Choose…** placeholder) until Country carries an answer.
+- **Choosing a country enables and populates Region** with exactly that country's list — the path re-resolves against the live form on every edit.
+- **Changing the country resets the presentation**: a previously chosen region that is no longer legal shows the placeholder again, and the stale value fails the membership pass on submit — client-side in the error panel, server-side as the 422 for enforcing roles.
+- Chains extend naturally: C can interpolate B the same way B interpolates A, walking one nested map or several refs.
+
+Interpolation works in `x-lt-source` the same way, so checklist item sets can follow an answer too.
+
+## 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.
+- **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.
+
+## Reference Example
+
+`examples/workflows/lookup-cascade/` is the canonical reference:
+
+- `material` — select from the pinned `catalog/materials` edition; the seed mints v1 (three items) then v2 (five), and seeds one escalation pinned to each, so both editions render side by side from ONE role form
+- `country` → `region` — the cascade pair over `catalog/geo`
+- `checks` — checklist sourced from `catalog/checks` with `x-lt-require-all`
+- the `catalog-picker` role sets `enforce_schema: true`, so out-of-edition submissions reject server-side
+
+Invoke `lookupCascade` with `{ "data": { "materials_version": 1 } }` (or `2`) to pin either edition per run.

package/docs/hitl/resolution.md

@@ -120,8 +120,8 @@ Cancellation is terminal — a cancelled escalation cannot be re-opened.
 
 ### When cancellation happens
 
-- **Workflow termination** — `POST /api/workflows/:workflowId/terminate` automatically cancels any pending escalations tied to it. The waiting `conditionLT` call returns `null`.
-- **Explicit cancel** — cancel a single escalation via the API or from the dashboard. Any workflow waiting on that escalation via `conditionLT` receives `null`.
+- **Workflow termination** — `POST /api/workflows/:workflowId/terminate` automatically cancels any pending escalations tied to it. The waiting `conditional` call returns `null`.
+- **Explicit cancel** — cancel a single escalation via the API or from the dashboard. Any workflow waiting on that escalation via `conditional` receives `null`.
 
 ### API
 
@@ -139,10 +139,10 @@ Returns 409 if the escalation is already resolved or cancelled.
 
 ### Handling cancellation in workflows
 
-`conditionLT` returns `T | false | null`. Always guard before accessing the payload:
+`conditional` returns `T | false | null`. Always guard before accessing the payload:
 
 ```typescript
-const decision = await conditionLT<{ approved: boolean }>(signalId, escalationConfig);
+const decision = await conditional<{ approved: boolean }>(signalId, escalationConfig);
 
 if (decision === null) {
   // Escalation was cancelled

package/docs/hitl/roles.md

@@ -2,10 +2,10 @@
 
 ## Role-Based Routing
 
-Escalations are routed by role, and any member of the role can handle them — a person working the queue in the dashboard, or a service account claiming and resolving through the API or MCP tools. Members only see escalations for roles they hold. Set `role` on every `conditionLT` config to name the target queue:
+Escalations are routed by role, and any member of the role can handle them — a person working the queue in the dashboard, or a service account claiming and resolving through the API or MCP tools. Members only see escalations for roles they hold. Set `role` on every `conditional` config to name the target queue:
 
 ```typescript
-const decision = await conditionLT<{ approved: boolean }>(signalId, {
+const decision = await conditional<{ approved: boolean }>(signalId, {
   role: 'finance-reviewer',   // only users with this role see it
   description: `Approve spend of $${amount}`,
   // ...
@@ -25,7 +25,7 @@ A `member` of a role carries a work-surface scope that narrows what they see and
 
 `self` means escalations assigned to that member (`assigned_to = user`); `all` means the whole role queue. `admin` and `superadmin` always work the whole queue.
 
-Scope is a property of the **membership** (`lt_user_roles`), not of the escalation row. The escalation engine is unchanged — `conditionLT` and `ltCreateEscalation` write rows exactly as before. Scope is resolved at read time when a user lists or acts on the queue.
+Scope is a property of the **membership** (`lt_user_roles`), not of the escalation row. The escalation engine is unchanged — `conditional` and `ltCreateEscalation` write rows exactly as before. Scope is resolved at read time when a user lists or acts on the queue.
 
 See the [Roles API](../api/http/roles.md#work-surface-scope) for the five member profiles and the assignment contract.
 
@@ -36,7 +36,7 @@ See the [Roles API](../api/http/roles.md#work-surface-scope) for the five member
 To route a single item to a named person, assign the escalation to them and provision them with `read_scope=self` + `write_scope=self`. The workflow sets `assigned_to` to the person's user ID when it creates the escalation, then provisions or updates that user as a `member` with self/self scope on the target role. They land directly on that one item — a just-in-time form scoped by RBAC — with no access to the rest of the queue.
 
 ```typescript
-const decision = await conditionLT<{ confirmed: boolean; address: string }>(signalId, {
+const decision = await conditional<{ confirmed: boolean; address: string }>(signalId, {
   role: 'customer-triage',
   assigned_to: userId,     // pre-claim
   description: 'Confirm your shipping address',

package/docs/hitl/x-lt-show-if.md

@@ -94,7 +94,7 @@ A queue that receives both regular items and a special signal type. The payload
 In the workflow, guard the payload fields before accessing them:
 
 ```typescript
-const decision = await conditionLT<{
+const decision = await conditional<{
   approved: boolean;
   rejection_reason?: string;
   notes?: string;

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

@@ -35,13 +35,13 @@ commit, using the HotMesh `condition({ assignee, durationMinutes, parentId })`
 primitive:
 
 ```ts
-const step1 = await conditionLT<Step1 & { $resolution?: EscalationResolution }>(sig1, {
+const step1 = await conditional<Step1 & { $resolution?: EscalationResolution }>(sig1, {
   role: STEP1_ROLE, /* … */ schemaVersion: 1,
 });
 const owner = step1.$resolution?.resolvedBy;      // who resolved step 1
 const parent = step1.$resolution?.escalationId;   // step 1's id — the correlation key
 
-await conditionLT<Step2>(sig2, {
+await conditional<Step2>(sig2, {
   role: STEP2_ROLE,
   assignee: owner,          // born assigned — no create-then-claim race
   durationMinutes: 30,      // a hard claim, so it stays with the owner

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

@@ -115,11 +115,13 @@ A select's option list can ride the escalation instead of the schema. The field-
 
 When the envelope carries `left_quantity_options: [0, 1, 2, 3]`, the field renders as a dropdown offering exactly those values — an out-of-range answer is structurally impossible. The workflow mints only the small per-row array; the form itself stays on the role.
 
+- Entries are scalars or `{ value, label }` objects (`{ id, label }` accepted as an alias): the select shows the label and the submitted answer is the value — a pick list can display text while storing its foreign key. A scalar is both. Mixed arrays resolve each entry independently; malformed entries are dropped.
 - A static `enum` takes precedence when both are present — the same static-over-dynamic rule as the bounds tokens.
 - The declared `type` governs the value: a number-typed field emits the picked option as a number, a string-typed field as a string.
 - 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.
 - A path that resolves to nothing (missing, empty array, no scalar entries) yields no options: the field renders as the plain input for its type and membership is not enforced for that submission.
-- Membership is enforced on both sides of the wire: 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`).
+- 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).
 
 ---
 
@@ -230,7 +232,7 @@ The path is dot-separated, with optional `[n]` array indices. A missing or non-n
 **Workflow side — passing the bound in the envelope:**
 
 ```typescript
-const decision = await conditionLT<{ score: number; notes: string }>(signalId, {
+const decision = await conditional<{ score: number; notes: string }>(signalId, {
   role: 'quality-reviewer',
   envelope: {
     min_score: 60,

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

@@ -144,7 +144,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). The renderer expects an array of `{ id: string; label: string; required?: boolean }` objects at that path.
 
-- `"envelope"` — for item definitions that are render data only (no query cost). The workflow puts them in `conditionLT`'s `envelope` parameter.
+- `"envelope"` — for item definitions that are render data only (no query cost). The workflow puts them in `conditional`'s `envelope` parameter.
 - `"metadata"` — only when items need to be GIN-indexed and searchable as facets. Adds index cost.
 
 ### Geometry (`x-lt-variant`)
@@ -191,7 +191,7 @@ const checklistItems = [
   { id: 'photos',  label: 'Before/after photos are present',           required: false },
 ];
 
-const decision = await conditionLT<{ checks: Record<string, boolean> }>(signalId, {
+const decision = await conditional<{ checks: Record<string, boolean> }>(signalId, {
   role: 'checklist-operator',
   envelope: {
     checklist_items: checklistItems,

package/docs/hitl-guide.md

@@ -16,6 +16,7 @@ This works because the form is data: a JSON Schema stored on the role, versioned
 |----------|-----|-----|
 | Typed fields, formats, required | Plain JSON Schema | [form.md](hitl/form.md) |
 | Input guards (bounds, patterns, dynamic limits) | Validation keywords | [x-lt-validation.md](hitl/x-lt-validation.md) |
+| Option lists shared by thousands of rows, cascading selects | Versioned lookups | [lookups.md](hitl/lookups.md) |
 | Fields that appear based on another answer | `x-lt-showIf` | [x-lt-show-if.md](hitl/x-lt-show-if.md) |
 | Sections, columns, ordering, side-panel help | Layout keywords | [x-lt-layout.md](hitl/x-lt-layout.md) |
 | Runtime-driven items, files, signatures, SOP blocks | Widgets | [x-lt-widget.md](hitl/x-lt-widget.md) |
@@ -65,6 +66,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))
 - **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
@@ -79,7 +81,8 @@ Ordered as a learning path — each file adds one capability to the same form:
 
 | Topic | File |
 |-------|------|
-| Creating escalations with `conditionLT`, schema versioning | [escalation.md](hitl/escalation.md) |
+| Creating escalations with `conditional`, schema versioning | [escalation.md](hitl/escalation.md) |
+| Versioned knowledge lookups, the `lookup.*` domain, cascading selects | [lookups.md](hitl/lookups.md) |
 | Field types, formats, required, read-only | [form.md](hitl/form.md) |
 | Pre-submission validation guards (min, max, pattern, dynamic bounds) | [x-lt-validation.md](hitl/x-lt-validation.md) |
 | Conditional visibility (`x-lt-showIf`, `x-lt-hide-if-empty`) | [x-lt-show-if.md](hitl/x-lt-show-if.md) |
@@ -101,7 +104,7 @@ Ordered as a learning path — each file adds one capability to the same form:
 | Keyword | Level | Purpose |
 |---------|-------|---------|
 | `x-lt-widget` | field | Rich control: `file-upload`, `code-editor`, `signature`, `rich-text`, `markdown`, `checklist`, `attachment` (alias `image`) |
-| `x-lt-source` | field | Data path for context-driven widgets: `"domain.path"` |
+| `x-lt-source` | field | Data path for context-driven widgets: `"domain.path"`; may embed `{{domain.path}}` interpolation segments |
 | `x-lt-require-all` | field | Checklist completion guard — every item must be checked, except items declared `required: false` |
 | `x-lt-require-any` | schema | At-least-one guard — each `string[]` group needs a value in one visible member; `0`/`false` count as answers |
 | `x-lt-require-sum` | schema | Quantity-group guard — the numeric values of `{ fields, minimum? }` must total at least `minimum` (default 1) |
@@ -112,7 +115,7 @@ Ordered as a learning path — each file adds one capability to the same form:
 | `x-lt-showIf` | field | Show field when a value is truthy at `domain.path`; prefix `!` to invert; `=VALUE` / `!=VALUE` compare the string form |
 | `x-lt-hide-if-empty` | field | `true` — suppress the field when its value is null, `""`, `false`, or `0` |
 | `x-lt-section` | field | Section group label |
-| `x-lt-options` | field | Dynamic select options — resolves a `"domain.path"` to the field's option list; static `enum` wins |
+| `x-lt-options` | field | Dynamic select options — resolves a `"domain.path"` to the field's option list (scalars or `{ value, label }`); static `enum` wins; `{{domain.path}}` segments make cascading selects |
 | `x-lt-minimum` | field | Dynamic lower bound — resolves a `"domain.path"` from the escalation context |
 | `x-lt-maximum` | field | Dynamic upper bound — resolves a `"domain.path"` from the escalation context |
 | `x-lt-min-length` | field | Dynamic minimum string length — resolves a `"domain.path"` |

package/docs/story.md

@@ -120,7 +120,7 @@ Each capability shows who uses it: which agents, which pipelines, which workflow
 
 The orchestration backstage — the same durable workflow, offered two ways:
 
-- **Procedural** — readable, Temporal-like TypeScript. Configure it, invoke it, watch its executions. Emulated atop the graph: cheap to maintain, heavier to run.
+- **Procedural** — readable, durable TypeScript. Configure it, invoke it, watch its executions. Emulated atop the graph: cheap to maintain, heavier to run.
 - **Graph** — that same workflow as a compiled, deterministic DAG. Same guarantees, roughly 3x faster, less to read. Run or schedule it; the router discovers it and pulls the work when it's healthy to.
 
 Every procedural pattern has a graph equivalent and the reverse, so the choice is readability or speed — never durability, escalation, or transactional safety. Engineers move freely between them: execution traces, durable cycle replay, swimlane timelines. Nothing is hidden. The technical depth is the product.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.14.4",
+  "version": "0.16.1",
   "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",