@hotmeshio/long-tail 0.5.12 → 0.6.2

package/docs/api/sdk/escalations.md

@@ -2,6 +2,15 @@
 
 Manage human-in-the-loop escalations -- list, claim, resolve, and bulk-operate on workflow escalations.
 
+## Work-Surface Scope
+
+Escalation methods enforce the caller's role work-surface scope server-side; the SDK method signatures are unchanged. For a `member`:
+
+- `read_scope` governs **search** — `list`, `listAvailable`, `findByMetadata`, `getStats`, and a single `get` return only the escalations the member is allowed to see. `read_scope=self` limits this to items assigned to the member; `read_scope=all` exposes the whole role queue.
+- `write_scope` governs **claim / ack (resolve) / delete (cancel)** — a member with `write_scope=self` may only `claim`, `resolve`, and `cancel` items already assigned to them. `release`, `escalate`, and `create` (standalone) are queue-management verbs and require `write_scope=all`.
+
+`admin` and `superadmin` ignore scope and act on the whole queue. Scope is set when a role is assigned — see [`lt.users.addRole`](users.md) and [Roles API — Work-Surface Scope](../http/roles.md).
+
 ## create
 
 Create an escalation. The caller must hold the target role or be a superadmin.
@@ -52,6 +61,18 @@ const result = await lt.escalations.list({
   role: 'reviewer',
   limit: 25,
 });
+
+// Faceted query — a "facet" is a key/value INSIDE the row's metadata JSONB. The
+// filter AND the count run in SQL, role-scoped; nothing is filtered client-side.
+const faceted = await lt.escalations.list({
+  status: 'pending',
+  facets: { flags: 'too_short' },                  // metadata @> { flags: 'too_short' }
+  range: [{ facet: 'confidence', op: '<=', value: 0.7 }],
+  block: [{ outcome: 'success' }],                 // exclude completed
+  exists: ['needsReview'],
+  orderBy: [{ field: 'metadata.confidence', numeric: true, direction: 'asc' }],
+  limit: 50,
+});
 ```
 
 **Parameters:**
@@ -60,14 +81,25 @@ const result = await lt.escalations.list({
 |-------|------|----------|-------------|
 | `status` | `string` | No | Filter by `pending`, `resolved`, or `cancelled` |
 | `role` | `string` | No | Filter by assigned role |
+| `roles` | `string[]` | No | Restrict to these roles (`role = ANY`) — narrows within the caller's scope, never widens past it |
 | `type` | `string` | No | Filter by workflow type |
 | `subtype` | `string` | No | Filter by subtype |
 | `assigned_to` | `string` | No | Filter by assigned user ID |
 | `priority` | `number` | No | Filter by priority (1--4) |
+| `facets` | `Record<string, any>` | No | Required metadata facets — `metadata @> facets` (AND, GIN-served). `{ k: v }` means `metadata.k == v` for a top-level scalar; for nested/arrays it is JSONB **containment** |
+| `block` | `Record<string, any>[]` | No | Exclude rows whose metadata contains ANY of these facet sets — `NOT (metadata @> ANY(block))` |
+| `range` | `{ facet, op, value }[]` | No | Numeric range over a metadata facet, e.g. `{ facet: 'confidence', op: '<=', value: 0.7 }` |
+| `exists` | `string[]` | No | Metadata keys that must be present — `metadata ? key` |
+| `available` | `boolean` | No | `true` = unclaimed/expired only; `false` = held now |
 | `limit` | `number` | No | Max results (default: 50) |
 | `offset` | `number` | No | Pagination offset |
 | `sort_by` | `string` | No | Column to sort by (e.g. `created_at`, `priority`) |
 | `order` | `string` | No | `asc` or `desc` |
+| `orderBy` | `{ field, direction?, numeric? }[]` | No | Multi-key sort over columns or a metadata path written `metadata.<key>` (set `numeric` for numeric sort) |
+
+When any faceted element (`facets`/`block`/`range`/`exists`/`roles`/`available`/`orderBy`) is
+present the request runs through the scoped faceted query; otherwise the simple list path is used.
+See [Faceted Routing — the human / operations query](../../faceted-routing.md#the-human--operations-query).
 
 **Returns:** `LTApiResult<{ escalations, total }>`
 
@@ -99,6 +131,9 @@ const result = await lt.escalations.listAvailable({
 | `sort_by` | `string` | No | Column to sort by |
 | `order` | `string` | No | `asc` or `desc` |
 
+Also accepts the same faceted parameters as [`list`](#list) (`facets`, `block`, `range`,
+`exists`, `roles`, `orderBy`), pinned to the available pool.
+
 **Returns:** `LTApiResult<{ escalations, total }>`
 
 **Auth:** Required
@@ -259,6 +294,7 @@ Supports two resolution paths: signal-routed (sends payload to a paused workflow
 const result = await lt.escalations.resolve({
   id: 'esc_123',
   resolverPayload: { approved: true, comment: 'Looks good' },
+  metadata: { outcome: 'approved', reviewedBy: 'alice', durationMs: 1_240 },
 });
 ```
 
