@hotmeshio/long-tail 0.5.12 → 0.6.0

package/build/routes/users.js

@@ -41,13 +41,14 @@ const router = (0, express_1.Router)();
 /**
  * GET /api/users
  * List users with optional filters.
- * Query: ?role=reviewer&roleType=admin&status=active&limit=50&offset=0
+ * Query: ?role=reviewer&roleType=admin&status=active&search=ada&limit=50&offset=0
  */
 router.get('/', async (req, res) => {
     const result = await api.listUsers({
         role: req.query.role,
         roleType: req.query.roleType,
         status: req.query.status,
+        search: req.query.search,
         limit: req.query.limit ? parseInt(req.query.limit, 10) : undefined,
         offset: req.query.offset ? parseInt(req.query.offset, 10) : undefined,
     });
@@ -99,15 +100,18 @@ router.get('/:id/roles', async (req, res) => {
 /**
  * POST /api/users/:id/roles
  * Add a role to a user.
- * Body: { role, type } — type must be superadmin, admin, or member
+ * Body: { role, type, read_scope?, write_scope? } — type must be superadmin,
+ * admin, or member. read_scope (self|all) and write_scope (none|self|all) refine
+ * a member's work surface; they default to all/all and are ignored for admin/superadmin.
  *
- * Scoping rules:
+ * Scoping rules (management tier):
  * - superadmin: can assign any role/type
  * - engineer: can assign up to admin type, but never superadmin type
  * - role/admin (non-builder): can only assign member/admin for roles they hold
+ * A caller who may assign a role may set any work-surface scope on it.
  */
 router.post('/:id/roles', auth_1.requireAdmin, async (req, res) => {
-    const { role, type } = req.body || {};
+    const { role, type, read_scope, write_scope } = req.body || {};
     const userId = req.auth.userId;
     // Superadmin bypasses all scoping
     const { isSuperAdmin } = await Promise.resolve().then(() => __importStar(require('../services/user/rbac')));
@@ -129,7 +133,7 @@ router.post('/:id/roles', auth_1.requireAdmin, async (req, res) => {
             }
         }
     }
-    const result = await api.addUserRole({ id: req.params.id, role, type });
+    const result = await api.addUserRole({ id: req.params.id, role, type, read_scope, write_scope });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 /**

package/build/sdk/index.d.ts

@@ -82,6 +82,12 @@ export declare function createClient(options?: LTClientOptions): {
             envelope?: string;
             metadata?: Record<string, any>;
             escalation_payload?: string;
+            origin_id?: string;
+            parent_id?: string;
+            task_id?: string;
+            workflow_id?: string;
+            task_queue?: string;
+            workflow_type?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         list: (input: {
             status?: string;
@@ -96,7 +102,7 @@ export declare function createClient(options?: LTClientOptions): {
             sort_by?: string;
             order?: string;
             search?: string;
-        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        } & import("../api/escalations/list").FacetInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         listAvailable: (input: {
             role?: string;
             type?: string;
@@ -107,8 +113,9 @@ export declare function createClient(options?: LTClientOptions): {
             sort_by?: string;
             order?: string;
             search?: string;
-        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        } & import("../api/escalations/list").FacetInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         listTypes: typeof escalationsApi.listDistinctTypes;
+        listFacetKeys: (input: unknown, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         getStats: (input: {
             period?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
@@ -131,6 +138,17 @@ export declare function createClient(options?: LTClientOptions): {
         resolve: (input: {
             id: string;
             resolverPayload: Record<string, any>;
+            metadata?: Record<string, any>;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        resolveBySignalKey: (input: {
+            signalKey: string;
+            resolverPayload: Record<string, any>;
+            metadata?: Record<string, any>;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        resolveByIds: (input: {
+            ids: string[];
+            resolverPayload: Record<string, any>;
+            metadata?: Record<string, any>;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         releaseExpired: typeof escalationsApi.releaseExpiredClaims;
         updatePriority: (input: {
@@ -176,6 +194,19 @@ export declare function createClient(options?: LTClientOptions): {
             assignee?: string;
             metadata?: Record<string, any>;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        searchByFacets: (input: import("..").FacetQuery, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        claimGroups: (input: {
+            query: import("..").FacetQuery;
+            limit?: number;
+            durationMinutes?: number;
+            sizeFacet?: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        claimByFacets: (input: {
+            query: import("..").FacetQuery;
+            limit?: number;
+            durationMinutes?: number;
+            allOrNone?: boolean;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
     };
     workflows: {
         invoke: (input: {

package/build/sdk/index.js

@@ -117,6 +117,7 @@ function createClient(options = {}) {
             list: bindAuth(escalationsApi.listEscalations, auth),
             listAvailable: bindAuth(escalationsApi.listAvailableEscalations, auth),
             listTypes: escalationsApi.listDistinctTypes,
+            listFacetKeys: bindAuth(escalationsApi.listFacetKeys, auth),
             getStats: bindAuth(escalationsApi.getEscalationStats, auth),
             get: bindAuth(escalationsApi.getEscalation, auth),
             getByWorkflowId: escalationsApi.getEscalationsByWorkflowId,
@@ -124,6 +125,8 @@ function createClient(options = {}) {
             claim: bindAuth(escalationsApi.claimEscalation, auth),
             release: bindAuth(escalationsApi.releaseEscalation, auth),
             resolve: bindAuth(escalationsApi.resolveEscalation, auth),
+            resolveBySignalKey: bindAuth(escalationsApi.resolveBySignalKey, auth),
+            resolveByIds: bindAuth(escalationsApi.resolveByIds, auth),
             releaseExpired: escalationsApi.releaseExpiredClaims,
             updatePriority: bindAuth(escalationsApi.updatePriority, auth),
             bulkClaim: bindAuth(escalationsApi.bulkClaim, auth),
@@ -133,6 +136,10 @@ function createClient(options = {}) {
             findByMetadata: bindAuth(escalationsApi.findByMetadata, auth),
             claimByMetadata: bindAuth(escalationsApi.claimByMetadata, auth),
             resolveByMetadata: bindAuth(escalationsApi.resolveByMetadata, auth),
+            // Faceted-routing surface (pond search + batch claim), RBAC-scoped to the caller's role.
+            searchByFacets: bindAuth(escalationsApi.searchByFacets, auth),
+            claimGroups: bindAuth(escalationsApi.claimGroups, auth),
+            claimByFacets: bindAuth(escalationsApi.claimByFacets, auth),
         },
         // ── Workflows ──────────────────────────────────────────────────────────
         workflows: {

package/build/services/escalation/crud.d.ts

@@ -12,8 +12,29 @@ export declare function claimEscalation(id: string, userId: string, durationMinu
  * orchestrator (api/escalations/resolve.ts); service-created rows have no
  * signal_key, so this never delivers a signal itself. Returns null when the
  * row is missing or already terminal.
+ *
+ * `metadata` (optional) is merged — not replaced — into the resolved row's
+ * GIN-indexed `metadata` in the same atomic UPDATE, and only on the winning
+ * resolve. It records "what actually happened" (outcome, duration, measured
+ * results) into the `@>`-queryable surface alongside the creation metadata
+ * ("what was intended"). Distinct from `resolverPayload`, which is delivered to
+ * the waiting workflow as `condition()`'s return value and is not GIN-indexed.
  */
-export declare function resolveEscalation(id: string, resolverPayload: Record<string, any>): Promise<LTEscalationRecord | null>;
+export declare function resolveEscalation(id: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>): Promise<LTEscalationRecord | null>;
+/**
+ * Resolve a SET of escalations by id in ONE guarded statement
+ * (`UPDATE … WHERE id = ANY($ids) AND status='pending'`). Returns the rows that
+ * won the resolve (already-terminal ids are excluded by the guard), and publishes
+ * a resolved event per winner.
+ *
+ * Use this over a per-row `resolveEscalation` loop when every row takes the SAME
+ * resolverPayload and the rows are woken collectively (or are bookkeeping rows with
+ * no signal_key). NOTE: unlike the single `resolve`, this does NOT deliver per-row
+ * signals — `resolveMany` is UPDATE-only. Do not use it for signal_key adverts whose
+ * resolution must wake a parked workflow; those require the per-row `resolveEscalation`
+ * (which delivers the signal).
+ */
+export declare function resolveEscalationsByIds(ids: string[], resolverPayload: Record<string, any>, metadata?: Record<string, any>): Promise<LTEscalationRecord[]>;
 /**
  * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
  * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.
@@ -30,8 +51,11 @@ export declare function getEscalationBySignalKey(signalKey: string): Promise<LTE
  * is delegated to `resolveEscalation`, whose `client.resolve` uses FOR UPDATE +
  * `WHERE status = 'pending'` so exactly one concurrent caller commits. No status
  * pre-check (that would be a TOCTOU window) — the atomic resolve is the arbiter.
+ *
+ * `metadata` (optional) records the resolution outcome into the row's
+ * GIN-indexed metadata atomically — see {@link resolveEscalation}.
  */
-export declare function resolveEscalationBySignalKey(signalKey: string, resolverPayload: Record<string, any>): Promise<LTEscalationRecord | null>;
+export declare function resolveEscalationBySignalKey(signalKey: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>): Promise<LTEscalationRecord | null>;
 /**
  * Mark an escalation cancelled — used when the tied workflow has terminated and
  * can never receive the resolution signal. The escalation is removed from the
@@ -49,6 +73,16 @@ export declare function updateEscalationsPriority(ids: string[], priority: 1 | 2
  * Used for permission validation before bulk operations.
  */
 export declare function getEscalationRoles(ids: string[]): Promise<string[]>;
+/**
+ * Fetch (id, role, assigned_to) for a set of escalation IDs — the minimal fields a
+ * write-scope gate needs to authorize a BULK action per item: write_all by role,
+ * write_self by ownership (assigned_to = caller). One query, no N+1.
+ */
+export declare function getEscalationScopeRows(ids: string[]): Promise<{
+    id: string;
+    role: string;
+    assigned_to: string | null;
+}[]>;
 /**
  * Release a single escalation claim back to the available pool.
  * Only the assigned user (or superadmin via route) may release.
@@ -79,7 +113,6 @@ export declare function getEscalationsByWorkflowId(workflowId: string): Promise<
  * This single UPDATE bypasses the SDK entirely and closes that gap.
  */
 export declare function cancelEscalationsByWorkflowId(workflowId: string): Promise<number>;
-export declare function updateEscalationMetadata(id: string, patch: Record<string, any>): Promise<LTEscalationRecord | null>;
 export declare function enrichEscalationRouting(id: string, metadataPatch: Record<string, any>, workflowFields: {
     workflowType?: string;
     workflowId?: string;
@@ -87,7 +120,20 @@ export declare function enrichEscalationRouting(id: string, metadataPatch: Recor
     taskId?: string;
 }): Promise<LTEscalationRecord | null>;
 export declare function getEscalationsByOriginId(originId: string): Promise<LTEscalationRecord[]>;
-export declare function findByMetadata(key: string, value: string, status?: string, limit?: number, offset?: number): Promise<{
+/**
+ * Find escalations by a metadata key/value, RBAC-scoped IN SQL.
+ *
+ * `allowedRoles` flows into BOTH the page query and the count: `undefined` =
+ * global (no role filter); a `string[]` filters `role = ANY(...)` (an empty array
+ * matches nothing). Filtering in SQL — never client-side over a fetched page — is
+ * what keeps `total` correct and pagination intact (a client-side filter shrinks a
+ * page and reports the wrong total).
+ */
+export declare function findByMetadata(key: string, value: string, status?: string, limit?: number, offset?: number, scope?: {
+    allRoles?: string[];
+    selfRoles?: string[];
+    meUserId?: string;
+}): Promise<{
     escalations: LTEscalationRecord[];
     total: number;
 }>;
@@ -97,7 +143,11 @@ export declare function findByMetadata(key: string, value: string, status?: stri
  * match zero rows. Returns `{ escalation, isExtension, candidatesExist }` or
  * null when nothing was claimed.
  *
- * @param allowedRoles — roles the caller can claim (null = no filter / global)
+ * @param allowedRoles — write_all roles the caller can claim (null = global / no
+ *   filter). The SDK applies a flat `role = ANY` filter and cannot express the
+ *   write_self ownership predicate, so self-scope members are intentionally
+ *   excluded from claim-by-metadata (their items are pre-claimed and resolved
+ *   by id). Self-scope claim-by-metadata would require a HotMesh SDK predicate.
  */
 export declare function claimByMetadata(key: string, value: string, userId: string, durationMinutes?: number, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<(ClaimResult & {
     candidatesExist: number;
@@ -131,4 +181,4 @@ export interface ResolveByMetadataResult {
  * business logic over the shared table, so it runs as one atomic statement on
  * `hmsh_escalations` rather than through the generic SDK resolve.
  */
-export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<ResolveByMetadataResult>;
+export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, writeAllRoles?: string[] | null, writeSelfRoles?: string[] | null): Promise<ResolveByMetadataResult>;

package/build/services/escalation/crud.js

@@ -3,11 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEscalation = createEscalation;
 exports.claimEscalation = claimEscalation;
 exports.resolveEscalation = resolveEscalation;
+exports.resolveEscalationsByIds = resolveEscalationsByIds;
 exports.getEscalationBySignalKey = getEscalationBySignalKey;
 exports.resolveEscalationBySignalKey = resolveEscalationBySignalKey;
 exports.cancelEscalation = cancelEscalation;
 exports.updateEscalationsPriority = updateEscalationsPriority;
 exports.getEscalationRoles = getEscalationRoles;
+exports.getEscalationScopeRows = getEscalationScopeRows;
 exports.releaseEscalation = releaseEscalation;
 exports.releaseExpiredClaims = releaseExpiredClaims;
 exports.escalateToRole = escalateToRole;
@@ -15,7 +17,6 @@ exports.getEscalation = getEscalation;
 exports.getEscalationsByTaskId = getEscalationsByTaskId;
 exports.getEscalationsByWorkflowId = getEscalationsByWorkflowId;
 exports.cancelEscalationsByWorkflowId = cancelEscalationsByWorkflowId;
-exports.updateEscalationMetadata = updateEscalationMetadata;
 exports.enrichEscalationRouting = enrichEscalationRouting;
 exports.getEscalationsByOriginId = getEscalationsByOriginId;
 exports.findByMetadata = findByMetadata;
@@ -24,6 +25,7 @@ exports.resolveByMetadataAtomic = resolveByMetadataAtomic;
 const db_1 = require("../../lib/db");
 const publish_1 = require("../../lib/events/publish");
 const client_1 = require("./client");
+const queries_1 = require("./queries");
 const map_1 = require("./map");
 const sql_1 = require("./sql");
 // All escalation state lives in `public.hmsh_escalations` (HotMesh 0.22.3),
@@ -94,10 +96,17 @@ async function claimEscalation(id, userId, durationMinutes = 30) {
  * orchestrator (api/escalations/resolve.ts); service-created rows have no
  * signal_key, so this never delivers a signal itself. Returns null when the
  * row is missing or already terminal.
+ *
+ * `metadata` (optional) is merged — not replaced — into the resolved row's
+ * GIN-indexed `metadata` in the same atomic UPDATE, and only on the winning
+ * resolve. It records "what actually happened" (outcome, duration, measured
+ * results) into the `@>`-queryable surface alongside the creation metadata
+ * ("what was intended"). Distinct from `resolverPayload`, which is delivered to
+ * the waiting workflow as `condition()`'s return value and is not GIN-indexed.
  */
-async function resolveEscalation(id, resolverPayload) {
+async function resolveEscalation(id, resolverPayload, metadata) {
     const client = await (0, client_1.escalations)();
-    const result = await client.resolve({ id, resolverPayload });
+    const result = await client.resolve({ id, resolverPayload, metadata });
     if (!result.ok)
         return null;
     const escalation = (0, map_1.toEscalationRecord)(result.entry);
@@ -113,6 +122,39 @@ async function resolveEscalation(id, resolverPayload) {
     });
     return escalation;
 }
+/**
+ * Resolve a SET of escalations by id in ONE guarded statement
+ * (`UPDATE … WHERE id = ANY($ids) AND status='pending'`). Returns the rows that
+ * won the resolve (already-terminal ids are excluded by the guard), and publishes
+ * a resolved event per winner.
+ *
+ * Use this over a per-row `resolveEscalation` loop when every row takes the SAME
+ * resolverPayload and the rows are woken collectively (or are bookkeeping rows with
+ * no signal_key). NOTE: unlike the single `resolve`, this does NOT deliver per-row
+ * signals — `resolveMany` is UPDATE-only. Do not use it for signal_key adverts whose
+ * resolution must wake a parked workflow; those require the per-row `resolveEscalation`
+ * (which delivers the signal).
+ */
+async function resolveEscalationsByIds(ids, resolverPayload, metadata) {
+    if (ids.length === 0)
+        return [];
+    const client = await (0, client_1.escalations)();
+    const rows = await client.resolveMany({ ids, resolverPayload, metadata });
+    const records = (0, map_1.toEscalationRecords)(rows);
+    for (const escalation of records) {
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.resolved',
+            source: 'service',
+            workflowId: escalation.workflow_id || '',
+            workflowName: escalation.workflow_type || '',
+            taskQueue: escalation.task_queue || '',
+            escalationId: escalation.id,
+            status: 'resolved',
+            data: {},
+        });
+    }
+    return records;
+}
 /**
  * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
  * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.
@@ -133,12 +175,15 @@ async function getEscalationBySignalKey(signalKey) {
  * is delegated to `resolveEscalation`, whose `client.resolve` uses FOR UPDATE +
  * `WHERE status = 'pending'` so exactly one concurrent caller commits. No status
  * pre-check (that would be a TOCTOU window) — the atomic resolve is the arbiter.
+ *
+ * `metadata` (optional) records the resolution outcome into the row's
+ * GIN-indexed metadata atomically — see {@link resolveEscalation}.
  */
-async function resolveEscalationBySignalKey(signalKey, resolverPayload) {
+async function resolveEscalationBySignalKey(signalKey, resolverPayload, metadata) {
     const escalation = await getEscalationBySignalKey(signalKey);
     if (!escalation)
         return null;
-    return resolveEscalation(escalation.id, resolverPayload);
+    return resolveEscalation(escalation.id, resolverPayload, metadata);
 }
 /**
  * Mark an escalation cancelled — used when the tied workflow has terminated and
@@ -185,6 +230,22 @@ async function getEscalationRoles(ids) {
     const rows = await client.list({ ids, limit: LOOKUP_LIMIT });
     return [...new Set(rows.map(r => r.role).filter((r) => !!r))];
 }
+/**
+ * Fetch (id, role, assigned_to) for a set of escalation IDs — the minimal fields a
+ * write-scope gate needs to authorize a BULK action per item: write_all by role,
+ * write_self by ownership (assigned_to = caller). One query, no N+1.
+ */
+async function getEscalationScopeRows(ids) {
+    if (ids.length === 0)
+        return [];
+    const client = await (0, client_1.escalations)();
+    const rows = await client.list({ ids, limit: LOOKUP_LIMIT });
+    return rows.map((r) => ({
+        id: r.id,
+        role: r.role,
+        assigned_to: r.assigned_to ?? null,
+    }));
+}
 /**
  * Release a single escalation claim back to the available pool.
  * Only the assigned user (or superadmin via route) may release.
@@ -284,11 +345,6 @@ async function cancelEscalationsByWorkflowId(workflowId) {
     }
     return rows.length;
 }
-async function updateEscalationMetadata(id, patch) {
-    const client = await (0, client_1.escalations)();
-    const entry = await client.update({ id, metadata: patch });
-    return entry ? (0, map_1.toEscalationRecord)(entry) : null;
-}
 async function enrichEscalationRouting(id, metadataPatch, workflowFields) {
     const client = await (0, client_1.escalations)();
     const entry = await client.update({
@@ -312,23 +368,31 @@ async function getEscalationsByOriginId(originId) {
     return (0, map_1.toEscalationRecords)(rows);
 }
 // --- Metadata candidate key lookups -----------------------------------------
-async function findByMetadata(key, value, status, limit = 50, offset = 0) {
-    const client = await (0, client_1.escalations)();
-    const metadata = { [key]: value };
-    const [rows, total] = await Promise.all([
-        client.list({
-            metadata,
-            status,
-            orderBy: [
-                { column: 'priority', direction: 'asc' },
-                { column: 'created_at', direction: 'asc' },
-            ],
-            limit,
-            offset,
-        }),
-        client.count({ metadata, status }),
-    ]);
-    return { escalations: (0, map_1.toEscalationRecords)(rows), total };
+/**
+ * Find escalations by a metadata key/value, RBAC-scoped IN SQL.
+ *
+ * `allowedRoles` flows into BOTH the page query and the count: `undefined` =
+ * global (no role filter); a `string[]` filters `role = ANY(...)` (an empty array
+ * matches nothing). Filtering in SQL — never client-side over a fetched page — is
+ * what keeps `total` correct and pagination intact (a client-side filter shrinks a
+ * page and reports the wrong total).
+ */
+async function findByMetadata(key, value, status, limit = 50, offset = 0, scope) {
+    // Route through the scoped list query so BOTH the role-scope filter
+    // (role ∈ allRoles OR (role ∈ selfRoles AND assigned_to = me)) AND the count
+    // run in SQL — never a client-side filter over a fetched page. allRoles travel
+    // as the flat `roles` filter; selfRoles + meUserId engage the raw-SQL scoped path.
+    return (0, queries_1.listEscalations)({
+        metadata: { [key]: value },
+        status: status,
+        visibleRoles: scope?.allRoles,
+        selfRoles: scope?.selfRoles,
+        meUserId: scope?.meUserId,
+        sort_by: 'priority',
+        order: 'asc',
+        limit,
+        offset,
+    });
 }
 /**
  * Atomic claim by metadata with inline RBAC and optional metadata merge.
@@ -336,7 +400,11 @@ async function findByMetadata(key, value, status, limit = 50, offset = 0) {
  * match zero rows. Returns `{ escalation, isExtension, candidatesExist }` or
  * null when nothing was claimed.
  *
- * @param allowedRoles — roles the caller can claim (null = no filter / global)
+ * @param allowedRoles — write_all roles the caller can claim (null = global / no
+ *   filter). The SDK applies a flat `role = ANY` filter and cannot express the
+ *   write_self ownership predicate, so self-scope members are intentionally
+ *   excluded from claim-by-metadata (their items are pre-claimed and resolved
+ *   by id). Self-scope claim-by-metadata would require a HotMesh SDK predicate.
  */
 async function claimByMetadata(key, value, userId, durationMinutes = 30, metadata, allowedRoles) {
     const client = await (0, client_1.escalations)();
@@ -377,14 +445,17 @@ async function claimByMetadata(key, value, userId, durationMinutes = 30, metadat
  * business logic over the shared table, so it runs as one atomic statement on
  * `hmsh_escalations` rather than through the generic SDK resolve.
  */
-async function resolveByMetadataAtomic(key, value, userId, resolverPayload, metadata, allowedRoles) {
+async function resolveByMetadataAtomic(key, value, userId, resolverPayload, metadata, writeAllRoles, writeSelfRoles) {
     await (0, client_1.ensureEscalationCompatView)();
     const pool = (0, db_1.getPool)();
     const filter = JSON.stringify({ [key]: value });
     const payloadJson = JSON.stringify(resolverPayload);
     const metaPatch = metadata ? JSON.stringify(metadata) : null;
-    const roles = allowedRoles ?? null;
-    const { rows } = await pool.query(sql_1.RESOLVE_BY_METADATA_ATOMIC, [filter, userId, payloadJson, metaPatch, roles]);
+    // null write_all roles = global (no filter). A scoped caller passes its arrays
+    // (possibly empty); the write_self branch matches only rows assigned to userId.
+    const allRoles = writeAllRoles ?? null;
+    const selfRoles = writeSelfRoles ?? null;
+    const { rows } = await pool.query(sql_1.RESOLVE_BY_METADATA_ATOMIC, [filter, userId, payloadJson, metaPatch, allRoles, selfRoles]);
     if (rows.length === 0)
         return { outcome: 'not_found' };
     const row = rows[0];

package/build/services/escalation/facet-sql.d.ts

@@ -0,0 +1,18 @@
+import type { FacetOrder, FacetQuery } from '../../types';
+/**
+ * Build the WHERE clause for a faceted query, pushing bound params into `params`.
+ * Every value is parameterized; only validated column names / metadata keys and
+ * a fixed operator set are interpolated. Returns `TRUE` when empty.
+ */
+export declare function buildFacetWhere(q: FacetQuery, params: unknown[]): string;
+/** Build an injection-safe ORDER BY mixing top-level columns and metadata facets. */
+export declare function buildFacetOrder(orderBy?: FacetOrder[]): string;
+/**
+ * Group rank for the all-or-nothing claim: each sort key aggregated across the
+ * group's members — `min` for ascending, `max` for descending — so a faceted
+ * order over members yields a stable order over orders. Defaults to the natural
+ * priority/FIFO order.
+ */
+export declare function buildGroupOrder(orderBy?: FacetOrder[]): string;
+/** Lazily-ensured index for the group aggregation (origin_id over the pending pool). */
+export declare const ENSURE_ORIGIN_INDEX = "CREATE INDEX IF NOT EXISTS idx_hmsh_escalations_origin_pending\n     ON public.hmsh_escalations (origin_id) WHERE status = 'pending'";

package/build/services/escalation/facet-sql.js

@@ -0,0 +1,118 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Faceted routing SQL — composable, injection-safe predicate + ORDER BY builders
+// over the escalation queue. Reads go through the `public.lt_escalations` view
+// (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 services/escalation/sql.ts. Metadata facets use the GIN index (`@>`).
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENSURE_ORIGIN_INDEX = void 0;
+exports.buildFacetWhere = buildFacetWhere;
+exports.buildFacetOrder = buildFacetOrder;
+exports.buildGroupOrder = buildGroupOrder;
+// Top-level columns a caller may sort/range on directly. Anything else must be a
+// `metadata.<key>` facet. Keeps interpolation to a fixed, audited set.
+const ORDER_COLUMNS = new Set(['priority', 'created_at', 'updated_at', 'status', 'role']);
+const RANGE_OPS = new Set(['<', '<=', '>', '>=', '=']);
+// Metadata keys are interpolated (as a JSON path), so they are strictly validated.
+const FACET_KEY = /^[a-zA-Z0-9_]+$/;
+/** A metadata extraction expression for a validated key (text or numeric). */
+function metaExpr(key, numeric = false) {
+    return numeric ? `(metadata->>'${key}')::numeric` : `(metadata->>'${key}')`;
+}
+/**
+ * Build the WHERE clause for a faceted query, pushing bound params into `params`.
+ * Every value is parameterized; only validated column names / metadata keys and
+ * a fixed operator set are interpolated. Returns `TRUE` when empty.
+ */
+function buildFacetWhere(q, params) {
+    const clauses = [];
+    if (q.role) {
+        params.push(q.role);
+        clauses.push(`role = $${params.length}`);
+    }
+    else if (q.roles && q.roles.length) {
+        params.push(q.roles);
+        clauses.push(`role = ANY($${params.length}::text[])`);
+    }
+    if (q.status) {
+        params.push(q.status);
+        clauses.push(`status = $${params.length}`);
+    }
+    if (q.facets && Object.keys(q.facets).length) {
+        params.push(JSON.stringify(q.facets));
+        clauses.push(`metadata @> $${params.length}::jsonb`); // GIN-served
+    }
+    if (q.block && q.block.length) {
+        params.push(q.block.map((b) => JSON.stringify(b)));
+        clauses.push(`NOT (metadata @> ANY($${params.length}::jsonb[]))`);
+    }
+    for (const r of q.range ?? []) {
+        if (!FACET_KEY.test(r.facet) || !RANGE_OPS.has(r.op))
+            continue;
+        params.push(r.value);
+        clauses.push(`${metaExpr(r.facet, true)} ${r.op} $${params.length}`);
+    }
+    for (const key of q.exists ?? []) {
+        if (!FACET_KEY.test(key))
+            continue;
+        clauses.push(`metadata ? '${key}'`);
+    }
+    if (q.available === true) {
+        clauses.push(`(assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW())`);
+    }
+    else if (q.available === false) {
+        clauses.push(`(assigned_to IS NOT NULL AND assigned_until > NOW())`);
+    }
+    return clauses.length ? clauses.join('\n  AND ') : 'TRUE';
+}
+const DEFAULT_ORDER = 'priority ASC, created_at ASC';
+/** Build an injection-safe ORDER BY mixing top-level columns and metadata facets. */
+function buildFacetOrder(orderBy) {
+    if (!orderBy || !orderBy.length)
+        return DEFAULT_ORDER;
+    const parts = [];
+    for (const o of orderBy) {
+        const dir = o.direction === 'desc' ? 'DESC' : 'ASC';
+        if (ORDER_COLUMNS.has(o.field)) {
+            parts.push(`${o.field} ${dir}`);
+        }
+        else if (o.field.startsWith('metadata.')) {
+            const key = o.field.slice('metadata.'.length);
+            if (!FACET_KEY.test(key))
+                continue;
+            parts.push(`${metaExpr(key, o.numeric)} ${dir} NULLS LAST`);
+        }
+    }
+    return parts.length ? parts.join(', ') : DEFAULT_ORDER;
+}
+/**
+ * Group rank for the all-or-nothing claim: each sort key aggregated across the
+ * group's members — `min` for ascending, `max` for descending — so a faceted
+ * order over members yields a stable order over orders. Defaults to the natural
+ * priority/FIFO order.
+ */
+function buildGroupOrder(orderBy) {
+    if (!orderBy || !orderBy.length)
+        return 'min(priority) ASC, min(created_at) ASC';
+    const parts = [];
+    for (const o of orderBy) {
+        const desc = o.direction === 'desc';
+        const agg = desc ? 'max' : 'min';
+        const dir = desc ? 'DESC' : 'ASC';
+        if (ORDER_COLUMNS.has(o.field)) {
+            parts.push(`${agg}(${o.field}) ${dir}`);
+        }
+        else if (o.field.startsWith('metadata.')) {
+            const key = o.field.slice('metadata.'.length);
+            if (!FACET_KEY.test(key))
+                continue;
+            parts.push(`${agg}(${metaExpr(key, o.numeric)}) ${dir} NULLS LAST`);
+        }
+    }
+    return parts.length ? parts.join(', ') : 'min(priority) ASC, min(created_at) ASC';
+}
+/** Lazily-ensured index for the group aggregation (origin_id over the pending pool). */
+exports.ENSURE_ORIGIN_INDEX = `CREATE INDEX IF NOT EXISTS idx_hmsh_escalations_origin_pending
+     ON public.hmsh_escalations (origin_id) WHERE status = 'pending'`;

package/build/services/escalation/facets.d.ts

@@ -0,0 +1,45 @@
+import type { ClaimedGroup, FacetQuery, GroupSummary, LTEscalationRecord } from '../../types';
+/** Ensure the compat view + the origin_id index exist before the first query. */
+export declare function ensureFacetReady(): Promise<void>;
+/** Item-level faceted search — filter/sort over top-level columns and metadata facets. */
+export declare function searchByFacets(query: FacetQuery): Promise<{
+    escalations: LTEscalationRecord[];
+    total: number;
+}>;
+/**
+ * Order-level view of the pond — what a batched dispatcher reads to page by
+ * capacity. Each row is an order (origin) with its unit count, availability and
+ * completeness, so the app grabs only as many orders as it has free consumers.
+ */
+export declare function searchGroups(query: FacetQuery, opts?: {
+    sizeFacet?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<GroupSummary[]>;
+/** Aggregate count — capacity / in-flight soft-limit checks. */
+export declare function countByFacets(query: FacetQuery): Promise<number>;
+/**
+ * Pull a *page* of complete orders — the dispatcher primitive. Claims up to
+ * `limit` eligible orders (each all-or-nothing) in rank order, skipping any a
+ * competing dispatcher holds. Page `limit` = how many consumers/printers are
+ * free, so a dependent grabs exactly as much as it can distribute. `limit=1`
+ * claims a single order.
+ */
+export declare function claimGroups(query: FacetQuery, consumer: string, opts?: {
+    limit?: number;
+    durationMinutes?: number;
+    sizeFacet?: string;
+}): Promise<ClaimedGroup[]>;
+/**
+ * Batch-claim *individual* escalations matching a facet query — the single-row
+ * sibling of `claimGroups`. Locks up to `limit` available rows in rank order with
+ * `FOR UPDATE SKIP LOCKED`, so concurrent claimers take disjoint sets without
+ * contention. With `allOrNone`, the claim commits only when the full `limit` was
+ * acquired (otherwise it rolls back and returns `[]`) — the all-or-none lock a
+ * dispatcher wants over a counted set it anticipated. Returns the claimed records.
+ */
+export declare function claimByFacets(query: FacetQuery, consumer: string, opts?: {
+    limit?: number;
+    durationMinutes?: number;
+    allOrNone?: boolean;
+}): Promise<LTEscalationRecord[]>;