@hotmeshio/long-tail 0.10.1 → 0.10.3

package/docs/api/http/escalations.md

@@ -58,6 +58,7 @@ GET /api/escalations
 | `exists` | array of strings | Keys that must be present — `metadata ? key` |
 | `roles` | array of strings | Restrict to these roles (narrows within scope, never widens) |
 | `available` | `true`/`false` | `true` = unclaimed/expired only; `false` = held now |
+| `jeopardy` | `1`/`true` | Only rows past their role's priority threshold — the exact predicate behind the Pace Board's priority count, so a jeopardy list's total equals the badge. Age from the role's `priority_facet` metadata timestamp (`created_at` when unset) against `priority_threshold_minutes` (`sla_minutes` when unset); undialed roles contribute no rows |
 | `orderBy` | array of `{field, direction?, numeric?}` | Sort by column or `metadata.<key>` |
 
 When any faceted parameter is present the request runs through the scoped faceted query.
@@ -204,7 +205,21 @@ Resolving an escalation starts a new workflow execution with the resolver's payl
 | `resolverPayload` | `object` | yes | The reviewer's decision — injected into `envelope.resolver` |
 | `metadata` | `object` | no | Outcome facets merged into the escalation's GIN-indexed metadata. Records *what happened* (disposition, timing) next to *what was asked*; `@>`-queryable. Distinct from `resolverPayload`, which resumes the workflow and is not indexed |
 
-The `resolverPayload` is stored exactly as submitted — the resolver payload is the payload. There is no server-side validation and no server-side mapping of its shape. The client forms the final payload: the React dashboard maps the flat form to the nested payload via each field's `x-lt-bind` before submitting.
+The `resolverPayload` is stored exactly as submitted — the resolver payload is the payload, with no server-side mapping of its shape. The client forms the final payload: the React dashboard maps the flat form to the nested payload via each field's `x-lt-bind` before submitting.
+
+**Schema enforcement (roles with `enforce_schema`):** every resolve surface validates the submitted `resolverPayload` against the escalation's resolved form schema (`metadata.form_schema` override, else the pinned `lt_role_schemas` snapshot, else the role's latest) and rejects violations with **422** before any state changes. The body is the canonical validation shape, identical across HTTP, SDK, MCP, and CLI — see [Schema Enforcement](../../schema-enforcement.md):
+
+```json
+{
+  "error": "resolverPayload failed schema validation (1 violation)",
+  "code": "schema_validation",
+  "violations": [{ "field": "contact_email", "message": "Enter a valid email address" }],
+  "role": "intake-reviewer",
+  "schemaVersion": 3
+}
+```
+
+Bulk surfaces (`resolve-by-ids`, `resolve-all-or-none`) tag each violation with its `escalationId`, and one failing item blocks the batch before anything resolves.
 
 **Example request:**
 

package/docs/api/http/roles.md

@@ -268,6 +268,7 @@ Returns all roles with metadata and usage counts.
 | `metadata_schema` | `object \| null` | JSON Schema declaring the expected shape of `lt_escalations.metadata` for this role. Drives faceted-query key autocomplete and creation-time validation |
 | `properties` | `object` | Free user-owned bag — icons, colors, tags, etc. No reserved keys |
 | `ops_visible` | `boolean` | When `true`, the role appears as a station on the `/operations` view |
+| `enforce_schema` | `boolean` | When `true`, every resolve surface validates submitted payloads against this role's form schema and rejects violations with `422` (`code: schema_validation`) — see [Schema Enforcement](../../schema-enforcement.md) |
 | `parent_role` | `string \| null` | Parent role in the process dependency graph; `null` for root stations |
 | `sla_minutes` | `number \| null` | Target resolution time in minutes (capacity setting) |
 | `target_per_hour` | `number \| null` | Intended throughput — items resolved per hour (capacity setting) |
@@ -366,6 +367,7 @@ When the update changes `form_schema` or `metadata_schema`, the new pair is snap
 | `metadata_schema` | `object \| null` | JSON Schema for `lt_escalations.metadata` |
 | `properties` | `object \| null` | Free user-owned bag |
 | `ops_visible` | `boolean` | Include in the `/operations` view |
+| `enforce_schema` | `boolean` | Turn server-side resolver schema validation on/off |
 | `parent_role` | `string \| null` | Parent in the process dependency graph |
 | `sla_minutes` | `number \| null` | SLA target in minutes |
 | `target_per_hour` | `number \| null` | Throughput target (items per hour) |
@@ -373,6 +375,8 @@ When the update changes `form_schema` or `metadata_schema`, the new pair is snap
 | `priority_threshold_minutes` | `number \| null` | Priority age threshold in minutes; falls back to `sla_minutes` |
 | `priority_facet` | `string \| null` | Metadata key for the priority age origin (letters, numbers, underscores); falls back to `created_at` |
 | `upstream_roles` | `string[] \| null` | Replace the set of roles this station draws input from across other Operations sequences (omitted = preserve; `null` or `[]` = clear). Every entry must name an existing role other than this one. Distinct from `parent_role`, which places the role in its own sequence. |
+| `list_schema` | `object \| null` | Rich formatting (x-lt-* markup) for this role's escalation LIST page. Versions independently of `form_schema`; the list always renders the latest |
+| `default_pins` | `array \| null` | Pinned-view seeds for members: `[{ label, url, badge? }]` with dashboard-relative `url`s. Members promote, hide, or reorder them via their own preferences (`/api/me/preferences`). `null` clears |
 | `change_summary` | `string` | Label recorded on the schema version snapshot when this update changes a schema field |
 
 **Example request** — configure a role as a station in the ops view:

package/docs/api/http/users.md

@@ -187,3 +187,42 @@ Deletes the user and all associated role assignments (cascade).
 ```json
 { "error": "User not found" }
 ```
+
+---
+
+## Self-Service — `/api/me`
+
+Operations on the **authenticated caller** — no ids, no admin gates. Any signed-in user (or service account) may call them.
+
+### GET /api/me/preferences
+
+The caller's preferences document — a generic per-user JSON store for presentation state (pinned views are the first tenant). Reads `{}` when unset.
+
+**Response 200:**
+
+```json
+{
+  "preferences": {
+    "pinnedViews": [
+      { "id": "pin-x1", "label": "Needs harvesting", "url": "/escalations/available?role=fleet-servicer&jeopardy=1&view=table", "badge": true }
+    ],
+    "hiddenRolePins": ["My machines"]
+  }
+}
+```
+
+### PATCH /api/me/preferences
+
+Shallow-merge the body into the caller's preferences: top-level keys overwrite whole, a `null` value deletes its key. The merge is a single guarded statement (no read-then-write) and the stored document is size-capped (~32 KB). Preferences carry presentation state only — URLs and UI choices, never data and never authorization.
+
+**Request body** — any JSON object of preference keys:
+
+```json
+{ "pinnedViews": [ { "id": "pin-x1", "label": "Needs harvesting", "url": "/escalations/available?role=fleet-servicer&jeopardy=1", "badge": true } ], "theme": null }
+```
+
+**Response 200:** the merged document, `{ "preferences": { ... } }`.
+
+**Response 400:** body is not a JSON object. **Response 413:** the patch or the merged document would exceed the size cap (nothing is written).
+
+See the [Pinned Views guide](../../hitl/pinned-views.md) for how the dashboard uses this store.

package/docs/api/sdk/roles.md