@@ -267,7 +303,8 @@ const result = await lt.escalations.resolve({
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `id` | `string` | Yes | Escalation UUID |
-| `resolverPayload` | `Record<string, any>` | Yes | Human decision data |
+| `resolverPayload` | `Record<string, any>` | Yes | Human decision data — resumes the paused workflow; not indexed |
+| `metadata` | `Record<string, any>` | No | Outcome facets merged into the row's GIN-indexed metadata. Records *what happened* (disposition, timing) next to *what was asked*; `@>`-queryable. See [Recording the outcome](#recording-the-outcome-on-resolve) |
 
 **Returns:** `LTApiResult<{ signaled, escalationId, workflowId }>` (signal path) or `LTApiResult<{ started, escalationId, workflowId }>` (re-run path) -- returns 404 if not found, 409 if not pending.
 
@@ -275,6 +312,35 @@ const result = await lt.escalations.resolve({
 
 ---
 
+## Recording the outcome on resolve
+
+Every resolve path — `resolve`, `resolveBySignalKey`, the HTTP routes, the MCP tools, and the
+in-process `EscalationService.resolveEscalation` — takes an optional `metadata` patch. It is
+merged, not replaced, into the row's GIN-indexed metadata, recording the **outcome** on the
+same row that carried the **intent**.
+
+```typescript
+await lt.escalations.resolve({
+  id: 'esc_123',
+  resolverPayload: { approved: true },           // resumes the workflow; not indexed
+  metadata: { outcome: 'approved', durationMs: 1_240 }, // recorded on the row; @>-queryable
+});
+```
+
+The patch is distinct from `resolverPayload`: the payload is delivered to the waiting workflow
+as `condition()`'s return value; the patch is the durable, queryable record. Intent and
+outcome live on one row — no side table:
+
+```typescript
+await lt.escalations.findByMetadata({ key: 'outcome', value: 'approved' });
+// every resolved row that was approved — with its disposition and duration
+```
+
+The in-process library takes the same patch as a third argument:
+`resolveEscalation(id, payload, metadata)` and `resolveEscalationBySignalKey(signalKey, payload, metadata)`.
+
+---
+
 ## conditionLT (workflow helper)
 
 Wait for a signal and automatically resolve the associated escalation. This is the counterpart to `executeLT` — where `executeLT` wraps `startChild` + `condition`, `conditionLT` wraps `condition` + escalation resolution.
@@ -283,6 +349,16 @@ Wait for a signal and automatically resolve the associated escalation. This is t
 conditionLT<T>(signalId: string, escalation?: ConditionQueueConfig): Promise<T | false | null>
 ```
 
+### Two ways to pause on an escalation
+
+There are two ways to make a workflow pause as a claimable escalation, and they are not equivalent in cost:
+
+- **Native `condition(signalId, escalationConfig)` — the efficient primitive.** HotMesh's `condition` takes an optional escalation config as its second argument. The row is written inside the workflow's Leg1 checkpoint, with `signal_key = signalId`. Resolving it (`resolve` / `resolveBySignalKey`) marks the row resolved **and** delivers the signal in one guarded transaction, resuming the job in place. No create activity, no enrich step, and **no proxy-activity round-trip on the resume** — the resolve is the whole transaction. This is the path to prefer.
+
+- **`conditionLT(signalId, config?)` — long-tail sugar.** With a config it delegates to the native efficient `condition` above (same atomic behavior — use it freely). Without a config it also supports the older **two-step** pattern: an escalation created separately, where the resume injects `$escalation_id` and `conditionLT` resolves it through a durable `proxyActivity` (`ltResolveEscalation`). That extra activity round-trip is the cost of the two-step form; the efficient form (and native `condition`) avoid it.
+
+Reach for native `condition(signalId, config)` when you want the leanest path; reach for `conditionLT` for the ergonomic wrapper or to support the legacy two-step flow. Both resume the same row, and both accept the resolve-time `metadata` patch (the efficient path merges it in the single guarded UPDATE; the two-step path forwards it through `ltResolveEscalation` into that same atomic resolve).
+
 ### Atomic form (recommended)
 
 Pass an escalation config as the second argument. The escalation row is written inside the workflow's Leg1 checkpoint — one commit, crash-safe: no separate `ltCreateEscalation` activity, no enrich step. `signal_key` is set to `signalId`, so the dashboard resolve endpoint (resolve-by-id → Path 0) and `POST /escalations/resolve-by-signal-key` resume *this* job in place, and `system.escalation.{id}.created` fires automatically.
@@ -662,7 +738,7 @@ const result = await lt.escalations.claimByMetadata({
 | `metadata` | `object` | No | Merge into escalation metadata (single atomic SQL call with the claim) |
 | `provisionIfAbsent` | `object` | No | JIT-provision the assignee if they don't exist or lack the required role (superadmin only) |
 
-`provisionIfAbsent` accepts `{ displayName?, email?, roles?: [{ role, type? }] }`. Only callers with global escalation access can use this flag. The happy path (user exists, has role) adds zero extra queries.
+`provisionIfAbsent` accepts `{ displayName?, email?, roles?: [{ role, type?, read_scope?, write_scope? }] }`. Each role entry forwards the optional work-surface scope fields `read_scope` (`self` or `all`, default `all`) and `write_scope` (`none`, `self`, or `all`, default `all`), subject to the **write ⊆ read** constraint; scope is ignored for `admin`/`superadmin`. To JIT-provision a one-time user who sees and acts on exactly the item being claimed, provision them `read_scope: 'self'` + `write_scope: 'self'`. Only callers with global escalation access can use this flag. The happy path (user exists, has role) adds zero extra queries.
 
 **Returns:** `LTApiResult<{ escalation, isExtension }>` -- 404 if no match, 409 if already claimed.
 
@@ -707,3 +783,80 @@ const result = await lt.escalations.resolveByMetadata({
 **Returns:** `LTApiResult<{ escalation }>` for non-signal, `LTApiResult<{ signaled, escalationId, workflowId }>` for signal-backed. 404 if no match.
 
 **Auth:** Required
+
+## resolveByIds
+
+Resolve a set of escalations by id in one guarded statement (the set-based sibling of `resolve`). For bookkeeping rows woken collectively — it does not deliver a per-row signal. RBAC: a scoped caller may only resolve rows whose role they hold.
+
+```typescript
+const result = await lt.escalations.resolveByIds({
+  ids: ['esc_1', 'esc_2', 'esc_3'],
+  resolverPayload: { printerId: 'p-7' },
+  metadata: { outcome: 'settled' },
+});
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Escalation ids to resolve as one set |
+| `resolverPayload` | `Record<string, any>` | Yes | Payload applied to every row |
+| `metadata` | `Record<string, any>` | No | Outcome patch merged into each row |
+
+**Returns:** `LTApiResult<{ resolved: number; escalationIds: string[] }>` — only still-`pending` rows are resolved.
+
+## resolveBySignalKey
+
+Resolve an efficient (atomic) escalation directly by its `signal_key` and resume the waiting workflow in place. For callers that know the deterministic signal id and want to skip the id lookup. RBAC-scoped to the escalation's role.
+
+```typescript
+const result = await lt.escalations.resolveBySignalKey({
+  signalKey: 'signal-scan-ar-order-42',
+  resolverPayload: { approved: true },
+});
+```
+
+**Returns:** `LTApiResult<{ signaled: true; escalationId; workflowId }>`.
+
+## searchByFacets
+
+Item-level faceted search over a single pond `role`, scoped to the caller's role. The faceted-routing read primitive.
+
+```typescript
+const result = await lt.escalations.searchByFacets({
+  role: 'printer-pool-diabetic',
+  status: 'pending',
+  available: true,
+  facets: { state: 'ready' },
+  limit: 50,
+});
+```
+
+**Returns:** `LTApiResult<{ escalations; total }>`.
+
+## claimGroups
+
+Batch-claim complete origin groups (e.g. all units of an order) in priority order over a pond, assigned to the caller. RBAC-scoped to the pond role.
+
+```typescript
+const result = await lt.escalations.claimGroups({
+  query: { role: 'print-farm-diabetic', available: true, facets: { filament: 'pla', size_class: 'standard' } },
+  limit: 4,
+  durationMinutes: 30,
+  sizeFacet: 'order_size',
+});
+```
+
+**Returns:** `LTApiResult<{ groups }>`.
+
+## claimByFacets
+
+Batch-claim individual rows matching a facet query (`FOR UPDATE SKIP LOCKED`), assigned to the caller. With `allOrNone`, commits only when the full `limit` is acquired. RBAC-scoped to the pond role.
+
+```typescript
+const result = await lt.escalations.claimByFacets({
+  query: { role: 'printer-pool-diabetic', facets: { state: 'ready', filament: 'pla' } },
+  limit: 3,
+});
+```
+
+**Returns:** `LTApiResult<{ claimed }>`.

package/docs/api/sdk/roles.md

@@ -2,6 +2,17 @@
 
 Manage roles and escalation chain routing between roles.
 
+## Work-Surface Scope
+
+A role is a task queue worked by its members. Each `member` assignment carries two work-surface scope axes that set how much of the queue that member touches:
+
+- `read_scope` (`self` or `all`, default `all`) governs **search** — which escalations the member sees.
+- `write_scope` (`none`, `self`, or `all`, default `all`) governs **claim / ack (resolve) / delete (cancel)** — which escalations the member may act on.
+
+`self` means items assigned to the member; `all` means the whole role queue. The constraint is **write ⊆ read** — `write_scope=all` requires `read_scope=all`. `admin` and `superadmin` ignore scope and always act on the whole queue. The default `all`/`all` is the full-queue worker.
+
+Scope is set when a role is assigned to a user, via [`lt.users.addRole`](users.md) and [`lt.users.create`](users.md). See [Roles API — Work-Surface Scope](../http/roles.md) for the five member profiles.
+
 ## list
 
 List all distinct role names in the system.

package/docs/api/sdk/users.md

@@ -70,9 +70,19 @@ const result = await lt.users.create({
 | `external_id` | `string` | Yes | External system identifier |
 | `email` | `string` | No | Email address |
 | `display_name` | `string` | No | Display name |
-| `roles` | `{ role: string; type: string }[]` | No | Initial role assignments (type: `superadmin`, `admin`, or `member`) |
+| `roles` | `{ role: string; type: string; read_scope?: string; write_scope?: string }[]` | No | Initial role assignments (type: `superadmin`, `admin`, or `member`) |
 | `metadata` | `Record<string, any>` | No | Arbitrary key-value metadata |
 
+Each role entry forwards the optional work-surface scope fields `read_scope` (`self` or `all`, default `all`) and `write_scope` (`none`, `self`, or `all`, default `all`) to the API. Scope refines a `member` grant and is ignored for `admin`/`superadmin`. The constraint is **write ⊆ read** — `write_scope=all` requires `read_scope=all`. The default `all`/`all` is the full-queue worker. See [Roles API — Work-Surface Scope](../http/roles.md) for the five member profiles.
+
+```typescript
+// A one-time user who sees and acts only on their own pre-assigned item
+const result = await lt.users.create({
+  external_id: 'new-user',
+  roles: [{ role: 'customer-triage', type: 'member', read_scope: 'self', write_scope: 'self' }],
+});
+```
+
 **Returns:** `LTApiResult<User>` (status 201) -- returns 409 if `external_id` already exists.
 
 **Auth:** Not required
@@ -166,6 +176,21 @@ const result = await lt.users.addRole({
 | `id` | `string` | Yes | User UUID |
 | `role` | `string` | Yes | Role name to assign |
 | `type` | `string` | Yes | Role type (`superadmin`, `admin`, or `member`) |
+| `read_scope` | `string` | No | `self` or `all` (default `all`). Search breadth for a `member`; ignored for admin/superadmin |
+| `write_scope` | `string` | No | `none`, `self`, or `all` (default `all`). Claim/ack/delete breadth for a `member` |
+
+`read_scope` and `write_scope` are the work-surface scope axes for a `member` grant: `read_scope` governs which escalations the member sees in search; `write_scope` governs which they may claim, ack (resolve), or delete (cancel). `self` means items assigned to the member; `all` means the whole role queue. The constraint is **write ⊆ read** — `write_scope=all` requires `read_scope=all`. Both default to `all` (full-queue worker), and both are ignored for `admin`/`superadmin`, which always act on the whole queue. The returned role object includes `read_scope` and `write_scope`. See [Roles API — Work-Surface Scope](../http/roles.md) for the five member profiles.
+
+```typescript
+// See the whole queue, act only on own items (e.g. a chat-style room)
+const result = await lt.users.addRole({
+  id: 'user_123',
+  role: 'reviewer',
+  type: 'member',
+  read_scope: 'all',
+  write_scope: 'self',
+});
+```
 
 **Returns:** `LTApiResult<UserRole>` (status 201)
 

package/docs/auth.md

@@ -239,7 +239,7 @@ When SSO is configured and a request arrives without a Bearer token, `requireAut
 
 Roles are resolved once during the token exchange (not per-request) and baked into the JWT — the same pattern as the built-in login. When the host system changes a user's roles, the new roles take effect on the next token refresh.
 
-If `roleMap` is provided, only mapped roles are assigned. If omitted, host role names are passed through directly as LT role names. Roles named `superadmin` or `admin` are assigned the corresponding role type; all others default to `member`.
+If `roleMap` is provided, only mapped roles are assigned. If omitted, host role names are passed through directly as LT role names. Roles named `superadmin` or `admin` are assigned the corresponding role type; all others default to `member`. Provisioned `member` grants take the default work-surface scope of `read_all`/`write_all` — the full-queue worker. Narrower scopes (for one-time or read-only users) are set through the [Roles API](api/http/roles.md#work-surface-scope) or the dashboard Scope picker.
 
 ### Standalone Deployments
 

package/docs/dashboard.md

@@ -187,18 +187,19 @@ Lists all durable workflow runs across the system.
 
 User Accounts and Service Accounts live on the same page, separated by a tab toggle.
 
-- **User Accounts** — human operators. Create users, assign display names, and grant roles. Roles determine which escalations a user can see and claim, and which workflows they can invoke from the dashboard.
+- **User Accounts** — human operators. Create users, assign display names, and grant roles. Roles determine which escalations a user can see and claim, and which workflows they can invoke from the dashboard. A `member` grant carries a work-surface scope (read/write breadth) chosen from the Scope picker; see [Roles](#roles).
 - **Service Accounts** — programmatic callers (bots, CI pipelines, external systems). Each service account has an API key for authentication. Assign roles to control access just like human users. Service accounts with the `reviewer` role can claim and resolve escalations programmatically.
 - **Role assignment** — both account types participate in the same role system. Click any account to edit roles, change display name, or manage credentials.
 
 **API:** `GET /api/users` lists accounts. `POST /api/users` creates. `PUT /api/users/:id/roles` assigns roles.
 
-### Roles and Permissions
+### Roles
 
 Define roles and configure escalation chains that control how work flows between teams.
 
 - **Role list** — all roles in the system with their type (admin, operator, custom). Click to view assigned users.
 - **Create Role** — add a new role. Roles referenced in workflow configs are auto-created, but you can also create them here for organizational clarity.
+- **Scope picker** — when granting a role at `member` type, a Scope picker offers the five named work-surface profiles: full worker (`all`/`all`, default), see-all-act-own (`all`/`self`), own-items-only (`self`/`self`), read-only auditor (`all`/`none`), and read-only own (`self`/`none`). `admin` and `superadmin` grants show no Scope picker — they always work the whole queue. The picker enforces **write ⊆ read**, so a write breadth wider than the read breadth cannot be selected.
 - **Escalation chains** — define source → target role mappings. When a reviewer escalates, the chain determines which roles receive the escalation next. Chains are directional (reviewer → engineer → admin) and support multiple targets per source.
 
 **API:** `GET /api/roles` lists roles. `POST /api/roles` creates. `GET /api/roles/escalation-chains` lists chains. `POST /api/roles/escalation-chains` adds a chain.
@@ -245,8 +246,8 @@ The central queue for all escalation activity across every workflow.
 
 - **Filter bar** — filter by status (pending/claimed/resolved), role, workflow type, priority, and time window.
 - **Columns:** Escalation ID, workflow type, role, status, priority, created time, and claimed-by user.
-- **Claim** — click the claim action to lock an escalation to your user. Only users with matching roles see pending escalations.
-- **Resolve** — after claiming, submit a resolver payload (pre-filled from the workflow's `resolver_schema` if configured). Resolution triggers a workflow re-run with the resolver data injected.
+- **Claim** — click the claim action to lock an escalation to your user. Only users with matching roles see pending escalations. The queue list and aggregate stats reflect `read_all` memberships — a member scoped to `read_self` lands directly on their own assigned item in user mode rather than browsing the full queue.
+- **Resolve** — after claiming, submit a resolver payload (pre-filled from the workflow's `resolver_schema` if configured). Resolution triggers a workflow re-run with the resolver data injected. A `member` whose `write_scope` is `self` can resolve only items already assigned to them; `write_scope=none` is read-only.
 - **Escalate** — forward a claimed escalation to a higher-tier role via the escalation chain.
 
 **API:** `GET /api/escalations` lists with filters. `POST /api/escalations/:id/claim` claims. `POST /api/escalations/:id/resolve` resolves.

package/docs/data.md

@@ -74,6 +74,11 @@ backward-compatible **view** over it — `SELECT *` plus a computed `available`
 column — so existing read queries and the public API are unchanged. Indexes are
 managed by the SDK on `hmsh_escalations` (see below).
 
+Role read/write scope does **not** add columns here. An escalation carries a `role`
+and an optional `assigned_to`; work-surface scope lives on the membership table
+(`lt_user_roles`) and is applied at read time. `condition()` / `conditionLT()` and
+the escalation engine are unaffected.
+
 The columns below are the `hmsh_escalations` table. The public API record
 (`LTEscalationRecord`) is mapped from these: the JSONB `envelope` /
 `escalation_payload` / `resolver_payload` are serialized to JSON **strings**, and
@@ -179,12 +184,14 @@ Maps users to roles. Each user can hold multiple roles with different permission
 |--------|------|---------|-------------|
 | `user_id` | `UUID NOT NULL` | — | FK to `lt_users(id)`, CASCADE on delete |
 | `role` | `TEXT NOT NULL` | — | Role name (e.g., `reviewer`, `senior-reviewer`) |
-| `type` | `TEXT NOT NULL` | `'member'` | `superadmin`, `admin`, or `member` |
+| `type` | `TEXT NOT NULL` | `'member'` | `superadmin`, `admin`, or `member` — the management tier |
+| `read_scope` | `TEXT NOT NULL` | `'all'` | `self` or `all` — search breadth for a `member`: which escalations in the role queue the member sees. `self` = items where `assigned_to = user`; `all` = the whole queue. Ignored for `admin`/`superadmin`, which always see the whole queue. |
+| `write_scope` | `TEXT NOT NULL` | `'all'` | `none`, `self`, or `all` — claim/ack/delete breadth for a `member`. `none` = read-only; `self` = items assigned to the member; `all` = the whole queue. Ignored for `admin`/`superadmin`. |
 | `created_at` | `TIMESTAMPTZ NOT NULL` | `NOW()` | When the role was assigned |
 
 Primary key: `(user_id, role)` — a user can hold each role at most once.
 
-Type is enforced by a CHECK constraint: `type IN ('superadmin', 'admin', 'member')`.
+Type is enforced by a CHECK constraint: `type IN ('superadmin', 'admin', 'member')`. Scope is enforced by CHECK constraints: `read_scope IN ('self', 'all')`, `write_scope IN ('none', 'self', 'all')`, and **write ⊆ read** — `write_scope = 'all'` requires `read_scope = 'all'` (a member cannot act on what it cannot see). Both scopes default to `all`, the full-queue worker.
 
 ### lt_bot_api_keys
 

package/docs/faceted-routing.md

@@ -0,0 +1,221 @@
+# Faceted Routing
+
+The escalation queue is more than a HITL inbox — it is a durable, queryable pool of work
+that any number of consumers can search and atomically claim by its **facets**. Faceted
+routing is the platform surface for that: a composable query language over the queue and a
+set of atomic claim primitives. The platform supplies the surface; the *policy* — what a
+facet means, how capability and priority map onto it, the matching loop — is the consuming
+app's. The [print-routing example](../examples/workflows/print-routing/README.md) is a full
+worked policy built entirely on these primitives.
+
+## Contents
+
+- [The model](#the-model)
+- [The query — `FacetQuery`](#the-query--facetquery)
+- [Reads](#reads)
+- [Atomic claims](#atomic-claims)
+- [The dispatcher pattern](#the-dispatcher-pattern)
+- [Recording the outcome on resolve](#recording-the-outcome-on-resolve)
+- [Safety](#safety)
+
+## The model
+
+Every escalation row carries a `role` (the hard isolation boundary) and a `metadata` JSONB
+object (the soft facets a late-binding consumer queries, sorts, and claims by). Routing
+work is a funnel over those columns:
+
+- **Capability** — the hard wall — is the `role`. A consumer bound to one role can never
+  see another role's work. Soft capability is `metadata @>` containment.
+- **Preference / priority** — ordering — is `orderBy` over top-level columns and facets.
+- **Capacity** — how much to take — is the page `limit` of a claim.
+
+An **order** (or any multi-unit job) is a set of rows sharing an `origin_id`; its unit
+count lives in a metadata facet so a group can be claimed all-or-nothing only when complete.
+
+## The query — `FacetQuery`
+
+```typescript
+interface FacetQuery {
+  role?: string;                    // hard isolation (exact)
+  roles?: string[];                 // role = ANY(...)
+  facets?: Record<string, any>;     // metadata @> facets  — required (AND), GIN-served
+  block?: Record<string, any>[];    // NOT (metadata @> ANY(block)) — exclusion list
+  range?: { facet: string; op: '<' | '<=' | '>' | '>=' | '='; value: number }[];
+  exists?: string[];                // metadata ? key — facet must be present
+  status?: string;                  // e.g. 'pending'
+  available?: boolean;              // true = unclaimed/expired only; false = held now
+  orderBy?: { field: string; direction?: 'asc' | 'desc'; numeric?: boolean }[];
+  limit?: number;
+  offset?: number;
+}
+```
+
+`orderBy.field` is either a whitelisted top-level column (`priority`, `created_at`,
+`updated_at`, `status`, `role`) or a metadata path written as `metadata.<key>` (extracted as
+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.
+
+```typescript
+// Pending, available diabetic-certified work needing PLA, soonest-deadline first.
+const query: FacetQuery = {
+  role: 'print-farm-diabetic',
+  status: 'pending',
+  available: true,
+  facets: { filament: 'pla' },
+  orderBy: [{ field: 'metadata.mustCompleteBy', numeric: true, direction: 'asc' }],
+};
+```
+
+## Reads
+
+```typescript
+import { searchByFacets, searchGroups, countByFacets } from '@hotmeshio/long-tail';
+
+// Item-level: filter/sort over columns and metadata facets.
+const { escalations, total } = await searchByFacets(query);
+
+// Order-level: each row is an origin group with its unit count, availability and
+// completeness — what a batched dispatcher reads to page by capacity.
+const groups = await searchGroups(query, { sizeFacet: 'orderSize', limit: 10 });
+
+// Aggregate: capacity / in-flight soft-limit checks.
+const inFlight = await countByFacets({ role: 'print-farm-diabetic', available: false });
+```
+
+## Atomic claims
+
+Two claim primitives, both `FOR UPDATE SKIP LOCKED` so many consumers run without
+contention. Each takes the `FacetQuery`, a `consumer` id, and options.
+
+```typescript
+import { claimGroups, claimByFacets } from '@hotmeshio/long-tail';
+
+// Claim whole orders (origin groups), all-or-nothing, in rank order. The page `limit`
+// is how many consumers/printers are free, so a dependent grabs exactly what it can
+// distribute. A group is only eligible when complete (member count = declared size).
+const orders = await claimGroups(query, 'broker-1', { limit: 4, sizeFacet: 'orderSize' });
+
+// Claim individual rows by facet — the single-row sibling. Locks up to `limit` available
+// rows in rank order. With { allOrNone: true } the claim commits only when the full limit
+// is acquired, otherwise it rolls back and returns [] — the all-or-none lock a dispatcher
+// wants over a counted set it anticipated.
+const printers = await claimByFacets(
+  { role: 'printer-pool-diabetic', facets: { state: 'ready' } },
+  'broker-1',
+  { limit: 4 },
+);
+```
+
+A claim sets `assigned_to` + `assigned_until` (default 30 minutes). Availability is a
+query, not a flag: a row is held iff `assigned_to` is set and `assigned_until > NOW()`.
+Resolve, release, or let the claim expire to return it to the pool.
+
+## The dispatcher pattern
+
+The primitives compose into a market: pull a *page* of complete orders sized to how many
+consumers are free, then distribute one per consumer. Reads go through the
+`public.lt_escalations` view (it adds the computed `available` flag); atomic claims run on
+the shared `public.hmsh_escalations` table — the same raw-SQL-on-the-shared-table pattern as
+the rest of the escalation service. Metadata facets use the GIN index (`@>`).
+
+```typescript
+// 1. Anticipate supply.
+const free = await searchByFacets({ role: 'printer-pool', available: true, facets: { state: 'ready' } });
+// 2. Claim that much demand by priority.
+const orders = await claimGroups(demandQuery, consumer, { limit: free.escalations.length });
+// 3. Lock the printers for the claimed orders, all-or-none.
+const printers = await claimByFacets(supplyQuery, consumer, { limit: orders.length, allOrNone: true });
+// 4. Pair, do the work, resolve both.
+```
+
+See the [print-routing example](../examples/workflows/print-routing/README.md) for the full
+two-sided market, carry-forward under contention, and the inspection/convergence loop.
+
+## Recording the outcome on resolve
+
+A row is created carrying **intent** — the facets that route and claim it. Resolving it can
+record the **outcome** onto the same row: pass a `metadata` patch and it is merged (not
+replaced) into the GIN-indexed metadata in the same atomic UPDATE, on the winning resolve
+only. "What actually happened" becomes `@>`-queryable next to "what was asked".
+
+```typescript
+import { resolveEscalation } from '@hotmeshio/long-tail';
+
+// The work is done; resolve the row AND stamp the outcome onto it — one atomic call.
+await resolveEscalation(rowId, { result: 'success' }, {
+  outcome: 'success',
+  unitsPrinted: 6,
+});
+// Duration needs no facet: the row's own created_at → resolved_at is the elapsed time.
+```
+
+The third argument is distinct from the second: `resolverPayload` (arg 2) is delivered to a
+waiting workflow as `condition()`'s return value and is **not** indexed; the `metadata` patch
+(arg 3) is the durable, queryable record on the row. With both, the row alone answers what was
+asked, what happened, and how long it took:
+
+```typescript
+searchByFacets({ role: 'printer-pool-diabetic', facets: { state: 'printing', outcome: 'success' } });
+// → every completed job: which consumer, which origin, how long — no side table to reconcile
+```
+
+The print farm leans on this: a printer resolves its in-flight `printing` row with the run's
+result and units in one atomic call, so the supply pond is also the production log — and the
+row's `created_at` → `resolved_at` is the print duration, no stored field required.
+
+## The human / operations query
+
+The same query language is also the operations team's read surface. Where the dispatcher
+sections above target a **single pond** for a workflow consumer, a **person** — a superadmin, or
+a member of several roles — queries "what work needs doing / was done" across **their** roles by
+the same facets, through the scoped list API.
+
+```typescript
+import { createClient } from '@hotmeshio/long-tail/sdk';
+const lt = createClient({ auth }); // auth carries the caller's userId
+
+// Faceted, role-scoped, paginated — the filter AND the count run in SQL.
+const res = await lt.escalations.list({
+  status: 'pending',
+  facets: { flags: 'too_short' },                 // metadata @> (GIN-served)
+  range: [{ facet: 'confidence', op: '<=', value: 0.7 }],
+  exists: ['needsReview'],
+  block: [{ outcome: 'success' }],                // exclude completed
+  orderBy: [{ field: 'metadata.confidence', numeric: true, direction: 'asc' }],
+  limit: 50, offset: 0,
+});
+// res.data → { escalations, total }
+```
+
+`list` and `listAvailable` accept the FacetQuery elements (`facets`, `block`, `range`, `exists`,
+`roles`, `available`, `orderBy`) on top of the plain filters. When any are present the request
+runs through the scoped faceted query; otherwise the simple list path is used.
+
+**Role scope is enforced in SQL, not in the controller.** The result is the read-scope predicate
+ANDed with the facets:
+
+- **superadmin / admin-of-admin** (global) — every role's queue, no role filter.
+- **`read_all` on a role** — the whole pond for that role.
+- **`read_self` on a role** — only items assigned to the caller (`assigned_to = me`).
+
+A caller may **narrow** within their scope (pass `role`/`roles`) but can never **widen** past it —
+a `role` they don't hold simply matches nothing. The page total is computed by the same WHERE, so
+pagination stays correct; the controller never filters a fetched page client-side.
+
+Over HTTP the faceted elements are JSON-encoded query params, so the whole query rides on a GET
+URL and the dashboard's copy-URL / copy-curl reproduces the exact request:
+
+```
+GET /api/escalations?status=pending&facets=%7B%22flags%22%3A%22too_short%22%7D&range=%5B%7B%22facet%22%3A%22confidence%22%2C%22op%22%3A%22%3C%3D%22%2C%22value%22%3A0.7%7D%5D
+```
+
+## Safety
+
+- **Parameterized** — every value is a bound parameter; only audited column names, metadata
+  keys (strict `^[a-zA-Z0-9_]+$`), and a fixed operator set are interpolated.
+- **Atomic** — claims are single transactions with `FOR UPDATE SKIP LOCKED`; group claims
+  re-check completeness *inside* the lock, so concurrent dispatchers never split a group or
+  double-claim a row.
+- **Durable consumers** — because the surface is a query, a consumer that holds a claim it
+  cannot yet place can carry it across `continueAsNew` and converge later rather than
+  releasing — the durable workflow is the coordinator, not a distributed transaction.

package/docs/hitl-guide.md

@@ -158,6 +158,29 @@ export async function reviewWorkflow(envelope: LTEnvelope) {
 
 ---
 
+## Recording the Outcome on Resolution
+
+An escalation row is created carrying **intent** — what was asked, who it routed to. Resolving it can stamp 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`, `/resolve-by-signal-key`) |
+| SDK facade | `lt.escalations.resolve({ id, resolverPayload, metadata })` |
+| MCP | `metadata` arg on `claim_and_resolve` / `resolve_escalation` |
+| In-process library | `resolveEscalation(id, payload, metadata)` / `resolveEscalationBySignalKey(signalKey, payload, metadata)` |
+
+```typescript
+await lt.escalations.resolve({
+  id,
+  resolverPayload: { approved: true },               // resumes the workflow; not indexed
+  metadata: { outcome: 'approved', reviewedBy: 'alice', durationMs: elapsed },
+});
+```
+
+The patch is distinct from the resolver payload: the payload resumes the paused workflow and is not indexed; the metadata patch is the durable, queryable record on the row. Use it for the 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.
+
+---
+
 ## JSON Schema Form Authoring
 
 The dashboard renders forms automatically from JSON Schema. No frontend code needed.
@@ -456,6 +479,33 @@ await ltCreateEscalation({
 });
 ```
 
+### Work-Surface Scope
+
+A `member` of a role carries a work-surface scope that narrows what they see and act on within that queue: `read_scope` (`self` | `all`) governs which escalations they see, and `write_scope` (`none` | `self` | `all`) governs which they 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. See the [Roles API](api/http/roles.md#work-surface-scope) for the five member profiles and the assignment contract.
+
+Scope is a property of the **membership** (`lt_user_roles`), not of the escalation. The escalation engine is unchanged: `condition()` / `conditionLT()`, `ltCreateEscalation`, and the interceptor write escalation rows (`hmsh_escalations`) exactly as before — an escalation carries a `role` and an optional `assigned_to`, with no scope column. Scope is resolved at read time, when a *user* lists or acts on the queue. Escalating to a role that does not exist yet still registers the role name only — roles are typeless; `type` and scope are set per user when the role is granted. The one place scope affects creation is the standalone `POST /api/escalations` HTTP endpoint, which requires `write_scope=all`; workflow-emitted escalations (`conditionLT`, interceptor returns, `ltCreateEscalation`) do not pass through that check.
+
+### One-Time and Pre-Assigned Users
+
+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 (a pre-claim) 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 and no direct table access. An update or follow-up is simply another workflow firing another escalation to that same person.
+
+```typescript
+// Pre-assign the escalation to a specific person and route a one-time form to them
+await ltCreateEscalation({
+  role: 'customer-triage',
+  assigned_to: userId,        // pre-claim — durable, keyed off the user, not the soft-lock TTL
+  description: 'Confirm your shipping address',
+  metadata: {
+    form_schema: {
+      title: 'Confirm Address',
+      properties: { address: { type: 'string' }, confirmed: { type: 'boolean' } },
+      required: ['confirmed'],
+    },
+  },
+});
+// The person is provisioned as a member of `customer-triage` with read_scope=self, write_scope=self.
+```
+
 ### Escalation Chains
 
 Users can escalate to other roles via the "Escalate" tab: