@hotmeshio/long-tail 0.5.12 → 0.6.0

package/docs/api/mcp/admin.md

@@ -54,6 +54,8 @@ Get all tasks and escalations for a process (origin_id).
 
 ## Escalations
 
+Escalations belong to a role's queue. Which of them a person sees and acts on is set by their work-surface scope: a role membership carries a `type` (`member`, `admin`, or `superadmin`) plus `read_scope` (`self` | `all`) — which escalations a member sees — and `write_scope` (`none` | `self` | `all`) — which they may claim, resolve, or cancel — with write ⊆ read. `read_self`/`write_self` narrows a member to items assigned to them (`assigned_to = user`); an `admin` or `superadmin` acts on the whole queue. The tools below operate at whole-queue breadth and need a role permitted to act on the target (see [Access](#access) above). The `assigned_to` filter on `find_escalations` pairs with this model — it narrows results to one user's items, the same surface a `read_self` member sees. Defaults are `all`/`all`. See the [Roles API](../http/roles.md) for the full scope model.
+
 ### find_escalations
 
 Search escalations with optional filters and sorting. Returns full records
@@ -659,11 +661,13 @@ Create a new user account with optional roles.
 | external_id | string | Yes | External identifier |
 | display_name | string | No | Display name |
 | email | string | No | Email address |
-| roles | object[] | No | Roles array (each: role, type: superadmin/admin/member) |
+| roles | object[] | No | Roles array (each: `role`, `type`: superadmin/admin/member, optional `read_scope`, `write_scope`) |
+
+Each role entry may carry a member work-surface scope: `read_scope` (`self` \| `all`, default `all`) and `write_scope` (`none` \| `self` \| `all`, default `all`), with write ⊆ read. This is how a one-time user is provisioned — e.g. `{ "role": "customer-triage", "type": "member", "read_scope": "self", "write_scope": "self" }` for someone who only handles their own pre-assigned escalation.
 
 ### add_user_role
 
-Assign a role to a user.
+Assign a role to a user. For a `member`, optional scope narrows the work surface.
 
 | | |
 |---|---|
@@ -676,6 +680,8 @@ Assign a role to a user.
 | user_id | string | Yes | User ID |
 | role | string | Yes | Role name |
 | type | string | Yes | Role type: superadmin, admin, or member |
+| read_scope | string | No | Member search breadth: `self` or `all` (default `all`) |
+| write_scope | string | No | Member claim/ack/delete breadth: `none`, `self`, or `all` (default `all`) |
 
 ### remove_user_role
 

package/docs/api/mcp/human-queue.md

@@ -65,7 +65,7 @@ List available escalations for a role. Returns pending, unassigned escalations.
 
 ### claim_and_resolve
 
-Claim an escalation and immediately resolve it with a payload. Atomic operation.
+Claim an escalation and immediately resolve it with a payload. Atomic operation. A read/write service account uses this to close out work and record the outcome in one call.
 
 | | |
 |---|---|
@@ -77,7 +77,24 @@ Claim an escalation and immediately resolve it with a payload. Atomic operation.
 |-------|------|----------|-------------|
 | escalation_id | string | Yes | The escalation ID to claim and resolve |
 | resolver_id | string | Yes | Identifier for who/what is resolving |
-| payload | object | Yes | Resolution payload data |
+| payload | object | Yes | Resolution payload data — resumes the waiting workflow |
+| metadata | object | No | Outcome facets merged into the escalation's metadata: the durable, `@>`-queryable record of what happened (disposition, reviewer, timing). Distinct from `payload`, which is not indexed |
+
+### resolve_escalation
+
+Resolve an already-claimed escalation with a payload. Use when the claim happened externally (e.g. via API).
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| escalation_id | string | Yes | The escalation ID to resolve |
+| payload | object | Yes | Resolution payload data — resumes the waiting workflow |
+| metadata | object | No | Outcome facets merged into the escalation's metadata (see `claim_and_resolve`) |
 
 ### escalate_and_wait
 
@@ -99,3 +116,18 @@ Create an escalation and pause the workflow until a human responds. Returns a si
 | type | string | No | Escalation type classification (default: "mcp") |
 | subtype | string | No | Escalation subtype (default: "wait_for_human") |
 | priority | number | No | Priority: 1 (highest) to 4 (lowest) (default: 1) |
+
+## Scope and One-Time Users
+
+Escalations created by these tools land in the target role's queue. Each member of that role sees and acts on them according to their work-surface scope — two axes carried by the role membership alongside its `type` (`member`, `admin`, or `superadmin`):
+
+- `read_scope` (`self` | `all`) governs which escalations a member sees. `read_all` shows the whole role queue; `read_self` shows only items assigned to the member (`assigned_to = user`).
+- `write_scope` (`none` | `self` | `all`) governs which a member may claim and resolve. `write_self` acts only on the member's own assigned items; `write_all` acts on the whole queue. The constraint is write ⊆ read — you cannot act on what you cannot see.
+
+An `admin` or `superadmin` member ignores scope and always acts on the whole queue. The defaults are `all`/`all` — the full-queue worker.
+
+`get_available_work` lists pending, unassigned escalations for a role: the shared pool that whole-queue (`write_all`) workers pull from. A `write_self` member does not draw from this pool — their item is pre-assigned to them.
+
+### The one-time-user pattern
+
+To route a single escalation to a named person, set `assigned_to` when creating it — the `assigned_to` field on `escalate_and_wait` pre-claims the item for that user — and provision that person as a `member` of the role with `read_self` + `write_self`. The result is a scoped single-item surface: they see and act on exactly that one escalation, with no access to the rest of the queue. The scoped membership is provisioned through the platform's user and escalation APIs (see the [Roles API](../http/roles.md)); these MCP tools supply the `assigned_to` pre-claim.

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