@@ -32,6 +32,9 @@ interface RoleDetail {
   worker_count: number | null;
   priority_threshold_minutes: number | null;
   priority_facet: string | null;
+  list_schema: Record<string, any> | null;
+  default_pins: { label: string; url: string; badge?: boolean }[] | null;
+  upstream_roles: string[];
   user_count: number;
   chain_count: number;
   workflow_count: number;
@@ -276,6 +279,8 @@ const result = await lt.roles.update({
 | `priority_threshold_minutes` | `number \| null` | No | Priority age threshold in minutes; falls back to `sla_minutes` |
 | `priority_facet` | `string \| null` | No | Metadata key for the priority age origin; falls back to `created_at` |
 | `upstream_roles` | `string[] \| null` | No | Replace the set of roles this station draws input from across other Operations sequences (omitted = preserve; `null` or `[]` = clear). Distinct from `parent_role`, which places the role in its own sequence |
+| `list_schema` | `object \| null` | No | Rich formatting (x-lt-* markup) for this role's escalation LIST page; versions independently of `form_schema` |
+| `default_pins` | `array \| null` | No | Pinned-view seeds for members: `[{ label, url, badge? }]` with dashboard-relative `url`s. Members promote, hide, or reorder via their own preferences (`lt.me`) |
 | `change_summary` | `string` | No | Label recorded on the schema version snapshot when this update changes a schema field |
 
 When the update changes `form_schema` or `metadata_schema`, the new pair is snapshotted into the role's version history and `current_schema_version` advances.

package/docs/api/sdk/users.md

@@ -219,3 +219,42 @@ const result = await lt.users.removeRole({
 **Returns:** `LTApiResult<{ removed: true }>` -- returns 404 if role not found.
 
 **Auth:** Not required
+
+---
+
+## me — the authenticated caller
+
+Self-service operations bound to the client's auth context (no ids, no admin gates).
+
+### me.getPreferences
+
+```typescript
+const result = await lt.me.getPreferences();
+// { status: 200, data: { preferences: { pinnedViews: [...] } } }
+```
+
+**Returns:** `LTApiResult<{ preferences: Record<string, unknown> }>` — `{}` when unset.
+
+### me.patchPreferences
+
+Shallow-merge a patch into the caller's preferences: top-level keys overwrite whole, `null` deletes a key. The merge is one guarded statement; the stored document is size-capped (~32 KB → 413).
+
+```typescript
+const result = await lt.me.patchPreferences({
+  patch: {
+    pinnedViews: [
+      { id: 'pin-x1', label: 'Needs harvesting', url: '/escalations/available?role=fleet-servicer&jeopardy=1', badge: true },
+    ],
+  },
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `patch` | `object` | Yes | Preference keys to merge; a `null` value deletes its key |
+
+**Returns:** `LTApiResult<{ preferences: Record<string, unknown> }>` — the merged document.
+
+**Auth:** Required (the operation targets the caller).

package/docs/hitl/pinned-views.md

@@ -0,0 +1,45 @@
+# Pinned Views
+
+Task-queue personas live in a handful of exact queries — "pending harvest rows, oldest first," "everything about serial X." Every filter on the escalations list is already deep-linked in the URL (`role`, `status`, `facets`, `range`, `orderBy`, `view`, `jeopardy`); pinned views add persistence and placement: the right queries sit in the right person's nav from first login.
+
+---
+
+## User Preferences
+
+Pins live in a per-user preferences store — a generic JSON document on the user record (pinned views are its first tenant, not its schema):
+
+```
+GET   /api/me/preferences            → { preferences }
+PATCH /api/me/preferences            shallow top-level merge; null deletes a key
+```
+
+The merge is a single guarded statement (no read-then-write) and the document is size-capped (~32 KB → 413). Preferences carry presentation state only — URLs and UI choices, never data and never authorization. A pin to a query the user cannot read simply renders that query's normal empty state; read-scope enforcement stays where it already lives.
+
+```json
+{
+  "pinnedViews": [
+    { "id": "pin-x1", "label": "Needs harvesting", "url": "/escalations/available?role=fleet-servicer&facets=%7B%22machineState%22%3A%22finished%22%7D&view=table", "badge": true }
+  ],
+  "hiddenRolePins": ["My machines"]
+}
+```
+
+## The Pinned Section
+
+Pins render as a **Pinned** nav section: the user's own pins first, in stored order (drag to reorder, ✕ to remove), then role-provided defaults. **Pin this view** on the escalations list captures the live filter set into a new pin, prompting only for a label.
+
+`badge: true` renders a live count beside the label using the same server-side predicate the pin opens onto (the pin's URL is parsed back into its query and counted with `limit: 1`) — so the badge and the list always agree, including `jeopardy=1` pins. Counts refresh on escalation events, and a pin whose URL isn't a countable escalations list renders without a badge.
+
+## Role Default Pins
+
+A role may declare `default_pins: [{ label, url, badge? }]` (edited on Role Detail → Default Pins). Members see them in their Pinned section from first login, marked as role-provided, and may:
+
+- **Promote** — copy into their own pins (an own pin with the same label supersedes the role default)
+- **Hide** — dismiss it (recorded in `hiddenRolePins`)
+- **Reorder** — promote first, then drag among their own pins
+
+Membership *is* the persona's bookmark set — no per-user setup. Duplicate labels across a user's roles collapse to the first role's pin.
+
+## Reference Example
+
+The `fleet-servicer` seed (`examples/seed-fleet-sim.ts`) ships a facet-board list schema, jeopardy dials, and three default pins — the board, a badged "Needs harvesting" facet query, and a badged jeopardy view — so the whole persona story is exercisable from the dashboard. The seeded `reviewer` user is a member.

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

@@ -12,11 +12,15 @@ Every string is a markdown/text template run through the same `{{domain.path}}`
 
 | Key | Level | Purpose |
 |-----|-------|---------|
-| `x-lt-layout` | schema | `"active-history"`, `"active"`, `"facet-table"`, or `"table"` |
+| `x-lt-layout` | schema | `"active-history"`, `"active"`, `"facet-table"`, `"facet-board"`, or `"table"` |
 | `x-lt-help` | schema | Optional markdown header, interpolated with the active row |
 | `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: string, value: string }]` |
+| `x-lt-columns` | schema | Column definitions for `facet-table` layout: `[{ label, value, format? }]` |
+| `x-lt-group-by` | schema | `facet-board`: the `"domain.path"` whose value identifies each entity |
+| `x-lt-card` | schema | `facet-board`: the per-entity card — `{ title, state?, fields?: [{ label, value, format? }] }` |
+
+`format: "age"` on a `facet-table` column or `facet-board` field renders a timestamp as a compact age (`12m`, `3h`, `2d`) with the absolute time as its tooltip, repainted each minute — aging interim states are scannable at a glance.
 
 The **active** item is the first non-terminal escalation. The **history** column is lazy-loaded — a "Load full history" link fetches resolved items on demand (`status` defaults to `"resolved"`, `limit` to 25). Unknown or absent `x-lt-layout` is a safe no-op that falls back to the table.
 
@@ -73,3 +77,34 @@ Use when the queue contains many concurrent rows and the role's context is best
 ```
 
 A status dot precedes the first column automatically. ISO datetime values render as a readable relative date with a full-timestamp tooltip. Missing token values render as an em dash. Clicking any row navigates to the detail page. `x-lt-help` and `x-lt-active` are ignored in this layout.
+
+### `"facet-board"` — entity board
+
+Use when the rows describe **entities** (machines, stations) rather than a queue: within the current filter scope, rows group by the resolved `x-lt-group-by` value and each group renders one card from its most recent row (by `created_at`). The board reflects the scope — groups with no matching rows simply don't render.
+
+```json
+{
+  "x-lt-layout": "facet-board",
+  "x-lt-group-by": "metadata.fleetMachine",
+  "x-lt-card": {
+    "title": "{{metadata.fleetMachine}}",
+    "state": "{{metadata.machineState}}",
+    "fields": [
+      { "label": "PO",    "value": "{{metadata.po}}" },
+      { "label": "Order", "value": "{{metadata.orderId}}" },
+      { "label": "Since", "value": "{{escalation.created_at}}", "format": "age" }
+    ]
+  }
+}
+```
+
+The card's `state` renders as a status chip (a stable hue per token — commonly a subtype or a metadata state facet). The grid wraps to the viewport (wall-screen friendly). `x-lt-help` renders above the board as in `facet-table`. In the digital-twin pattern — each machine advertising one live pending row — the board is exact by construction; for wider scopes it groups the fetched page, with standard pagination beyond it.
+
+Cards are fully interactive (`x-lt-group-by` should be a `metadata.*` path so the facet affordances apply):
+
+- **Click** opens the group's latest row in the detail view.
+- **⇧ click** adds the entity's facet to the live filter set — additive, so shift-clicking narrows the board in place and the facet chips row shows each condition with its own remove.
+- **Hovering the card footer** reveals the entity's history as the filtered **table** or **timeline** view (the same view modes the queue offers everywhere else).
+- **Fields bound to a pure `{{metadata.KEY}}` token** carry the same hover pair the table's metadata cells offer: **filter** (narrows within the current role; ⇧ click adds to the current filters) and **search** (the facet across all roles).
+
+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)).

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

@@ -10,6 +10,17 @@ A field can be shown or hidden based on a value in the escalation context. Apply
 
 The value at `domain.path` is evaluated for truthiness. If truthy, the field shows; if absent, null, false, or an empty string, it is hidden. Prefix `!` to invert — show when the value is absent or falsy.
 
+### Equality forms
+
+Compare the resolved value's string form against a literal:
+
+```json
+"x-lt-showIf": "resolver.designatedStation=DRAFT"
+"x-lt-showIf": "resolver.designatedStation!=DRAFT"
+```
+
+The expected value is the raw remainder after the operator (trimmed; no quoting). Numbers and booleans compare via their string form (`metadata.count=3`, `metadata.live=true`). An absent value compares as the empty string — so `=X` is false and `!=X` is true when the path is missing. `resolver.` conditions react live as the user edits, exactly like the truthy form — this is what drives per-designation sub-surfaces on verdict forms (different fields for send-to-design vs send-to-printing).
+
 ### Domains
 
 | Domain | Resolves against |

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

@@ -10,6 +10,7 @@ For rich inputs beyond standard HTML types, set `x-lt-widget` on any field:
 | `"rich-text"` | Tall textarea for formatted text input. |
 | `"markdown"` | Markdown source rendered with headings, tables, lists, code blocks. Editable by default; set `readOnly: true` for a pure content block. |
 | `"checklist"` | Dynamic labeled checkboxes driven by runtime data. Items come from a `"domain.path"` declared in `x-lt-source`. |
+| `"attachment"` | ReadOnly display of a captured binary (data URL or fetchable URL): images inline with click-to-full-size, everything else as a safe open/download link. `"image"` is an accepted alias. |
 
 ---
 
@@ -75,6 +76,27 @@ The submitted value is a PNG data URL of the canvas drawing.
 
 ---
 
+## Attachment
+
+ReadOnly display of a binary captured earlier — typically by the `file-upload` widget on a prior form. The reporting form uploads the evidence (a defect photo, a signed PDF, a scan); the review form shows it:
+
+```json
+{
+  "properties": {
+    "defect_evidence": {
+      "type": "string",
+      "readOnly": true,
+      "x-lt-widget": "attachment",
+      "description": "Uploaded by the reporting form"
+    }
+  }
+}
+```
+
+The value is a data URL or a fetchable URL. Rendering dispatches on content type: `image/*` renders inline (constrained, click for full size); everything else — PDFs, scans, arbitrary binaries — renders as a labeled open/download affordance and is never embedded as a document (inlining arbitrary `data:` content is an XSS vector; the image context is script-inert). `"image"` is an accepted alias when the schema wants to name the constrained intent. An empty value reads as a quiet "No attachment".
+
+---
+
 ## Markdown
 
 Without `readOnly`, the field is a markdown editor — the resolver writes source in a Write/Preview toggle and the submitted value is the markdown text.

package/docs/hitl-guide.md

@@ -19,7 +19,7 @@ This works because the form is data: a JSON Schema stored on the role, versioned
 | 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) |
