@hotmeshio/long-tail 0.5.12 → 0.6.2

package/build/api/users.js

@@ -48,6 +48,7 @@ const userService = __importStar(require("../services/user"));
  * @param input.role — filter by role name
  * @param input.roleType — filter by role type (superadmin, admin, member)
  * @param input.status — filter by user status
+ * @param input.search — free-text match on display name, email, or external_id
  * @param input.limit — maximum number of users to return
  * @param input.offset — number of users to skip for pagination
  * @returns `{ status: 200, data: User[] }` on success
@@ -105,6 +106,17 @@ async function createUser(input) {
                         error: 'Each role must have a role name and type (superadmin, admin, member)',
                     };
                 }
+                if (r.read_scope !== undefined && !userService.isValidReadScope(r.read_scope)) {
+                    return { status: 400, error: 'read_scope must be self or all' };
+                }
+                if (r.write_scope !== undefined && !userService.isValidWriteScope(r.write_scope)) {
+                    return { status: 400, error: 'write_scope must be none, self, or all' };
+                }
+                const read = (r.read_scope ?? userService.DEFAULT_READ_SCOPE);
+                const write = (r.write_scope ?? userService.DEFAULT_WRITE_SCOPE);
+                if (!userService.isValidScopePair(read, write)) {
+                    return { status: 400, error: 'write_scope=all requires read_scope=all' };
+                }
             }
         }
         const user = await userService.createUser({
@@ -201,7 +213,23 @@ async function addUserRole(input) {
         if (!userService.isValidRoleType(input.type)) {
             return { status: 400, error: 'type must be superadmin, admin, or member' };
         }
-        const result = await userService.addUserRole(input.id, input.role, input.type);
+        // Work-surface scope (optional; defaults to all/all = full worker). Only
+        // meaningful for `member`; admin/superadmin normalize to all/all.
+        if (input.read_scope !== undefined && !userService.isValidReadScope(input.read_scope)) {
+            return { status: 400, error: 'read_scope must be self or all' };
+        }
+        if (input.write_scope !== undefined && !userService.isValidWriteScope(input.write_scope)) {
+            return { status: 400, error: 'write_scope must be none, self, or all' };
+        }
+        const read = (input.read_scope ?? userService.DEFAULT_READ_SCOPE);
+        const write = (input.write_scope ?? userService.DEFAULT_WRITE_SCOPE);
+        if (!userService.isValidScopePair(read, write)) {
+            return { status: 400, error: 'write_scope=all requires read_scope=all (cannot act on what you cannot see)' };
+        }
+        const result = await userService.addUserRole(input.id, input.role, input.type, {
+            read_scope: read,
+            write_scope: write,
+        });
         return { status: 201, data: result };
     }
     catch (err) {

package/build/bin/ltc.js

@@ -120,6 +120,13 @@ escCmd.command('list')
     .option('--status <status>', 'Filter by status (pending, resolved, cancelled)')
     .option('--role <role>', 'Filter by role')
     .option('--limit <n>', 'Max results')
+    .option('--facets <json>', 'Required metadata facets, JSON object (metadata @>), e.g. \'{"filament":"pla"}\'')
+    .option('--block <json>', 'Exclude rows containing ANY of these facet sets, JSON array')
+    .option('--range <json>', 'Numeric ranges over facets, JSON array e.g. \'[{"facet":"confidence","op":"<=","value":0.7}]\'')
+    .option('--exists <json>', 'Metadata keys that must be present, JSON array of strings')
+    .option('--roles <json>', 'Restrict to these roles, JSON array (narrows within scope)')
+    .option('--available <bool>', 'true = unclaimed/expired only; false = held now')
+    .option('--order-by <json>', 'Sort keys, JSON array e.g. \'[{"field":"metadata.confidence","numeric":true,"direction":"asc"}]\'')
     .option('--json', 'JSON output')
     .option('-q, --quiet', 'IDs only')
     .action(wrap(esc.listEscalations));
@@ -153,6 +160,39 @@ escCmd.command('resolve-by-meta <key> <value>')
     .option('--assignee <external_id>', 'Resolve on behalf of user (external_id)')
     .option('--meta <json>', 'Merge metadata (JSON object)')
     .action(wrap(esc.resolveByMetadata));
+escCmd.command('resolve-by-ids <ids...>')
+    .description('Resolve a set of escalations by id')
+    .requiredOption('--payload <json>', 'Resolver payload (JSON string)')
+    .option('--metadata <json>', 'Merge metadata (JSON object)')
+    .action(wrap(esc.resolveByIds));
+escCmd.command('search-facets')
+    .description('Item-level faceted search over a pond (role-scoped)')
+    .requiredOption('--role <role>', 'Pond role to search')
+    .option('--status <status>', 'Filter by status')
+    .option('--available', 'Only available (unclaimed/expired)')
+    .option('--facets <json>', 'Required facets (JSON object)')
+    .option('--limit <n>', 'Max results')
+    .option('--json', 'JSON output')
+    .option('-q, --quiet', 'IDs only')
+    .action(wrap(esc.searchByFacets));
+escCmd.command('claim-groups')
+    .description('Batch-claim complete origin groups in priority order')
+    .requiredOption('--role <role>', 'Pond role to claim from')
+    .option('--facets <json>', 'Required facets (JSON object)')
+    .option('--limit <n>', 'Max groups to claim')
+    .option('--duration <minutes>', 'Claim duration in minutes')
+    .option('--size-facet <key>', 'Metadata facet declaring group size')
+    .option('--json', 'JSON output')
+    .action(wrap(esc.claimGroups));
+escCmd.command('claim-by-facets')
+    .description('Batch-claim individual rows matching facets')
+    .requiredOption('--role <role>', 'Pond role to claim from')
+    .option('--facets <json>', 'Required facets (JSON object)')
+    .option('--limit <n>', 'Max rows to claim')
+    .option('--duration <minutes>', 'Claim duration in minutes')
+    .option('--all-or-none', 'Claim all matched rows or none')
+    .option('--json', 'JSON output')
+    .action(wrap(esc.claimByFacets));
 // ── Workflows ────────────────────────────────────────────────────────────
 const wfCmd = commander_1.program.command('workflows').alias('wf').description('Manage durable workflows');
 wfCmd.command('list')

package/build/lib/cli/commands/escalations.d.ts

@@ -4,6 +4,13 @@ interface ListOptions {
     limit?: string;
     json?: boolean;
     quiet?: boolean;
+    facets?: string;
+    block?: string;
+    range?: string;
+    exists?: string;
+    roles?: string;
+    available?: string;
+    orderBy?: string;
 }
 export declare function listEscalations(opts: ListOptions): Promise<void>;
 export declare function getEscalation(id: string, opts: {
@@ -27,4 +34,33 @@ export declare function resolveByMetadata(key: string, value: string, opts: {
     assignee?: string;
     meta?: string;
 }): Promise<void>;
+export declare function resolveByIds(ids: string[], opts: {
+    payload: string;
+    metadata?: string;
+}): Promise<void>;
+export declare function searchByFacets(opts: {
+    role: string;
+    status?: string;
+    available?: boolean;
+    facets?: string;
+    limit?: string;
+    json?: boolean;
+    quiet?: boolean;
+}): Promise<void>;
+export declare function claimGroups(opts: {
+    role: string;
+    facets?: string;
+    limit?: string;
+    duration?: string;
+    sizeFacet?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function claimByFacets(opts: {
+    role: string;
+    facets?: string;
+    limit?: string;
+    duration?: string;
+    allOrNone?: boolean;
+    json?: boolean;
+}): Promise<void>;
 export {};

package/build/lib/cli/commands/escalations.js

@@ -11,6 +11,10 @@ exports.resolveEscalation = resolveEscalation;
 exports.findByMetadata = findByMetadata;
 exports.claimByMetadata = claimByMetadata;
 exports.resolveByMetadata = resolveByMetadata;
+exports.resolveByIds = resolveByIds;
+exports.searchByFacets = searchByFacets;
+exports.claimGroups = claimGroups;
+exports.claimByFacets = claimByFacets;
 const picocolors_1 = __importDefault(require("picocolors"));
 const client_1 = require("../client");
 const format_1 = require("../format");
@@ -30,6 +34,22 @@ async function listEscalations(opts) {
         params.set('role', opts.role);
     if (opts.limit)
         params.set('limit', opts.limit);
+    // Faceted query elements travel as JSON-encoded query params (the route JSON-parses
+    // them). parseJsonOption validates the input and throws a friendly error on bad JSON.
+    if (opts.facets)
+        params.set('facets', JSON.stringify(parseJsonOption('--facets', opts.facets)));
+    if (opts.block)
+        params.set('block', JSON.stringify(parseJsonOption('--block', opts.block)));
+    if (opts.range)
+        params.set('range', JSON.stringify(parseJsonOption('--range', opts.range)));
+    if (opts.exists)
+        params.set('exists', JSON.stringify(parseJsonOption('--exists', opts.exists)));
+    if (opts.roles)
+        params.set('roles', JSON.stringify(parseJsonOption('--roles', opts.roles)));
+    if (opts.orderBy)
+        params.set('orderBy', JSON.stringify(parseJsonOption('--order-by', opts.orderBy)));
+    if (opts.available != null)
+        params.set('available', opts.available);
     const data = await (0, client_1.apiFetch)(`/escalations?${params}`);
     (0, format_1.output)(data, data.escalations || [], COLUMNS, opts);
 }
@@ -107,3 +127,81 @@ async function resolveByMetadata(key, value, opts) {
     });
     console.log(`\n  ${picocolors_1.default.green('✓')} Resolved by ${key}=${value}\n`);
 }
+// --- Faceted routing commands -----------------------------------------------
+function parseJsonOption(label, raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON for ${label}: ${raw}`);
+    }
+}
+async function resolveByIds(ids, opts) {
+    const resolverPayload = parseJsonOption('--payload', opts.payload);
+    const body = { ids, resolverPayload };
+    if (opts.metadata)
+        body.metadata = parseJsonOption('--metadata', opts.metadata);
+    const data = await (0, client_1.apiFetch)('/escalations/resolve-by-ids', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    console.log(`\n  ${picocolors_1.default.green('✓')} Resolved ${data.resolved} escalation(s)\n`);
+}
+async function searchByFacets(opts) {
+    const query = { role: opts.role };
+    if (opts.status)
+        query.status = opts.status;
+    if (opts.available)
+        query.available = true;
+    if (opts.facets)
+        query.facets = parseJsonOption('--facets', opts.facets);
+    if (opts.limit)
+        query.limit = parseInt(opts.limit, 10);
+    const data = await (0, client_1.apiFetch)('/escalations/search-by-facets', {
+        method: 'POST',
+        body: JSON.stringify(query),
+    });
+    (0, format_1.output)(data, data.escalations || [], COLUMNS, opts);
+}
+async function claimGroups(opts) {
+    const query = { role: opts.role };
+    if (opts.facets)
+        query.facets = parseJsonOption('--facets', opts.facets);
+    const body = { query };
+    if (opts.limit)
+        body.limit = parseInt(opts.limit, 10);
+    if (opts.duration)
+        body.durationMinutes = parseInt(opts.duration, 10);
+    if (opts.sizeFacet)
+        body.sizeFacet = opts.sizeFacet;
+    const data = await (0, client_1.apiFetch)('/escalations/claim-groups', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    console.log(`\n  ${picocolors_1.default.green('✓')} Claimed ${data.groups?.length || 0} group(s)\n`);
+}
+async function claimByFacets(opts) {
+    const query = { role: opts.role };
+    if (opts.facets)
+        query.facets = parseJsonOption('--facets', opts.facets);
+    const body = { query };
+    if (opts.limit)
+        body.limit = parseInt(opts.limit, 10);
+    if (opts.duration)
+        body.durationMinutes = parseInt(opts.duration, 10);
+    if (opts.allOrNone)
+        body.allOrNone = true;
+    const data = await (0, client_1.apiFetch)('/escalations/claim-by-facets', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    console.log(`\n  ${picocolors_1.default.green('✓')} Claimed ${data.claimed?.length || 0} escalation(s)\n`);
+}

package/build/lib/db/schemas/001_schema.sql

@@ -99,11 +99,16 @@ CREATE OR REPLACE TRIGGER lt_users_updated_at
 -- ─── lt_user_roles ───────────────────────────────────────────────────────────
 
 CREATE TABLE IF NOT EXISTS lt_user_roles (
-  user_id    UUID NOT NULL REFERENCES lt_users(id) ON DELETE CASCADE,
-  role       TEXT NOT NULL REFERENCES lt_roles(role),
-  type       TEXT NOT NULL DEFAULT 'member' CHECK (type IN ('superadmin', 'admin', 'member')),
-  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  PRIMARY KEY (user_id, role)
+  user_id     UUID NOT NULL REFERENCES lt_users(id) ON DELETE CASCADE,
+  role        TEXT NOT NULL REFERENCES lt_roles(role),
+  type        TEXT NOT NULL DEFAULT 'member' CHECK (type IN ('superadmin', 'admin', 'member')),
+  -- Work-surface scope (orthogonal to `type`, ignored for admin/superadmin).
+  -- read governs search, write governs claim/ack/delete. write ⊆ read.
+  read_scope  TEXT NOT NULL DEFAULT 'all' CHECK (read_scope IN ('self', 'all')),
+  write_scope TEXT NOT NULL DEFAULT 'all' CHECK (write_scope IN ('none', 'self', 'all')),
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (user_id, role),
+  CONSTRAINT chk_lt_user_roles_scope CHECK (NOT (write_scope = 'all' AND read_scope = 'self'))
 );
 
 CREATE INDEX IF NOT EXISTS idx_lt_user_roles_type ON lt_user_roles (type);

package/build/lib/db/schemas/012_lt_tasks_workflow_id_unique.sql

@@ -0,0 +1,20 @@
+-- ─── 012: lt_tasks.workflow_id uniqueness ─────────────────────────────────────
+-- A task is 1:1 with its workflow_id. Every createTask caller keys the row by a
+-- deterministic workflow_id (orchestrator childWorkflowId, interceptor
+-- wf.workflowId, escalation triage-<id>), and createTask runs inside a
+-- proxyActivity with retry { maximumAttempts: 3 }. Without a unique constraint a
+-- retry — or a re-driven triage saga — double-inserts a task row. The unique
+-- index lets createTask use ON CONFLICT (workflow_id) so retries converge instead
+-- of duplicating, matching how HotMesh upserts the sibling job by (workflowId, app_id).
+
+-- Collapse any pre-existing duplicates, keeping the most recent row per workflow_id
+-- (tie-break on id so exactly one survives and the unique index can be built).
+DELETE FROM lt_tasks a
+USING lt_tasks b
+WHERE a.workflow_id = b.workflow_id
+  AND (a.created_at < b.created_at
+       OR (a.created_at = b.created_at AND a.id < b.id));
+
+-- Replace the non-unique lookup index with a unique one (it still serves lookups).
+DROP INDEX IF EXISTS idx_lt_tasks_workflow_id;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_lt_tasks_workflow_id ON lt_tasks (workflow_id);

package/build/lib/db/schemas/013_role_scope.sql

@@ -0,0 +1,37 @@
+-- ─── lt_user_roles: read/write work-surface scope ──────────────────────────
+--
+-- Open roles split the worker capability into two orthogonal axes so that
+-- one-time and limited-surface users are first-class:
+--
+--   read_scope  (self | all)        → governs SEARCH (which items appear)
+--   write_scope (none | self | all) → governs CLAIM / ACK / DELETE
+--
+-- `self` = escalations assigned to the user (assigned_to = userId); `all` = the
+-- whole role queue. The only constraint is write ⊆ read (you cannot act on what
+-- you cannot see). `type` (member/admin/superadmin) is unchanged — it remains the
+-- management/global tier, and admin/superadmin ignore scope (always act on all).
+--
+-- Existing rows default to ('all','all') = today's `member` behavior, so this is
+-- backward compatible with zero data backfill. Idempotent: no-op on fresh installs
+-- where 001_schema.sql already created the columns and the named constraint.
+
+ALTER TABLE lt_user_roles
+  ADD COLUMN IF NOT EXISTS read_scope  TEXT NOT NULL DEFAULT 'all'
+    CHECK (read_scope IN ('self', 'all'));
+
+ALTER TABLE lt_user_roles
+  ADD COLUMN IF NOT EXISTS write_scope TEXT NOT NULL DEFAULT 'all'
+    CHECK (write_scope IN ('none', 'self', 'all'));
+
+-- write ⊆ read: cannot act on the whole queue while only reading your own.
+-- Guarded so a re-run (or a fresh install where 001 already added it) is a no-op.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'chk_lt_user_roles_scope'
+  ) THEN
+    ALTER TABLE lt_user_roles
+      ADD CONSTRAINT chk_lt_user_roles_scope
+      CHECK (NOT (write_scope = 'all' AND read_scope = 'self'));
+  END IF;
+END $$;

package/build/modules/version.d.ts

@@ -7,10 +7,15 @@
  */
 export declare const HOTMESH_VERSION: string;
 /**
- * The long-tail app version. Read from the root package.json at runtime via the
- * process working directory (which is the app root in both dev and the Docker
- * image, where CMD runs `node build/index.js` from /app). A static
- * `../package.json` import would resolve to build/package.json after compile —
- * a path the Dockerfile does not copy — so this reads from cwd instead.
+ * The long-tail package version.
+ *
+ * Resolved from long-tail's OWN package.json by walking up from this module's
+ * directory to the first package.json named `@hotmeshio/long-tail`. Reading
+ * `process.cwd()/package.json` is wrong when long-tail is consumed as a
+ * dependency (e.g. mounted as a NestJS module) — cwd is then the HOST app's
+ * root, so it reported the host's version. The upward walk resolves correctly in
+ * dev (source tree), the standalone Docker image (`/app`), and under
+ * `node_modules/@hotmeshio/long-tail`. A static `../package.json` import can't be
+ * used: post-compile it resolves to `build/package.json`, which is not shipped.
  */
 export declare const LONG_TAIL_VERSION: string;

package/build/modules/version.js

@@ -15,20 +15,36 @@ const package_json_1 = __importDefault(require("@hotmeshio/hotmesh/package.json"
  * node_modules), and resolveJsonModule handles the static import at compile time.
  */
 exports.HOTMESH_VERSION = package_json_1.default.version ?? 'unknown';
+const LONG_TAIL_PACKAGE_NAME = '@hotmeshio/long-tail';
 /**
- * The long-tail app version. Read from the root package.json at runtime via the
- * process working directory (which is the app root in both dev and the Docker
- * image, where CMD runs `node build/index.js` from /app). A static
- * `../package.json` import would resolve to build/package.json after compile —
- * a path the Dockerfile does not copy — so this reads from cwd instead.
+ * The long-tail package version.
+ *
+ * Resolved from long-tail's OWN package.json by walking up from this module's
+ * directory to the first package.json named `@hotmeshio/long-tail`. Reading
+ * `process.cwd()/package.json` is wrong when long-tail is consumed as a
+ * dependency (e.g. mounted as a NestJS module) — cwd is then the HOST app's
+ * root, so it reported the host's version. The upward walk resolves correctly in
+ * dev (source tree), the standalone Docker image (`/app`), and under
+ * `node_modules/@hotmeshio/long-tail`. A static `../package.json` import can't be
+ * used: post-compile it resolves to `build/package.json`, which is not shipped.
  */
 exports.LONG_TAIL_VERSION = readLongTailVersion();
 function readLongTailVersion() {
-    try {
-        const raw = (0, fs_1.readFileSync)((0, path_1.resolve)(process.cwd(), 'package.json'), 'utf8');
-        return JSON.parse(raw).version ?? 'unknown';
-    }
-    catch {
-        return 'unknown';
+    let dir = __dirname;
+    const { root } = (0, path_1.parse)(dir);
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        try {
+            const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(dir, 'package.json'), 'utf8'));
+            if (pkg.name === LONG_TAIL_PACKAGE_NAME)
+                return pkg.version ?? 'unknown';
+        }
+        catch {
+            /* no readable package.json here — keep walking up */
+        }
+        if (dir === root)
+            break;
+        dir = (0, path_1.dirname)(dir);
     }
+    return 'unknown';
 }

package/build/routes/escalations/facets.d.ts

@@ -0,0 +1,7 @@
+import { Router } from 'express';
+/**
+ * Faceted-routing HTTP surface — pond search + batch claim. Each operation targets a
+ * single pond `role` and is RBAC-scoped to it (the api layer enforces the gate). These
+ * mirror the SDK `escalations.searchByFacets / claimGroups / claimByFacets`.
+ */
+export declare function registerFacetRoutes(router: Router): void;

package/build/routes/escalations/facets.js

@@ -0,0 +1,81 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFacetRoutes = registerFacetRoutes;
+const api = __importStar(require("../../api/escalations"));
+/**
+ * Faceted-routing HTTP surface — pond search + batch claim. Each operation targets a
+ * single pond `role` and is RBAC-scoped to it (the api layer enforces the gate). These
+ * mirror the SDK `escalations.searchByFacets / claimGroups / claimByFacets`.
+ */
+function registerFacetRoutes(router) {
+    /**
+     * POST /api/escalations/search-by-facets
+     * Item-level faceted search over a pond, scoped to the caller's role.
+     * Body: FacetQuery — { role, status?, available?, facets?, orderBy?, limit?, offset? }
+     */
+    router.post('/search-by-facets', async (req, res) => {
+        const result = await api.searchByFacets(req.body ?? {}, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/claim-groups
+     * Batch-claim complete origin groups in priority order, assigned to the caller.
+     * Body: { query: FacetQuery, limit?, durationMinutes?, sizeFacet? }
+     */
+    router.post('/claim-groups', async (req, res) => {
+        const result = await api.claimGroups({
+            query: req.body?.query,
+            limit: req.body?.limit,
+            durationMinutes: req.body?.durationMinutes,
+            sizeFacet: req.body?.sizeFacet,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/claim-by-facets
+     * Batch-claim individual rows (FOR UPDATE SKIP LOCKED), assigned to the caller.
+     * Body: { query: FacetQuery, limit?, durationMinutes?, allOrNone? }
+     */
+    router.post('/claim-by-facets', async (req, res) => {
+        const result = await api.claimByFacets({
+            query: req.body?.query,
+            limit: req.body?.limit,
+            durationMinutes: req.body?.durationMinutes,
+            allOrNone: req.body?.allOrNone,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+}

package/build/routes/escalations/index.js

@@ -6,6 +6,7 @@ const bulk_1 = require("./bulk");
 const metadata_1 = require("./metadata");
 const single_1 = require("./single");
 const resolve_1 = require("./resolve");
+const facets_1 = require("./facets");
 const router = (0, express_1.Router)();
 // Registration order matters: literal paths before parameterized /:id routes.
 // GET /, /available, /types, /stats
@@ -15,6 +16,8 @@ const router = (0, express_1.Router)();
 (0, bulk_1.registerBulkRoutes)(router);
 // GET /by-metadata, POST /claim-by-metadata, POST /resolve-by-metadata
 (0, metadata_1.registerMetadataRoutes)(router);
+// POST /search-by-facets, /claim-groups, /claim-by-facets
+(0, facets_1.registerFacetRoutes)(router);
 // PATCH /:id/escalate, GET /by-workflow/:workflowId,
 // GET /:id, POST /:id/claim, POST /:id/release
 (0, single_1.registerSingleRoutes)(router);

package/build/routes/escalations/list.js

@@ -35,6 +35,21 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerListRoutes = registerListRoutes;
 const api = __importStar(require("../../api/escalations"));
+/**
+ * Parse a JSON-encoded query param (facets/block/range/exists/orderBy/roles) so the
+ * full faceted query rides on a GET URL — keeps the dashboard's copy-URL/curl path
+ * reproducible. Returns undefined on absent/invalid JSON (never throws to the caller).
+ */
+function jsonParam(v) {
+    if (typeof v !== 'string' || !v)
+        return undefined;
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return undefined;
+    }
+}
 function registerListRoutes(router) {
     /**
      * POST /api/escalations
@@ -55,6 +70,13 @@ function registerListRoutes(router) {
             envelope: req.body?.envelope,
             metadata: req.body?.metadata,
             escalation_payload: req.body?.escalation_payload,
+            // Workflow-linkage (optional): an advert for a running workflow.
+            origin_id: req.body?.origin_id,
+            parent_id: req.body?.parent_id,
+            task_id: req.body?.task_id,
+            workflow_id: req.body?.workflow_id,
+            task_queue: req.body?.task_queue,
+            workflow_type: req.body?.workflow_type,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
@@ -77,6 +99,14 @@ function registerListRoutes(router) {
             sort_by: req.query.sort_by,
             order: req.query.order,
             search: req.query.search,
+            // Faceted query elements (JSON-encoded on the URL).
+            roles: jsonParam(req.query.roles),
+            facets: jsonParam(req.query.facets),
+            block: jsonParam(req.query.block),
+            range: jsonParam(req.query.range),
+            exists: jsonParam(req.query.exists),
+            orderBy: jsonParam(req.query.orderBy),
+            available: req.query.available != null ? req.query.available === 'true' : undefined,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
@@ -96,6 +126,13 @@ function registerListRoutes(router) {
             sort_by: req.query.sort_by,
             order: req.query.order,
             search: req.query.search,
+            // Faceted query elements (JSON-encoded on the URL).
+            roles: jsonParam(req.query.roles),
+            facets: jsonParam(req.query.facets),
+            block: jsonParam(req.query.block),
+            range: jsonParam(req.query.range),
+            exists: jsonParam(req.query.exists),
+            orderBy: jsonParam(req.query.orderBy),
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
@@ -107,6 +144,15 @@ function registerListRoutes(router) {
         const result = await api.listDistinctTypes();
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    /**
+     * GET /api/escalations/facet-keys
+     * Distinct top-level metadata facet keys visible to the caller (role-scoped).
+     * Powers the faceted-query UI's key autocomplete.
+     */
+    router.get('/facet-keys', async (req, res) => {
+        const result = await api.listFacetKeys(undefined, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * GET /api/escalations/stats
      * Aggregated escalation statistics.

package/build/routes/escalations/resolve.js

@@ -42,10 +42,28 @@ function registerResolveRoutes(router) {
      * waiting workflow in place. For webhook callers that know the deterministic
      * signal id. Literal single-segment path — registered before /:id/resolve so
      * it is never shadowed by the parameterized route.
-     * Body: { signalKey: string, resolverPayload: Record<string, any> }
+     * Body: { signalKey: string, resolverPayload: Record<string, any>, metadata?: Record<string, any> }
      */
     router.post('/resolve-by-signal-key', async (req, res) => {
-        const result = await api.resolveBySignalKey({ signalKey: req.body?.signalKey, resolverPayload: req.body?.resolverPayload }, req.auth);
+        const result = await api.resolveBySignalKey({
+            signalKey: req.body?.signalKey,
+            resolverPayload: req.body?.resolverPayload,
+            metadata: req.body?.metadata,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/resolve-by-ids
+     * Resolve a SET of escalations by id in one guarded statement (set-based sibling of
+     * /:id/resolve). RBAC: scoped callers may only resolve rows whose role they hold.
+     * Body: { ids: string[], resolverPayload: Record<string, any>, metadata?: Record<string, any> }
+     */
+    router.post('/resolve-by-ids', async (req, res) => {
+        const result = await api.resolveByIds({
+            ids: req.body?.ids,
+            resolverPayload: req.body?.resolverPayload,
+            metadata: req.body?.metadata,
+        }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
     /**
@@ -53,10 +71,10 @@ function registerResolveRoutes(router) {
      * Resolve a pending escalation with a human-provided payload. Routes by
      * escalation shape: efficient (signal_key) resumes the job in place; legacy
      * paths signal via routing metadata or re-run the original workflow.
-     * Body: { resolverPayload: Record<string, any> }
+     * Body: { resolverPayload: Record<string, any>, metadata?: Record<string, any> }
      */
     router.post('/:id/resolve', async (req, res) => {
-        const result = await api.resolveEscalation({ id: req.params.id, resolverPayload: req.body?.resolverPayload }, req.auth);
+        const result = await api.resolveEscalation({ id: req.params.id, resolverPayload: req.body?.resolverPayload, metadata: req.body?.metadata }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
 }