@hotmeshio/long-tail 0.9.6 → 0.10.0

package/docs/hitl/resolution.md

@@ -0,0 +1,166 @@
+# Resolution
+
+## Claim Lifecycle
+
+A claim is a **work lock**: `assigned_to` names the holder and `assigned_until` bounds the window. The lock exists only while the window is active — this is what `isEffectivelyClaimed` means throughout the platform. Two related shapes use the same columns without being locks:
+
+- **Unclaimed** (`assigned_to` null) — available to the whole role queue, and resolvable by system code.
+- **Durable pre-assignment** (`assigned_to` set, no window) — a workflow targeting a named user (the one-time-user JIT-form shape, see [roles.md](roles.md#one-time-and-pre-assigned-escalations)). Routing, not a lock.
+
+### Claiming and extending
+
+Claiming takes a duration (configurable options via `LT_CLAIM_DURATION_OPTIONS`; a custom duration is always available). Re-claiming a row you already hold extends the window — the claim endpoint is idempotent per assignee and reports `isExtension: true`.
+
+In the dashboard, 90 seconds before the window lapses a **Claim Expiring** dialog offers the same duration options to extend. Dismissing it lets the window run out: at expiry the form locks, the action bar returns to its claim state, and the item is available to the queue again. Typed input survives — see draft persistence in [form.md](form.md#draft-persistence) — so re-claiming picks up exactly where the resolver left off.
+
+### The claim-liveness rule
+
+A resolve presented **by escalation id** must not act against a claim lock. The rule blocks exactly two states:
+
+| Row state | Resolve by id |
+|-----------|---------------|
+| Unclaimed | Allowed (system resolvers act on unclaimed rows by design) |
+| Durable pre-assignment (no window) | Allowed |
+| Live window, held by the caller | Allowed |
+| Live window, held by someone else | **409** — the lock is theirs |
+| Caller's own window, lapsed | **409** — stale work; re-claim to resolve |
+| Someone else's window, lapsed | Allowed — the lock is gone, the row is back in the pool |
+
+The rule applies to every principal, including superadmins: the claim is a work lock, not an authorization scope. It is enforced twice — an advisory check before any resolution side effects fire, and atomically inside the SDK's guarded resolve UPDATE (`assertClaim`), so a claim that lapses mid-request still cannot land a stale resolution.
+
+`resolveBySignalKey` and `resolveByMetadata` are claim-agnostic: they are system ingress surfaces (webhooks, domain events) that resolve on behalf of the process, not a claimant.
+
+---
+
+## Resolving from System Code
+
+When a backend service (not the dashboard UI) needs to resolve an escalation — for example, an ingress handler that receives a webhook or processes a domain event — use the escalation SDK methods directly.
+
+### By escalation ID
+
+Use when you already have the escalation UUID (e.g. stored in your own DB alongside the order):
+
+```typescript
+const result = await lt.escalations.resolve({
+  id: escalationId,
+  resolverPayload: { approved: true, targetStatus: 'ready' },
+});
+```
+
+This routes through the full resolution path for all escalation types.
+
+### By metadata key-value pair
+
+Use when you know a domain identifier (e.g. `orderId`) but not the escalation UUID. `resolveByMetadata` finds the highest-priority pending escalation matching the key-value pair and resolves it atomically — no pre-flight lookup, no TOCTOU:
+
+```typescript
+const result = await lt.escalations.resolveByMetadata({
+  key: 'orderId',
+  value: orderId,
+  resolverPayload: { approved: true, targetStatus: 'ready' },
+});
+
+if (result.status === 404) {
+  // No pending escalation for this orderId
+}
+```
+
+### By signal key
+
+When the signal key is deterministic and known to the caller (e.g. `station-done-${workflowId}`), use the signal-key path to skip the metadata lookup:
+
+```typescript
+await lt.escalations.resolveBySignalKey({
+  signalKey: `station-done-${workflowId}`,
+  resolverPayload: { approved: true },
+});
+```
+
+### Resolving a set atomically
+
+When one decision settles a set of waits — each with its own payload — use `resolveAllOrNone`:
+
+```typescript
+await lt.escalations.resolveAllOrNone({ items: [
+  { id: 'esc-aaa', resolverPayload: { decision: 'approve' } },
+  { id: 'esc-bbb', resolverPayload: { decision: 'reject' } },
+] });
+```
+
+Every listed row resolves with its own payload in one SQL statement, waking each parked workflow with its own value — or nothing resolves. A 409 names exactly the rows that blocked (`failedIds` + reasons). Pass `requireClaimed: true` to assert, inside the same statement, that every row is still assigned to the caller. See the [SDK reference](../api/sdk/escalations.md#resolveallornone) for the full contract.
+
+---
+
+## Recording the Outcome
+
+An escalation row carries **intent** — what was asked, who it routed to. Resolving it stamps the **outcome** onto the same row: every resolve surface takes an optional `metadata` patch merged into the row's GIN-indexed metadata.
+
+| Surface | How to pass it |
+|---------|----------------|
+| HTTP | `metadata` in the resolve body (`POST /api/escalations/:id/resolve`) |
+| SDK facade | `lt.escalations.resolve({ id, resolverPayload, metadata })` |
+| MCP | `metadata` arg on `claim_and_resolve` / `resolve_escalation` |
+| In-process library | `resolveEscalation(id, payload, metadata)` |
+
+```typescript
+await lt.escalations.resolve({
+  id,
+  resolverPayload: { approved: true },               // resumes the workflow; not indexed
+  metadata: { outcome: 'approved', reviewedBy: 'alice', durationMs: elapsed },
+});
+```
+
+The metadata patch is the durable, queryable record on the row. The resolver payload resumes the paused workflow and is not indexed separately. Use the metadata patch for audit trail and analytics — disposition, reviewer, time-to-resolve — so the escalation table answers *what was asked, what was decided, and how long it took* without a parallel log.
+
+---
+
+## Cancelling Escalations
+
+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`.
+
+### API
+
+```
+POST /api/escalations/:id/cancel        # single
+POST /api/escalations/bulk-cancel       # { "ids": [...] }
+```
+
+Returns 409 if the escalation is already resolved or cancelled.
+
+### Dashboard
+
+- **Escalations list** — select one or more rows and click **Cancel** in the bulk action bar.
+- **Escalation detail page** — a Cancel link appears in the action bar when the escalation is in `available` or `claimed_by_me` state.
+
+### Handling cancellation in workflows
+
+`conditionLT` returns `T | false | null`. Always guard before accessing the payload:
+
+```typescript
+const decision = await conditionLT<{ approved: boolean }>(signalId, escalationConfig);
+
+if (decision === null) {
+  // Escalation was cancelled
+  return { type: 'return' as const, data: { cancelled: true } };
+}
+if (decision === false) {
+  // Escalation timed out (SLA)
+  return { type: 'return' as const, data: { timedOut: true } };
+}
+
+// Normal path — decision is the resolver's payload
+if (decision.approved) { ... }
+```
+
+The `!decision` shorthand handles both cases when you don't need to distinguish between them:
+
+```typescript
+if (!decision) {
+  return { type: 'return' as const, data: { cancelled: true } };
+}
+```

package/docs/hitl/roles.md

@@ -0,0 +1,72 @@
+# Role Routing and RBAC
+
+## 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:
+
+```typescript
+const decision = await conditionLT<{ approved: boolean }>(signalId, {
+  role: 'finance-reviewer',   // only users with this role see it
+  description: `Approve spend of $${amount}`,
+  // ...
+});
+```
+
+---
+
+## Work-Surface Scope
+
+A `member` of a role carries a work-surface scope that narrows what they see and act on within that queue:
+
+| Scope field | Values | Meaning |
+|-------------|--------|---------|
+| `read_scope` | `self` / `all` | Which escalations the member sees |
+| `write_scope` | `none` / `self` / `all` | Which escalations the member can claim, resolve, or cancel |
+
+`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.
+
+See the [Roles API](../api/http/roles.md#work-surface-scope) for the five member profiles and the assignment contract.
+
+---
+
+## One-Time and Pre-Assigned Escalations
+
+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, {
+  role: 'customer-triage',
+  assigned_to: userId,     // pre-claim
+  description: 'Confirm your shipping address',
+  metadata: {
+    form_schema: {
+      title: 'Confirm Address',
+      properties: {
+        address:   { type: 'string' },
+        confirmed: { type: 'boolean' },
+      },
+      required: ['confirmed'],
+    },
+  },
+});
+```
+
+---
+
+## Escalation Chains
+
+Users can escalate to other roles via the "Escalate" tab on the detail page. Configure chain targets in Admin > Roles. Each role lists which other roles it can escalate to. Common shape:
+
+```
+Analyst → Senior Analyst → Manager → VP
+```
+
+Chains are runtime RBAC — they control who can receive an escalation handed off from this role. `parent_role` and `ops_visible` are the process graph Operations renders.
+
+---
+
+## Schema Versioning
+
+See [escalation.md](escalation.md#versioned-role-schemas) for the full versioning contract — how to pin a schema version on an escalation row, how to inspect versions, and how to save a new version.

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

@@ -0,0 +1,167 @@
+# Layout, Ordering, Sections, Binding, and Help
+
+---
+
+## Two-Column Layout (`x-lt-layout`)
+
+Set `"x-lt-layout": "two-column"` at the schema root to arrange fields in a 2-column grid. Use `"x-lt-span": 2` on a field to span the full width.
+
+```json
+{
+  "x-lt-layout": "two-column",
+  "properties": {
+    "first_name": { "type": "string" },
+    "last_name":  { "type": "string" },
+    "notes":      { "type": "string", "format": "textarea", "x-lt-span": 2 }
+  }
+}
+```
+
+---
+
+## Field Ordering (`x-lt-order`)
+
+By default, fields render in JSON key order. `x-lt-order` sets an explicit sequence. Fields not listed in `x-lt-order` render after the listed ones in their original key order.
+
+```json
+{
+  "x-lt-order": ["priority", "decision", "notes"],
+  "properties": {
+    "notes":    { "type": "string" },
+    "decision": { "type": "string", "enum": ["approve", "reject", "defer"] },
+    "priority": { "type": "number" }
+  }
+}
+```
+
+---
+
+## Section Groups (`x-lt-section`)
+
+Group related fields under a labeled section by adding `"x-lt-section": "Label"` to each property. Fields that share the same consecutive section name are collected into one group with a header.
+
+Sections are ordered by the first field that carries the section name (respects `x-lt-order`). A field without `x-lt-section` belongs to an unnamed group rendered without a header. Named sections render with a left accent line, a small icon, and the label in uppercase.
+
+```json
+{
+  "x-lt-layout": "two-column",
+  "x-lt-order": ["patient_id", "heel_cup", "pdac", "approved", "notes"],
+  "properties": {
+    "patient_id": { "type": "string", "readOnly": true, "x-lt-section": "Facts", "x-lt-hide-if-empty": true },
+    "heel_cup":   { "type": "string", "readOnly": true, "x-lt-section": "Facts", "x-lt-hide-if-empty": true },
+    "pdac":       { "type": "boolean","readOnly": true, "x-lt-section": "Facts", "x-lt-hide-if-empty": true },
+    "approved":   { "type": "string", "enum": ["yes", "no"],       "x-lt-section": "Action" },
+    "notes":      { "type": "string", "format": "textarea", "x-lt-span": 2, "x-lt-section": "Action" }
+  }
+}
+```
+
+---
+
+## Payload Binding (`x-lt-bind`)
+
+The form is flat; the payload the workflow consumes rarely is. A field may declare `x-lt-bind` — the path its value occupies in the resolver payload (dot keys, optional `[n]` indices). The dashboard maps the flat form through the binds on submit, and reverse-maps `envelope.formDefaults` through them to prefill. A field with no bind lands at its own name at the payload root.
+
+```json
+{
+  "properties": {
+    "customer_name":  { "type": "string",  "x-lt-bind": "customer.name" },
+    "contact_email":  { "type": "string",  "format": "email", "x-lt-bind": "customer.email" },
+    "tier":           { "type": "string",  "enum": ["starter", "professional"], "x-lt-bind": "contract.tier" },
+    "notes":          { "type": "string",  "format": "textarea" }
+  }
+}
+```
+
+Submitting `{ customer_name, contact_email, tier, notes }` produces:
+
+```json
+{
+  "customer": { "name": "…", "email": "…" },
+  "contract": { "tier": "…" },
+  "notes": "…"
+}
+```
+
+Only the form is versioned on the role — the payload shape is the workflow's own contract, produced by the binds. Evolve the form and its binds together, and the workflow's resolver type in the same commit.
+
+---
+
+## Help Panel (`x-lt-help`)
+
+Schema-level `x-lt-help` carries the form's guidance — checklists, tier tables, callouts, links — as markdown. The dashboard renders it in the side panel beside the form, so the form itself stays a clean title-and-fields surface while the SOP sits one glance to the right. The help text versions with the form: it lives in the same `form_schema` snapshot in `lt_role_schemas`.
+
+```json
+{
+  "title": "Customer Intake",
+  "x-lt-help": "### Review checklist\n\n1. Confirm the **legal name** matches.\n2. Send a test message before approving.\n\nThis escalation is **{{escalation.status}}** in the **{{escalation.role}}** queue.",
+  "properties": { }
+}
+```
+
+### `{{domain.path}}` tokens
+
+`{{domain.path}}` tokens in `x-lt-help` interpolate live values from the escalation record. Five domains are available:
+
+| Domain | Resolves against |
+|--------|-----------------|
+| `escalation` | The escalation row (`{{escalation.role}}`, `{{escalation.status}}`) |
+| `metadata` | The row's metadata dict (`{{metadata.schema_version}}`) |
+| `envelope` | The workflow-sent input envelope (`{{envelope.min_score}}`) |
+| `payload` | The escalation context payload (`{{payload.category}}`) |
+| `resolver` | The submitted resolver payload (`{{resolver.notes}}`) |
+
+A missing value renders as an em dash. Links whose `href` starts with `/` navigate inside the dashboard.
+
+### Help fallback chain
+
+The side panel's Help view resolves in order: `x-lt-help` → `x-lt-context` (plain text) → a state-aware hint ("Claim this escalation to enable the form", "Fill out the form and submit to resolve it", and so on). The panel always gives the resolver a prompt.
+
+The panel's other views surface the record itself:
+
+| View | Shows | Available to |
+|------|-------|--------------|
+| **Help** | `x-lt-help` markdown, or a state-aware hint | Everyone |
+| **Details** | Status, role, priority, claim provenance, timestamps | Everyone |
+| **AI Analysis** | Triage diagnosis and corrections | When AI is enabled and triage data is present |
+| **Metadata** | The row's metadata values | Everyone |
+| **Context** | Input envelope, escalation context, resolver payload | Everyone |
+| **Errors** | Pre-submission validation failures with click-to-focus | When submit is blocked |
+| **Record** | The raw escalation JSON | Builders (admins, superadmins, engineers) |
+
+---
+
+## Complete Layout Example
+
+Two-column intake form with sections, help panel, ordering, and bindings:
+
+```json
+{
+  "title": "Customer Intake",
+  "description": "Complete all required fields then submit.",
+  "x-lt-layout": "two-column",
+  "x-lt-order": ["first_name", "last_name", "email", "phone", "tier", "notes"],
+  "x-lt-help": "### Intake checklist\n\n1. Confirm the **legal name** matches the ID on file.\n2. Verify the email is reachable — send a test message.\n3. Select tier based on the sales order.\n\n> Escalate non-standard contract language to legal.",
+  "required": ["first_name", "last_name", "email", "tier"],
+  "properties": {
+    "first_name": { "type": "string",                             "x-lt-section": "Contact" },
+    "last_name":  { "type": "string",                             "x-lt-section": "Contact" },
+    "email":      { "type": "string", "format": "email",          "x-lt-section": "Contact", "x-lt-bind": "customer.email" },
+    "phone":      { "type": "string",                             "x-lt-section": "Contact" },
+    "tier": {
+      "type": "string",
+      "enum": ["free", "pro", "enterprise"],
+      "description": "Select the customer tier",
+      "x-lt-section": "Contract",
+      "x-lt-bind": "contract.tier"
+    },
+    "notes": {
+      "type": "string",
+      "format": "textarea",
+      "x-lt-span": 2,
+      "description": "Additional notes",
+      "x-lt-section": "Contract"
+    }
+  }
+}
+```

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

@@ -0,0 +1,75 @@
+# List Schema (`x-lt-list-schema`)
+
+The form schema formats one escalation on the detail page. A role can also own a `list_schema` that formats its whole list page — the list-page analog of the resolve form. It is opt-in and applies only when the list is scoped to exactly one role (`/escalations/available?role=<role>`). Absent, the list renders the standard engineer table; present, a rich role-authored view renders with a "Table view" toggle one click away.
+
+The list schema is versioned independently of the form schema — a list edit never bumps the form version. Edit it at `/admin/roles/:role/list-schema`. The list always renders the latest version.
+
+---
+
+## Vocabulary
+
+Every string is a markdown/text template run through the same `{{domain.path}}` token binding as `x-lt-help` (domains: `escalation | metadata | envelope | payload | resolver`, evaluated against each row). `body` strings render through the markdown renderer.
+
+| Key | Level | Purpose |
+|-----|-------|---------|
+| `x-lt-layout` | schema | `"active-history"`, `"active"`, `"facet-table"`, 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 }]` |
+
+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.
+
+---
+
+## Layouts
+
+### `"active-history"` — document workflow
+
+Use when the queue contains exactly one live item at a time and a history column is meaningful — a policy document, a looped review, a sequential approval chain.
+
+```json
+{
+  "x-lt-layout": "active-history",
+  "x-lt-help": "# {{metadata.title}}\nThe authoritative policy. One revision is live at a time.",
+  "x-lt-active": {
+    "title": "{{metadata.title}}",
+    "subtitle": "Revision {{metadata.revision}} · effective {{metadata.effective_date}}",
+    "body": "{{metadata.document_markdown}}",
+    "fields": [
+      { "label": "Owner",      "value": "{{metadata.owner}}" },
+      { "label": "Claimed by", "value": "{{escalation.assigned_to}}" }
+    ]
+  },
+  "x-lt-history": {
+    "row":   { "title": "{{metadata.title}} — revision {{metadata.revision}}" },
+    "limit": 25
+  }
+}
+```
+
+The reference: `examples/workflows/policy-document/` (role seeded by `examples/seed-policy-document.ts`) — a looped workflow keeps exactly one escalation live and each resolution folds into the next revision.
+
+### `"active"` — current item card only
+
+Use when there is one live item but no history view is needed — a single-request approval or a just-in-time form.
+
+### `"facet-table"` — scannable queue
+
+Use when the queue contains many concurrent rows and the role's context is best expressed as a table — a print farm, order queue, or batch-processing pond. Every pending escalation is a row; columns are defined by `x-lt-columns`.
+
+```json
+{
+  "x-lt-layout": "facet-table",
+  "x-lt-columns": [
+    { "label": "Patient",  "value": "{{metadata.patientId}}" },
+    { "label": "Heel cup", "value": "{{metadata.heelCup}}" },
+    { "label": "PDAC",     "value": "{{metadata.pdac}}" },
+    { "label": "Station",  "value": "{{metadata.station}}" },
+    { "label": "Priority", "value": "{{escalation.priority}}" },
+    { "label": "Created",  "value": "{{escalation.created_at}}" }
+  ]
+}
+```
+
+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.

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

@@ -0,0 +1,128 @@
+# Conditional Visibility
+
+## `x-lt-showIf`
+
+A field can be shown or hidden based on a value in the escalation context. Apply `x-lt-showIf` to any property:
+
+```json
+"x-lt-showIf": "domain.path"
+```
+
+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.
+
+### Domains
+
+| Domain | Resolves against |
+|--------|-----------------|
+| `metadata` | The row's metadata dict |
+| `payload` | The escalation context payload (`escalation_payload`) |
+| `envelope` | The workflow-sent input envelope |
+| `escalation` | Top-level escalation row fields (`role`, `status`, `priority`, …) |
+| `resolver` | The submitted resolver payload — **live**: reacts in real time as the user edits the form |
+
+Conditions based on `metadata`, `payload`, `envelope`, and `escalation` are static (read from the stored row). Conditions based on `resolver` are dynamic — the field appears or disappears immediately as the user edits a sibling field, without a page reload.
+
+### Item type branching
+
+A queue that receives both regular items and a special signal type. The payload carries `crew_pill` to distinguish them:
+
+```json
+{
+  "title": "Worker Station",
+  "properties": {
+    "action_taken": {
+      "type": "string",
+      "enum": ["completed", "deferred", "escalated"],
+      "description": "Outcome for this work item",
+      "x-lt-showIf": "!payload.crew_pill"
+    },
+    "notes": {
+      "type": "string",
+      "format": "textarea",
+      "x-lt-showIf": "!payload.crew_pill"
+    },
+    "shutdown_ack": {
+      "type": "boolean",
+      "title": "Acknowledge shutdown",
+      "description": "Confirm you are stopping work and clearing the station",
+      "x-lt-showIf": "payload.crew_pill"
+    }
+  }
+}
+```
+
+### Approval/rejection — live conditional required
+
+`rejection_reason` is hidden when `approved` is checked. Because the condition targets `resolver.approved`, the field appears immediately when the user unchecks the toggle — no submit needed. The `required` array marks `rejection_reason` as required — the required check is skipped for fields hidden by `x-lt-showIf`:
+
+```json
+{
+  "title": "Quality Review",
+  "x-lt-order": ["approved", "rejection_reason", "notes"],
+  "required": ["rejection_reason"],
+  "properties": {
+    "approved": {
+      "type": "boolean",
+      "description": "Approve this submission"
+    },
+    "rejection_reason": {
+      "type": "string",
+      "format": "textarea",
+      "description": "Explain why this submission is not approved",
+      "x-lt-showIf": "!resolver.approved"
+    },
+    "notes": {
+      "type": "string",
+      "format": "textarea",
+      "description": "Reviewer notes"
+    }
+  }
+}
+```
+
+In the workflow, guard the payload fields before accessing them:
+
+```typescript
+const decision = await conditionLT<{
+  approved: boolean;
+  rejection_reason?: string;
+  notes?: string;
+}>(signalId, { role: 'quality-reviewer', /* ... */ });
+
+if (!decision.approved) {
+  await sendForRework({ reason: decision.rejection_reason, notes: decision.notes });
+} else {
+  await advanceOrder();
+}
+```
+
+### Submission behavior
+
+Hidden fields are not rendered but their values (if any) remain in form state and are submitted only if they were filled before being hidden. Required validation is not applied to fields hidden at submission time.
+
+---
+
+## `x-lt-hide-if-empty`
+
+A field with `"x-lt-hide-if-empty": true` is suppressed entirely when its value is null, an empty string, `false`, or `0`. This is primarily useful for `readOnly` fact fields that are only present on some escalations:
+
+```json
+{
+  "properties": {
+    "heel_raise": {
+      "type": "string",
+      "readOnly": true,
+      "x-lt-hide-if-empty": true,
+      "description": "Heel raise specification"
+    },
+    "notes": {
+      "type": "string",
+      "readOnly": true,
+      "x-lt-hide-if-empty": true,
+      "description": "Additional processing notes"
+    }
+  }
+}
+```
+
+`x-lt-hide-if-empty` is evaluated against the field's current value in form state. It is distinct from `x-lt-showIf`, which evaluates against a path in the escalation context.