-| A role-authored list page for the whole queue | List schema | [x-lt-list-schema.md](hitl/x-lt-list-schema.md) |
+| A role-authored list page — document views, facet tables, entity card boards | List schema | [x-lt-list-schema.md](hitl/x-lt-list-schema.md) |
 | A fully custom UI nothing above can express | Iframe viewport | [iframe.md](hitl/iframe.md) |
 
 ---
@@ -62,6 +62,7 @@ When you author a HITL-backed workflow, the platform handles:
 - **Escalation chains** — users can re-route work to other roles
 - **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))
 - **Telemetry** — trace IDs link escalations to OpenTelemetry traces
 - **Bulk operations** — bulk claim, assign, escalate, triage, and cancel for queue management
 - **Cancellation** — cancel pending escalations from the API or dashboard
@@ -82,10 +83,11 @@ Ordered as a learning path — each file adds one capability to the same form:
 | Conditional visibility (`x-lt-showIf`, `x-lt-hide-if-empty`) | [x-lt-show-if.md](hitl/x-lt-show-if.md) |
 | Layout, ordering, sections, binding, help panel | [x-lt-layout.md](hitl/x-lt-layout.md) |
 | Custom widgets (checklist, file upload, code editor, signature, markdown) | [x-lt-widget.md](hitl/x-lt-widget.md) |
