@hotmeshio/long-tail 0.9.5 → 0.10.0

package/docs/faceted-routing.md

@@ -44,6 +44,7 @@ interface FacetQuery {
   exists?: string[];                // metadata ? key — facet must be present
   status?: string;                  // e.g. 'pending'
   available?: boolean;              // true = unclaimed/expired only; false = held now
+  jeopardy?: boolean;               // true = past the role's priority threshold only
   orderBy?: { field: string; direction?: 'asc' | 'desc'; numeric?: boolean }[];
   limit?: number;
   offset?: number;
@@ -55,6 +56,14 @@ interface FacetQuery {
 text, or numeric when `numeric` is set). Every value is parameterized; only validated column
 names / metadata keys and a fixed operator set are ever interpolated.
 
+`jeopardy` keeps only rows past their role's priority threshold — the exact predicate behind
+the Pace Board's priority count, evaluated per row against the role's dials
+(`priority_facet` metadata timestamp, `created_at` when unset; `priority_threshold_minutes`,
+`sla_minutes` when unset; roles with no threshold contribute no rows). Because the count and
+the list share one expression, a jeopardy list's total always equals the badge that linked to
+it. On the HTTP surface it rides as `jeopardy=1`; the canonical deep link is
+`/escalations/available?role=<r>&jeopardy=1&view=table&orderBy=[{"field":"metadata.<facet>"|"created_at","direction":"asc"}]`.
+
 ```typescript
 // Pending, available diabetic-certified work needing PLA, soonest-deadline first.
 const query: FacetQuery = {

package/docs/hitl/escalation.md

@@ -0,0 +1,206 @@
+# Creating Escalations
+
+## `conditionLT` — Atomic Pattern
+
+Pass an escalation config to `conditionLT`. The escalation row, its metadata, and the resume timer all commit inside the workflow's Leg1 checkpoint — one write, crash-safe. The `signal_key` on the row is the resume key: the dashboard resolve endpoint and `POST /api/escalations/resolve-by-signal-key` both resume this job in place, and the `system.escalation.{id}.created` event fires automatically.
+
+```typescript
+import { conditionLT } from '@hotmeshio/long-tail';
+
+export async function approvalWorkflow(envelope: LTEnvelope) {
+  const ctx = Durable.workflow.workflowInfo();
+  const signalId = `approval-${ctx.workflowId}`;
+
+  const decision = await conditionLT<{ approved: boolean; notes?: string }>(signalId, {
+    role: 'finance-reviewer',
+    type: 'approval',
+    subtype: 'budget-request',
+    priority: 2,
+    description: `Budget approval needed: $${envelope.data.amount}`,
+    metadata: {
+      form_schema: {
+        title: 'Budget Approval',
+        properties: {
+          approved: { type: 'boolean', description: 'Approve this request?' },
+          notes: { type: 'string', format: 'textarea' },
+        },
+        required: ['approved'],
+      },
+    },
+    envelope: { data: envelope.data },
+    timeout: '72h',   // SLA: resume with false + expire the row if unresolved
+  });
+
+  if (decision === false) {
+    // SLA timer fired — the row is already status='expired', any late resolve returns already-expired
+    return { type: 'return' as const, data: { autoRejected: 'sla' } };
+  }
+  if (decision === null) {
+    // Escalation was cancelled (workflow terminated or explicit cancel)
+    return { type: 'return' as const, data: { cancelled: true } };
+  }
+
+  if (decision.approved) {
+    // ... approved flow ...
+  } else {
+    // ... rejection flow ...
+  }
+}
+```
+
+`conditionLT` returns `T | false | null`:
+- `T` — the human's resolver payload
+- `false` — SLA timeout (omit `timeout` for an open-ended wait)
+- `null` — cancellation (workflow terminated or explicit cancel)
+
+### Row completeness guarantee
+
+Every field of the config — including all `metadata` facets — commits inside the Leg1 checkpoint. A claim-by-metadata router or a version-pinned facet reads a complete row from its first visible moment; there is no window where a row is visible but its metadata is still en route.
+
+### Early-signal buffering
+
+A resolve that races ahead of the `conditionLT` registration (a fast webhook, or a payload deposited before the workflow starts) is held as a pending signal and delivered when the wait registers — 10 minutes by default; pass `expire` to `signal()` when signaling early on purpose. Fan-out (`Promise.all` over many waits) scales the same way.
+
+---
+
+## Versioned Role Schemas
+
+Every role carries a versioned `form_schema`. Every save that changes it appends an immutable snapshot to `lt_role_schemas` and advances the role's current version. Escalations pin one with `schemaVersion`:
+
+```typescript
+const decision = await conditionLT<{ approved: boolean; lotNumber: string }>(signalId, {
+  role: 'reviewer',
+  description: instructions,
+  schemaVersion: 3,   // renders role schema v3, always, regardless of later edits
+});
+```
+
+The pin travels as `metadata.schema_version` on the row (GIN-indexed, queryable like any facet). A pin that names a missing version fails at creation with a 400 — it never silently falls through to a different version. Without a pin, the role's latest schema always applies.
+
+Inspect versions:
+- `GET /api/roles/:role/schema?version=N`
+- `GET /api/roles/:role/schema/versions`
+- `lt.roles.getSchema` / `lt.roles.listSchemaVersions`
+- `ltc roles schema <role> --version N`
+- `get_role_schema` / `list_role_schema_versions` admin MCP tools
+- Dashboard: `/admin/roles/:role/schema`
+
+Save a new version: `PATCH /api/roles/:role` with `form_schema` (+ optional `change_summary`), `lt.roles.update`, `ltc roles save-schema <role> --file schema.json`, the `update_role` MCP tool, or the dashboard schema editor.
+
+---
+
+## Form Schema Resolution
+
+The resolver form uses the most specific schema available for each escalation row:
+
+1. **`metadata.form_schema`** — a full JSON Schema embedded on the row. Use when different escalation points in the same workflow need different forms.
+2. **The role's versioned `form_schema`** — when `metadata.schema_version` is set, the snapshot at that version renders; otherwise the role's latest applies.
+
+---
+
+## Working Examples
+
+The reference examples ship as fully runnable seeds:
+
+- `examples/workflows/rich-form/` — `intake-reviewer` role: two-column layout, ordering, date and email formats, enum, file upload, spans, required fields, `x-lt-bind`, `x-lt-help`
+- `examples/workflows/checklist-confirmation/` — `checklist-operator` role: checklist widget with `x-lt-source` driving dynamic items from the envelope
+- `examples/workflows/constraint-form/` — `quality-reviewer` role: the reference for all pre-submission guards — hidden required field, dynamic checklist, min/max, pattern, dynamic numeric and string-length bounds
+
+### Simple approval
+
+```typescript
+import { conditionLT } from '@hotmeshio/long-tail';
+
+export async function approveSpendWorkflow(envelope: LTEnvelope) {
+  const ctx = Durable.workflow.workflowInfo();
+
+  const decision = await conditionLT<{ approved: boolean; notes?: string }>(
+    `spend-approval-${ctx.workflowId}`,
+    {
+      role: 'finance-reviewer',
+      type: 'approval',
+      description: `Approve spend of $${envelope.data.amount} for ${envelope.data.vendor}`,
+      priority: 2,
+      metadata: {
+        form_schema: {
+          title: 'Spend Approval',
+          description: 'Review and approve or reject this spend request.',
+          required: ['approved'],
+          properties: {
+            approved: { type: 'boolean', description: 'Check to approve' },
+            notes: { type: 'string', format: 'textarea', description: 'Optional comments' },
+          },
+        },
+      },
+      timeout: '48h',
+    },
+  );
+
+  if (decision === null) return { type: 'return' as const, data: { cancelled: true } };
+  if (decision === false) return { type: 'return' as const, data: { timedOut: true } };
+
+  if (decision.approved) {
+    await releasePayment(envelope.data);
+  } else {
+    await notifyRejection(envelope.data, decision.notes);
+  }
+}
+```
+
+### Checklist confirmation
+
+Dynamic checklist where item labels come from the workflow's envelope, not the static schema. Item count and wording vary per escalation without touching the form schema.
+
+```typescript
+import { conditionLT } from '@hotmeshio/long-tail';
+
+export async function stationCheckWorkflow(envelope: LTEnvelope) {
+  const ctx = Durable.workflow.workflowInfo();
+
+  const steps = [
+    { id: 'step_0', label: 'Verify patient ID matches the order' },
+    { id: 'step_1', label: 'Confirm dosage and route of administration' },
+    { id: 'step_2', label: 'Sign the dispensing log' },
+  ];
+
+  const result = await conditionLT<{ checks: Record<string, boolean> }>(
+    `station-check-${ctx.workflowId}`,
+    {
+      role: 'station-operator',
+      type: 'station-check',
+      description: 'Complete all station checks before releasing',
+      priority: 1,
+      envelope: {
+        checklist_items: steps,
+        formDefaults: {
+          checks: Object.fromEntries(steps.map((s) => [s.id, false])),
+        },
+      },
+      metadata: {
+        form_schema: {
+          title: 'Station Check',
+          description: 'Work through each step and confirm completion.',
+          required: ['checks'],
+          properties: {
+            checks: {
+              type: 'object',
+              'x-lt-widget': 'checklist',
+              'x-lt-source': 'envelope.checklist_items',
+              description: 'Check each step when complete',
+            },
+          },
+        },
+      },
+    },
+  );
+
+  if (!result) return { type: 'return' as const, data: { cancelled: true } };
+
+  const allClear = Object.values(result.checks).every(Boolean);
+  const failed = steps.filter((s) => !result.checks[s.id]).map((s) => s.label);
+
+  if (!allClear) {
+    await flagIncomplete({ failed });
+  }
+}
+```

package/docs/hitl/form.md

@@ -0,0 +1,162 @@
+# Form Fields
+
+The dashboard renders forms automatically from JSON Schema. No frontend code needed.
+
+---
+
+## Field Types
+
+| JSON Type | Renders As |
+|-----------|-----------|
+| `boolean` | Checkbox toggle |
+| `number` | Number input |
+| `string` | Text input (default) |
+| `string` + `enum` | Dropdown select |
+| `null` | Read-only "null" display |
+| `array` | Tag display (read-only) |
+| `object` | Nested section with recursive fields, or a widget (see [x-lt-widget.md](x-lt-widget.md)) |
+
+---
+
+## String Format Extensions
+
+Use `format` on any `string` field to get a specialized input:
+
+| Format | Renders as |
+|--------|-----------|
+| `"password"` | Masked input — ephemeral token replaces the value in the resolver payload |
+| `"date"` | Date picker |
+| `"date-time"` | Date + time picker |
+| `"email"` | Email input — pre-submission guard enforces valid address format |
+| `"uri"` | URL input — pre-submission guard enforces `https?://...` format |
+| `"textarea"` | Multi-line textarea |
+
+```json
+{
+  "properties": {
+    "due_date":      { "type": "string", "format": "date" },
+    "contact_email": { "type": "string", "format": "email" },
+    "report_url":    { "type": "string", "format": "uri" },
+    "notes":         { "type": "string", "format": "textarea" }
+  }
+}
+```
+
+---
+
+## Required Fields
+
+Fields listed in `required` show a red asterisk and block submission when empty:
+
+```json
+{
+  "required": ["decision"],
+  "properties": {
+    "decision": { "type": "string", "enum": ["approve", "reject"] },
+    "notes":    { "type": "string", "description": "Optional comments" }
+  }
+}
+```
+
+A required `object` field (e.g. a `checklist` widget) is satisfied when at least one of its boolean values is `true`.
+
+Hidden fields — those suppressed by `x-lt-showIf` at submit time — are skipped from required validation. See [x-lt-show-if.md](x-lt-show-if.md) for conditional required fields.
+
+---
+
+## Read-Only Fields
+
+Fields with `readOnly: true` display as static text — the value is shown but cannot be edited:
+
+```json
+{
+  "properties": {
+    "request_amount": { "type": "number", "readOnly": true },
+    "approved_amount": { "type": "number", "description": "Enter the approved amount" }
+  }
+}
+```
+
+Use `readOnly` with `x-lt-hide-if-empty: true` to suppress empty fact fields entirely (see [x-lt-show-if.md](x-lt-show-if.md)).
+
+Use `readOnly` with `x-lt-widget: "markdown"` to embed a rendered content block — SOPs, checklists, review instructions — inside the form (see [x-lt-widget.md](x-lt-widget.md)).
+
+---
+
+## Schema Title and Description
+
+`title` and `description` at the schema root appear in the form header:
+
+- **`title`** — shown as the form section header
+- **`description`** — short subtitle beneath the title; keep to a phrase; longer guidance belongs in [`x-lt-help`](x-lt-layout.md#help-panel-x-lt-help)
+
+Individual field `title` and `description` render as the field label and inline help text, respectively.
+
+```json
+{
+  "title": "Expense Approval",
+  "description": "Review the expense report and approve or reject with notes.",
+  "properties": {
+    "approved": {
+      "type": "boolean",
+      "title": "Approve",
+      "description": "Check to approve. Leave unchecked to reject."
+    }
+  }
+}
+```
+
+---
+
+## Credential Fields
+
+Password fields (`"format": "password"`) are masked in the UI. On submit, the platform replaces the plain-text value with a short-lived ephemeral token (`eph:v1:*`, 15-minute TTL) before storing or signaling it to the workflow — the secret is never written to the escalation record.
+
+```json
+{
+  "properties": {
+    "api_key":    { "type": "string", "description": "API Key" },
+    "api_secret": {
+      "type": "string",
+      "format": "password",
+      "description": "API Secret — stored as an ephemeral token, never in plain text"
+    }
+  },
+  "required": ["api_key", "api_secret"]
+}
+```
+
+The workflow receives the `eph:v1:*` token and passes it to the integration layer for redemption.
+
+---
+
+## Draft Persistence
+
+Form edits are saved locally (browser storage, per escalation) a moment after each change and restored when the resolver returns to the item — a lapsed claim, an accidental navigation, or a browser restart keeps typed input intact. The draft holds field values only; the form definition always renders from the current schema resolution, so a draft never resurrects a stale form. Pristine, untouched defaults are not stored. The draft clears when the escalation is resolved, acknowledged, or cancelled from that browser.
+
+---
+
+## Accessibility
+
+Generated form controls carry the wiring assistive technology depends on:
+
+- Every input is associated with its label (`label[for]` → `input[id]`), and checkbox labels wrap their controls.
+- Required fields set `aria-required`; failing fields set `aria-invalid` and link their message via `aria-describedby`.
+- Inline validation messages and the side panel's error list render as `role="alert"` live regions, so corrections are announced as they happen.
+- The checklist widget is a `role="group"` labeled by its field description.
+- A locked form (unclaimed, claimed by another user, or a lapsed claim) is `inert`: its fields leave the tab order entirely rather than merely looking disabled.
+- Modals are `role="dialog"` with `aria-modal` and a labelled title; Escape closes them.
+- The error panel's entries are buttons — clicking one scrolls to and focuses the failing field, keyboard included.
+
+---
+
+## Designing the Form
+
+To create a polished resolve experience:
+
+1. Set `title` on the schema — it becomes the form section header
+2. Set `x-lt-help` — SOPs, tables, and links render in the side panel as markdown with `{{domain.path}}` tokens for live record values (see [x-lt-layout.md](x-lt-layout.md#help-panel-x-lt-help))
+3. Use `readOnly` fields for context the human needs to see but not change
+4. Use `x-lt-order` to put the most important fields first (see [x-lt-layout.md](x-lt-layout.md))
+5. Use `required` to guide users on what must be filled
+6. Use field-level `description` for inline help text

package/docs/hitl/iframe.md

@@ -0,0 +1,170 @@
+# Iframe Viewport Protocol
+
+For fully custom UIs — PDF viewers, complex multi-step forms, specialized domain interfaces — replace the generated form with an iframe. The iframe owns its entire surface: platform-side validation, layout, widgets, and draft persistence apply to the generated form, so the embedded app provides its own. Reach for the schema-driven form first ([choosing your surface](../hitl-guide.md#choosing-your-surface)); use the iframe when the domain demands a surface the schema cannot express.
+
+---
+
+## Schema Declaration
+
+```json
+{
+  "x-lt-viewport": {
+    "type": "iframe",
+    "src": "https://your-app.example.com/hitl-form"
+  },
+  "properties": { }
+}
+```
+
+When `x-lt-viewport` is present, the dashboard renders an iframe instead of the standard form. The `properties` block still defines the resolver payload shape for typing purposes.
+
+---
+
+## URL Token Substitution
+
+The `src` value supports `{key}` tokens — single-brace, flat key lookup. The dashboard expands them at render time using values merged from three sources, in priority order:
+
+| Priority | Source | Field |
+|----------|--------|-------|
+| 1 (highest) | `escalation_payload` | Per-escalation context set by the workflow |
+| 2 | `envelope` | Input envelope set by the workflow |
+| 3 (lowest) | `metadata` | Row metadata |
+
+Keys present in multiple sources resolve from the highest-priority one. A key with no match is left as `{key}` in the final URL.
+
+### Example — CAD designer workbench
+
+The `cad-designer` role embeds a WebGL editor. Each escalation carries `workbenchId` and `companyId` in its payload; the dashboard injects them into the iframe URL at render time:
+
+```typescript
+// Form schema on the role
+const WORKBENCH_FORM_SCHEMA = {
+  'x-lt-viewport': {
+    type: 'iframe',
+    src: `${BASE_URL}/design?workbenchId={workbenchId}&companyId={companyId}`,
+  },
+  properties: {
+    stl_url: {
+      type: 'string',
+      description: 'Object-storage URL of the completed design, set by the embedded editor.',
+    },
+  },
+};
+
+// Workflow side — the wait is a normal conditionLT; the iframe submits the payload
+const design = await conditionLT<{ stl_url: string }>(signalId, {
+  role: 'cad-designer',
+  description: 'Design the orthotic insole for this order.',
+  escalation_payload: JSON.stringify({ workbenchId, companyId }),
+});
+if (design) {
+  await attachDesign(design.stl_url);
+}
+```
+
+At render time the dashboard produces:
+
+```
+https://editor.internal/design?workbenchId=wb-123&companyId=co-456
+```
+
+`{workbenchId}` and `{companyId}` are resolved from `escalation_payload`, which has the highest priority — so even if the same keys appear in `envelope` or `metadata`, the payload values win.
+
+### Common token patterns
+
+| Goal | Source to use | Token |
+|------|--------------|-------|
+| Per-escalation session or record ID | `escalation_payload` | `{sessionId}`, `{orderId}` |
+| Tenant or company context | `escalation_payload` or `envelope` | `{companyId}`, `{tenantId}` |
+| Role-wide base path (same for all escalations) | `metadata` on the escalation or schema-level constant | Embed directly in `src` |
+| Configuration passed at escalation creation | `envelope` | `{formMode}`, `{locale}` |
+
+> **Note:** The `{key}` syntax used in the `src` URL is distinct from the `{{domain.path}}` syntax used in `x-lt-help`, `x-lt-active`, and list schema templates. The URL substitution is a flat key lookup across merged sources; the template tokens do a domain-routed deep path lookup.
+
+---
+
+## Message Protocol
+
+Communication happens via `window.postMessage`.
+
+### Parent → Iframe
+
+```typescript
+// Sent when the iframe signals ready (or on load)
+{
+  type: 'lt:init',
+  escalation: {
+    id: string,
+    type: string,
+    subtype: string,
+    description: string | null,
+    status: string,
+    priority: number,
+    role: string,
+    workflow_type: string | null,
+  },
+  schema: Record<string, unknown>,   // The full form schema
+}
+
+// Optional: parent requests the iframe to submit
+{ type: 'lt:requestSubmit' }
+```
+
+### Iframe → Parent
+
+```typescript
+// Signal that the iframe is ready to receive init data
+{ type: 'lt:ready' }
+
+// Submit the human's response — triggers escalation resolution
+{ type: 'lt:submit', payload: { approved: true, notes: '...' } }
+
+// Escalate to a different role
+{ type: 'lt:escalate', target: 'senior-reviewer' }
+
+// Auto-resize the iframe height
+{ type: 'lt:resize', height: 600 }
+```
+
+---
+
+## Minimal Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head><title>Custom HITL Form</title></head>
+<body>
+  <div id="form"></div>
+  <button id="submit">Approve</button>
+
+  <script>
+    window.parent.postMessage({ type: 'lt:ready' }, '*');
+
+    window.addEventListener('message', (event) => {
+      if (event.data.type === 'lt:init') {
+        const { escalation, schema } = event.data;
+        document.getElementById('form').textContent =
+          `Reviewing: ${escalation.description}`;
+      }
+    });
+
+    document.getElementById('submit').addEventListener('click', () => {
+      window.parent.postMessage({
+        type: 'lt:submit',
+        payload: { approved: true, reviewed_at: new Date().toISOString() },
+      }, '*');
+    });
+  </script>
+</body>
+</html>
+```
+
+---
+
+## Security
+
+- The iframe runs with `sandbox="allow-scripts allow-same-origin allow-forms"`
+- The parent validates message origins — only messages from the iframe's declared origin are accepted
+- The `envelope` field (which may contain secrets) is not sent to the iframe
+- Only safe escalation metadata (`id`, `type`, `description`, `status`, `priority`, `role`) is exposed