-| List schema (`active-history`, `facet-table`) | [x-lt-list-schema.md](hitl/x-lt-list-schema.md) |
+| List schema (`active-history`, `active`, `facet-table`, `facet-board` cards) | [x-lt-list-schema.md](hitl/x-lt-list-schema.md) |
 | Iframe viewport protocol | [iframe.md](hitl/iframe.md) |
 | Claim lifecycle, resolving from system code, outcome recording, cancellation | [resolution.md](hitl/resolution.md) |
 | Role routing, RBAC, scope, chains | [roles.md](hitl/roles.md) |
+| Pinned views, user preferences, role default pins | [pinned-views.md](hitl/pinned-views.md) |
 
 ---
 
@@ -93,14 +95,14 @@ 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` |
+| `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-require-all` | field | Checklist completion guard — every item must be checked, except items declared `required: false` |
 | `x-lt-language` | field | Syntax hint for the `code-editor` widget |
 | `accept` | field | File-type filter for `file-upload` (e.g. `".pdf,.png"`) |
 | `x-lt-bind` | field | Path in the resolver payload (e.g. `"customer.email"`) |
 | `x-lt-span` | field | Column span in a `two-column` layout (`2` = full width) |
-| `x-lt-showIf` | field | Show field when a value is truthy at `domain.path`; prefix `!` to invert |
+| `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-minimum` | field | Dynamic lower bound — resolves a `"domain.path"` from the escalation context |
@@ -109,7 +111,9 @@ Ordered as a learning path — each file adds one capability to the same form:
 | `x-lt-max-length` | field | Dynamic maximum string length — resolves a `"domain.path"` |
 | `x-lt-pattern-error` | field | Human-readable label for a `pattern` validation failure |
 | `x-lt-order` | schema | Field render sequence |
-| `x-lt-layout` | schema | `"two-column"` grid layout (form) or `"active-history"` / `"facet-table"` (list) |
+| `x-lt-layout` | schema | `"two-column"` grid layout (form) or `"active-history"` / `"facet-table"` / `"facet-board"` (list) |
+| `x-lt-group-by` | schema (list) | `facet-board`: the `"domain.path"` identifying each entity |
+| `x-lt-card` | schema (list) | `facet-board`: per-entity card — `{ title, state?, fields? }`; fields accept `format: "age"` |
 | `x-lt-help` | schema | Markdown guidance for the side panel's Help view |
 | `x-lt-context` | schema | Plain-text fallback for the Help view when `x-lt-help` is absent |
 | `x-lt-viewport` | schema | Replace the generated form with a custom iframe UI |

package/docs/schema-enforcement.md

@@ -0,0 +1,149 @@
+# Resolver Schema Enforcement
+
+A role's `form_schema` is an API contract, and the dashboard form is one client
+of it. Escalations resolve from many directions — the dashboard, the SDK, the
+CLI, webhooks that know a signal key, MCP agents, and simulated workforces —
+and every one of them submits the same artifact: a resolver payload shaped by
+the role's form schema and its `x-lt-bind` map. Schema enforcement makes the
+server the authority on that contract: roles that opt in validate every
+submitted payload at the API layer and reject violations before any state
+changes.
+
+## The contract
+
+A form schema declares, per field:
+
+- **presence** — membership in `required`, honoring `x-lt-showIf` (a field the
+  submitter cannot see never blocks submission; conditions evaluate against
+  the escalation surface plus the submitted values as `resolver.*`)
+- **type** — the declared JSON Schema `type`; a number field takes `1`, and
+  `"1"` is a violation
+- **enum** — membership in the field's declared choices
+- **bounds and patterns** — `minimum`/`maximum` (and their `x-lt-*` dynamic
+  variants resolved from the escalation context), lengths, `pattern`,
+  `format: email` / `format: uri`
+- **checklist completion** — `x-lt-require-all` against the items resolved
+  from the row's own envelope
+
+The pass that checks these is one isomorphic module
+(`shared/form-validation/`): the dashboard runs it pre-submission on the flat
+form values, and the API layer runs it on the submitted nested payload by
+inverting each field's `x-lt-bind` path first. One implementation on both
+sides means a payload that passes the client panel passes the server gate,
+and a rejection lists exactly the errors the panel would show.
+
+## Opting a role in
+
+Enforcement is per-role config: set `enforce_schema: true` on the role
+(`PATCH /api/roles/:role`, the `update_role` MCP tool, or the dashboard role
+editor). The schema validated against is resolved per escalation, most
+specific first:
+
+1. `metadata.form_schema` — a full form embedded on the row
+2. the `lt_role_schemas` snapshot pinned by `metadata.schema_version`
+3. the role's live (latest) `form_schema`
+
+A role that enforces but declares no schema has no contract to enforce, and
+its resolves proceed unchanged.
+
+## The rejection shape
+
+Every surface reports violations with one canonical body
+(`types/validation.ts`), HTTP status 422:
+
+```json
+{
+  "error": "resolverPayload failed schema validation (2 violations)",
+  "code": "schema_validation",
+  "violations": [
+    { "field": "contact_email", "message": "Enter a valid email address" },
+    { "field": "tier", "message": "Must be one of: free, starter, professional, enterprise" }
+  ],
+  "role": "intake-reviewer",
+  "schemaVersion": 3
+}
+```
+
+- **HTTP / routes** — the 422 response body
+- **SDK** — `result.status === 422`, `result.code === 'schema_validation'`,
+  full body in `result.data`; narrow with `isValidationErrorBody(result.data)`
+- **MCP** (`resolve_escalation`, `claim_and_resolve`) — the tool returns the
+  same JSON body with `isError: true`; `check_resolution` reports
+  `schema_enforced: true` on pending escalations whose role enforces
+- **CLI** — prints each violation beneath the error line
+- **Dashboard** — maps `violations` into the same errors panel the
+  pre-submission pass feeds
+
+Bulk surfaces (`resolve-by-ids`, `resolve-all-or-none`) tag each violation
+with its `escalationId`; all-or-none semantics extend to validation — one
+failing item blocks the batch before anything resolves.
+
+## Enforcement points
+
+All resolve surfaces run the same gate, before any resolution side effect:
+
+| Surface | Gate placement |
+|---|---|
+| `POST /escalations/:id/resolve` | after RBAC and claim-liveness checks, before path dispatch |
+| `POST /escalations/resolve-by-signal-key` | after write-scope check |
+| `POST /escalations/resolve-by-ids` | after write-scope check; only rows in enforcing roles load in full |
+| `POST /escalations/resolve-all-or-none` | after the unsupported-path check, before password redaction |
+| `POST /escalations/resolve-by-metadata` | inside the atomic statement: an enforcing target returns `validation_required` with nothing written; the validated payload re-invokes with the row id asserted, and the second pass re-checks `pending` inside the same guarded statement |
+| MCP `resolve_escalation` / `claim_and_resolve` | before the resolve; `claim_and_resolve` validates before claiming so a rejected payload never strands a claim |
+
+## Production cost model
+
+Role schemas change on admin timescales; resolves happen on work timescales.
+The gate is built so the hot path pays nothing for it:
+
+- **The enforcing-role set** (`SELECT role FROM lt_roles WHERE enforce_schema`)
+  is cached under `ROLE_ENFORCEMENT_CACHE_TTL_MS` (default 30s). Every surface
+  consults the cached set first — with no enforcing roles involved, a resolve
+  adds zero SQL.
+- **Pinned schema snapshots** are immutable and cache indefinitely (LRU-bounded).
+- **Latest schemas** cache under the same TTL.
+- In-process role writes invalidate immediately; across a container fleet,
+  staleness is bounded by one TTL window. Escalations that pin
+  `schema_version` are immune to latest-schema staleness.
+
+Surfaces that already load the row (by id, by signal key, all-or-none)
+validate with zero additional reads beyond the cached schema. Bulk-by-ids
+shares its RBAC scope-row read with the gate and loads full rows only for
+enforcing targets.
+
+## Typed consumption
+
+Enforcement guarantees what entered the system; `parseResolverPayload`
+(exported from the SDK) gives workflow code the consuming half. Declare the
+payload shape once as a zod schema, derive the type from it, and parse
+resolutions through it at the activity boundary:
+
+```typescript
+import { z } from 'zod';
+import { parseResolverPayload } from '@longtail/sdk';
+
+export const IntakeResolverV1Schema = z.object({
+  customer: z.object({ name: z.string(), email: z.string() }),
+  contract: z.object({ tier: z.enum(['starter', 'professional']), approved: z.boolean() }),
+});
+export type IntakeResolverV1 = z.infer<typeof IntakeResolverV1Schema>;
+
+const intake = parseResolverPayload(IntakeResolverV1Schema, response);
+intake.customer.name; // typed and runtime-checked
+```
+
+A non-conforming payload throws `ResolverPayloadTypeError` carrying the same
+`{ field, message }` violation list, with the ZodError as `cause`. The
+`rich-form` example (`examples/workflows/rich-form/`) shows the full pattern:
+one zod schema as the single source of truth for the type, the runtime check,
+and the version pin.
+
+## Rollout pattern
+
+1. Confirm the role's submitters send complete payloads — `check_resolution`
+   returns the `form_schema` (fields, types, `x-lt-bind` paths) an agent needs
+   to construct one, and flags `schema_enforced` once the role opts in.
+2. Flip `enforce_schema: true` on the role.
+3. Watch for 422s: each one identifies a submitter with a payload gap and
+   names the exact fields. The dashboard is unaffected — its pre-submission
+   pass is the same code.

package/package.json

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