@hotmeshio/long-tail 0.5.12 → 0.6.2

package/build/services/user/scope.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = void 0;
+exports.isValidReadScope = isValidReadScope;
+exports.isValidWriteScope = isValidWriteScope;
+exports.isValidScopePair = isValidScopePair;
+exports.effectiveScope = effectiveScope;
+// ─── Role scope: the work-surface axes for an open-role membership ───────────
+//
+// A membership's `type` (member/admin/superadmin) is the management/global tier.
+// Orthogonal to it, a member also carries two scope axes that gate the four task
+// queue verbs:
+//
+//   read_scope  (self | all)        → governs SEARCH (which items appear)
+//   write_scope (none | self | all) → governs CLAIM / ACK / DELETE (which items
+//                                      the user may act on)
+//
+// `self` = items 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 (enforced in the DB by chk_lt_user_roles_scope). admin/superadmin
+// ignore scope and always operate on all.
+exports.READ_SCOPES = ['self', 'all'];
+exports.WRITE_SCOPES = ['none', 'self', 'all'];
+/** Defaults preserve legacy `member` behavior (full role worker). */
+exports.DEFAULT_READ_SCOPE = 'all';
+exports.DEFAULT_WRITE_SCOPE = 'all';
+function isValidReadScope(scope) {
+    return exports.READ_SCOPES.includes(scope);
+}
+function isValidWriteScope(scope) {
+    return exports.WRITE_SCOPES.includes(scope);
+}
+/**
+ * Is (read, write) a valid point in the lattice? Enforces write ⊆ read:
+ * write='all' requires read='all'. (write='self'/'none' allowed under read='self'.)
+ */
+function isValidScopePair(read, write) {
+    return !(write === 'all' && read === 'self');
+}
+/**
+ * Resolve the scope a membership actually grants. The management tier
+ * (admin/superadmin) short-circuits both axes to `all` — those users always
+ * search and act on the whole role queue regardless of stored scope columns.
+ */
+function effectiveScope(type, read, write) {
+    if (type === 'admin' || type === 'superadmin') {
+        return { read: 'all', write: 'all' };
+    }
+    return { read, write };
+}

package/build/services/user/seed-admin.js

@@ -20,23 +20,40 @@ async function seedAdmin(input) {
     catch { /* ON CONFLICT DO NOTHING */ }
     const existing = await (0, crud_1.getUserByExternalId)(externalId);
     if (existing) {
-        // Ensure existing user has the superadmin role
-        const roles = await (0, roles_1.getUserRoles)(existing.id);
-        const hasSuperadmin = roles.some((r) => r.role === 'superadmin' && r.type === 'superadmin');
-        if (!hasSuperadmin) {
-            await (0, roles_1.addUserRole)(existing.id, 'superadmin', 'superadmin');
-            logger_1.loggerRegistry.info(`[seed-admin] granted superadmin role to ${externalId}`);
+        return ensureSuperadmin(existing.id, externalId);
+    }
+    // Create. Concurrent container startups can both reach here; external_id UNIQUE
+    // is the arbiter — on the loser's 23505, adopt the winner's row instead of
+    // crashing the boot sequence.
+    try {
+        const user = await (0, crud_1.createUser)({
+            external_id: externalId,
+            email: email || undefined,
+            display_name: displayName || externalId,
+            password: password || undefined,
+            roles: [{ role: 'superadmin', type: 'superadmin' }],
+        });
+        logger_1.loggerRegistry.info(`[seed-admin] created superadmin user: ${externalId}`);
+        return user.id;
+    }
+    catch (err) {
+        if (err?.code === '23505') {
+            const winner = await (0, crud_1.getUserByExternalId)(externalId);
+            if (winner) {
+                return ensureSuperadmin(winner.id, externalId);
+            }
         }
-        logger_1.loggerRegistry.info(`[seed-admin] ${externalId} already exists, skipping creation`);
-        return existing.id;
+        throw err;
+    }
+}
+/** Ensure an existing user carries the superadmin role; returns its id. */
+async function ensureSuperadmin(userId, externalId) {
+    const roles = await (0, roles_1.getUserRoles)(userId);
+    const hasSuperadmin = roles.some((r) => r.role === 'superadmin' && r.type === 'superadmin');
+    if (!hasSuperadmin) {
+        await (0, roles_1.addUserRole)(userId, 'superadmin', 'superadmin');
+        logger_1.loggerRegistry.info(`[seed-admin] granted superadmin role to ${externalId}`);
     }
-    const user = await (0, crud_1.createUser)({
-        external_id: externalId,
-        email: email || undefined,
-        display_name: displayName || externalId,
-        password: password || undefined,
-        roles: [{ role: 'superadmin', type: 'superadmin' }],
-    });
-    logger_1.loggerRegistry.info(`[seed-admin] created superadmin user: ${externalId}`);
-    return user.id;
+    logger_1.loggerRegistry.info(`[seed-admin] ${externalId} already exists, skipping creation`);
+    return userId;
 }

package/build/services/user/sql.d.ts

@@ -1,24 +1,35 @@
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 export declare const ENSURE_ROLE_EXISTS = "INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING";
 /** Fetch roles for a single user, ordered by creation time. */
-export declare const GET_ROLES_BY_USER_ID = "SELECT role, type, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at";
+export declare const GET_ROLES_BY_USER_ID = "SELECT role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at";
 /** Fetch a user row by external_id. */
 export declare const GET_USER_BY_EXTERNAL_ID = "SELECT * FROM lt_users WHERE external_id = $1";
-export declare const INSERT_USER = "INSERT INTO lt_users (external_id, email, display_name, status, metadata, password_hash, oauth_provider, oauth_provider_id)\n   VALUES ($1, $2, $3, $4, $5, $6, $7, $8)\n   RETURNING *";
+/**
+ * Create a user and its role assignments in ONE atomic statement. The user row,
+ * the lt_roles FK targets ($9 = role names), and the lt_user_roles links
+ * ($9 names × $10 types × $11 read_scope × $12 write_scope) all commit together —
+ * a failure can never leave a half-provisioned user with a partial role set, and
+ * there is no per-role N+1. All four are passed as parallel text[] arrays (empty
+ * arrays → no roles). Postgres checks the lt_user_roles→lt_roles FK at statement
+ * end, after the sibling role-ensure CTE has run, so brand-new roles are valid
+ * FK targets.
+ */
+export declare const CREATE_USER_WITH_ROLES = "WITH new_user AS (\n     INSERT INTO lt_users (external_id, email, display_name, status, metadata, password_hash, oauth_provider, oauth_provider_id)\n     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)\n     RETURNING *\n   ), ensured_roles AS (\n     INSERT INTO lt_roles (role)\n     SELECT DISTINCT unnest($9::text[])\n     ON CONFLICT DO NOTHING\n   ), assigned_roles AS (\n     INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope)\n     SELECT (SELECT id FROM new_user), x.role, x.type, x.read_scope, x.write_scope\n     FROM unnest($9::text[], $10::text[], $11::text[], $12::text[]) AS x(role, type, read_scope, write_scope)\n     ON CONFLICT DO NOTHING\n   )\n   SELECT * FROM new_user";
 export declare const GET_USER_BY_EMAIL = "SELECT * FROM lt_users WHERE email = $1 LIMIT 1";
-export declare const INSERT_USER_ROLE_IGNORE = "INSERT INTO lt_user_roles (user_id, role, type) VALUES ($1, $2, $3)\n   ON CONFLICT DO NOTHING";
 export declare const GET_USER_BY_ID = "SELECT * FROM lt_users WHERE id = $1";
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 export declare const VERIFY_USER_BY_ID = "SELECT id FROM lt_users WHERE id = $1 LIMIT 1";
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
-export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
+export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type, r.read_scope, r.write_scope\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
 export declare const DELETE_USER_BY_ID = "DELETE FROM lt_users WHERE id = $1";
 /** Batch-load roles for many users (avoids N+1). */
-export declare const GET_ROLES_BY_USER_IDS = "SELECT user_id, role, type, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at";
-/** Upsert a user–role assignment, promoting the type if the row exists. */
-export declare const UPSERT_USER_ROLE = "INSERT INTO lt_user_roles (user_id, role, type) VALUES ($1, $2, $3)\n   ON CONFLICT (user_id, role) DO UPDATE SET type = EXCLUDED.type\n   RETURNING role, type, created_at";
+export declare const GET_ROLES_BY_USER_IDS = "SELECT user_id, role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at";
+/** Upsert a user–role assignment, promoting the type/scope if the row exists. */
+export declare const UPSERT_USER_ROLE = "INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)\n   ON CONFLICT (user_id, role) DO UPDATE SET\n     type = EXCLUDED.type,\n     read_scope = EXCLUDED.read_scope,\n     write_scope = EXCLUDED.write_scope\n   RETURNING role, type, read_scope, write_scope, created_at";
 export declare const DELETE_USER_ROLE = "DELETE FROM lt_user_roles WHERE user_id = $1 AND role = $2";
 export declare const HAS_ROLE = "SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1";
 export declare const HAS_ROLE_TYPE = "SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND type = $2 LIMIT 1";
+/** Fetch the management tier + scope for one (user, role) — used for write enforcement. */
+export declare const GET_ROLE_SCOPE = "SELECT type, read_scope, write_scope FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1";
 /** Check if a user is an admin (or superadmin) of a specific role group. */
 export declare const IS_GROUP_ADMIN = "SELECT 1 FROM lt_user_roles\n   WHERE user_id = $1\n     AND (\n       (role = $2 AND type IN ('admin', 'superadmin'))\n       OR type = 'superadmin'\n     )\n   LIMIT 1";

package/build/services/user/sql.js

@@ -1,26 +1,46 @@
 "use strict";
 // ─── Shared queries (used by multiple modules) ──────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IS_GROUP_ADMIN = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USER_BY_ID = exports.INSERT_USER_ROLE_IGNORE = exports.GET_USER_BY_EMAIL = exports.INSERT_USER = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
+exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 exports.ENSURE_ROLE_EXISTS = 'INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING';
 /** Fetch roles for a single user, ordered by creation time. */
-exports.GET_ROLES_BY_USER_ID = 'SELECT role, type, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at';
+exports.GET_ROLES_BY_USER_ID = 'SELECT role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at';
 /** Fetch a user row by external_id. */
 exports.GET_USER_BY_EXTERNAL_ID = 'SELECT * FROM lt_users WHERE external_id = $1';
 // ─── User CRUD ───────────────────────────────────────────────────────────────
-exports.INSERT_USER = `INSERT INTO lt_users (external_id, email, display_name, status, metadata, password_hash, oauth_provider, oauth_provider_id)
-   VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
-   RETURNING *`;
+/**
+ * Create a user and its role assignments in ONE atomic statement. The user row,
+ * the lt_roles FK targets ($9 = role names), and the lt_user_roles links
+ * ($9 names × $10 types × $11 read_scope × $12 write_scope) all commit together —
+ * a failure can never leave a half-provisioned user with a partial role set, and
+ * there is no per-role N+1. All four are passed as parallel text[] arrays (empty
+ * arrays → no roles). Postgres checks the lt_user_roles→lt_roles FK at statement
+ * end, after the sibling role-ensure CTE has run, so brand-new roles are valid
+ * FK targets.
+ */
+exports.CREATE_USER_WITH_ROLES = `WITH new_user AS (
+     INSERT INTO lt_users (external_id, email, display_name, status, metadata, password_hash, oauth_provider, oauth_provider_id)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+     RETURNING *
+   ), ensured_roles AS (
+     INSERT INTO lt_roles (role)
+     SELECT DISTINCT unnest($9::text[])
+     ON CONFLICT DO NOTHING
+   ), assigned_roles AS (
+     INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope)
+     SELECT (SELECT id FROM new_user), x.role, x.type, x.read_scope, x.write_scope
+     FROM unnest($9::text[], $10::text[], $11::text[], $12::text[]) AS x(role, type, read_scope, write_scope)
+     ON CONFLICT DO NOTHING
+   )
+   SELECT * FROM new_user`;
 exports.GET_USER_BY_EMAIL = `SELECT * FROM lt_users WHERE email = $1 LIMIT 1`;
-exports.INSERT_USER_ROLE_IGNORE = `INSERT INTO lt_user_roles (user_id, role, type) VALUES ($1, $2, $3)
-   ON CONFLICT DO NOTHING`;
 exports.GET_USER_BY_ID = 'SELECT * FROM lt_users WHERE id = $1';
 /** Check if a user exists by id. Lightweight — returns only the id column. */
 exports.VERIFY_USER_BY_ID = 'SELECT id FROM lt_users WHERE id = $1 LIMIT 1';
 /** Fetch user + roles in a single query. Returns one row per role (or one row with nulls if no roles). */
 exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,
-          r.role, r.type AS role_type
+          r.role, r.type AS role_type, r.read_scope, r.write_scope
    FROM lt_users u
    LEFT JOIN lt_user_roles r ON r.user_id = u.id
    WHERE u.external_id = $1
@@ -28,14 +48,19 @@ exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.sta
 exports.DELETE_USER_BY_ID = 'DELETE FROM lt_users WHERE id = $1';
 // ─── Role management ─────────────────────────────────────────────────────────
 /** Batch-load roles for many users (avoids N+1). */
-exports.GET_ROLES_BY_USER_IDS = 'SELECT user_id, role, type, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at';
-/** Upsert a user–role assignment, promoting the type if the row exists. */
-exports.UPSERT_USER_ROLE = `INSERT INTO lt_user_roles (user_id, role, type) VALUES ($1, $2, $3)
-   ON CONFLICT (user_id, role) DO UPDATE SET type = EXCLUDED.type
-   RETURNING role, type, created_at`;
+exports.GET_ROLES_BY_USER_IDS = 'SELECT user_id, role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at';
+/** Upsert a user–role assignment, promoting the type/scope if the row exists. */
+exports.UPSERT_USER_ROLE = `INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)
+   ON CONFLICT (user_id, role) DO UPDATE SET
+     type = EXCLUDED.type,
+     read_scope = EXCLUDED.read_scope,
+     write_scope = EXCLUDED.write_scope
+   RETURNING role, type, read_scope, write_scope, created_at`;
 exports.DELETE_USER_ROLE = 'DELETE FROM lt_user_roles WHERE user_id = $1 AND role = $2';
 exports.HAS_ROLE = 'SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1';
 exports.HAS_ROLE_TYPE = 'SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND type = $2 LIMIT 1';
+/** Fetch the management tier + scope for one (user, role) — used for write enforcement. */
+exports.GET_ROLE_SCOPE = 'SELECT type, read_scope, write_scope FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1';
 // ─── RBAC ────────────────────────────────────────────────────────────────────
 /** Check if a user is an admin (or superadmin) of a specific role group. */
 exports.IS_GROUP_ADMIN = `SELECT 1 FROM lt_user_roles

package/build/services/user/sso-provision.js

@@ -18,34 +18,51 @@ async function ssoProvision(identity, ssoConfig) {
     const ltRoles = resolveRoles(identity.roles || [], defaultRoleType, ssoConfig.roleMap);
     const existing = await (0, crud_1.getUserByExternalId)(identity.externalId);
     if (existing) {
-        // Sync roles: ensure all resolved roles exist on the user
-        const currentRoles = await (0, roles_1.getUserRoles)(existing.id);
-        for (const lr of ltRoles) {
-            const has = currentRoles.some((r) => r.role === lr.role);
-            if (!has) {
-                await (0, roles_1.addUserRole)(existing.id, lr.role, lr.type);
-            }
-        }
-        const updatedRoles = await (0, roles_1.getUserRoles)(existing.id);
+        return syncExistingUser(existing.id, ltRoles);
+    }
+    // Create new user. Two concurrent first-logins for the same identity can both
+    // pass the existence check above; external_id UNIQUE is the arbiter. The loser's
+    // insert raises 23505 — adopt the winner's committed row and sync roles rather
+    // than failing the login.
+    try {
+        const user = await (0, crud_1.createUser)({
+            external_id: identity.externalId,
+            email: identity.email || undefined,
+            display_name: identity.displayName || identity.externalId,
+            roles: ltRoles.map((r) => ({ role: r.role, type: r.type })),
+            metadata: identity.metadata,
+        });
+        logger_1.loggerRegistry.info(`[lt-sso] provisioned user: ${identity.externalId} → ${user.id}`);
         return {
-            userId: existing.id,
-            roles: updatedRoles.map((r) => ({ role: r.role, type: r.type })),
-            created: false,
+            userId: user.id,
+            roles: (user.roles || []).map((r) => ({ role: r.role, type: r.type })),
+            created: true,
         };
     }
-    // Create new user
-    const user = await (0, crud_1.createUser)({
-        external_id: identity.externalId,
-        email: identity.email || undefined,
-        display_name: identity.displayName || identity.externalId,
-        roles: ltRoles.map((r) => ({ role: r.role, type: r.type })),
-        metadata: identity.metadata,
-    });
-    logger_1.loggerRegistry.info(`[lt-sso] provisioned user: ${identity.externalId} → ${user.id}`);
+    catch (err) {
+        if (err?.code === '23505') {
+            const winner = await (0, crud_1.getUserByExternalId)(identity.externalId);
+            if (winner) {
+                return syncExistingUser(winner.id, ltRoles);
+            }
+        }
+        throw err;
+    }
+}
+/** Ensure all resolved roles exist on an already-provisioned user. */
+async function syncExistingUser(userId, ltRoles) {
+    const currentRoles = await (0, roles_1.getUserRoles)(userId);
+    for (const lr of ltRoles) {
+        const has = currentRoles.some((r) => r.role === lr.role);
+        if (!has) {
+            await (0, roles_1.addUserRole)(userId, lr.role, lr.type);
+        }
+    }
+    const updatedRoles = await (0, roles_1.getUserRoles)(userId);
     return {
-        userId: user.id,
-        roles: (user.roles || []).map((r) => ({ role: r.role, type: r.type })),
-        created: true,
+        userId,
+        roles: updatedRoles.map((r) => ({ role: r.role, type: r.type })),
+        created: false,
     };
 }
 function resolveRoles(hostRoles, defaultRoleType, roleMap) {

package/build/services/user/types.d.ts

@@ -1,5 +1,12 @@
-import type { LTRoleType, LTUserStatus } from '../../types';
+import type { LTReadScope, LTRoleType, LTUserStatus, LTWriteScope } from '../../types';
 export declare const VALID_ROLE_TYPES: LTRoleType[];
+/** A role grant on user create: management tier + optional work-surface scope. */
+export interface RoleGrantInput {
+    role: string;
+    type: LTRoleType;
+    read_scope?: LTReadScope;
+    write_scope?: LTWriteScope;
+}
 export interface CreateUserInput {
     external_id: string;
     email?: string;
@@ -7,10 +14,7 @@ export interface CreateUserInput {
     password?: string;
     status?: LTUserStatus;
     metadata?: Record<string, any>;
-    roles?: {
-        role: string;
-        type: LTRoleType;
-    }[];
+    roles?: RoleGrantInput[];
     /** OAuth identity link (set during OAuth auto-provisioning). */
     oauth_provider?: string;
     oauth_provider_id?: string;

package/build/system/mcp-servers/admin/escalations.js

@@ -81,6 +81,9 @@ function registerEscalationTools(server) {
             'assigned_to, priority), free-text `search`, and sorting. `search` matches ' +
             'across description, type/subtype, role, workflow/origin id, and metadata values ' +
             '(e.g. a correlation key like an order id) server-side over the full result set. ' +
+            'Also supports FACETED metadata query — `facets` (metadata @> containment), `block` ' +
+            '(exclusion), `range` (numeric), `exists` (key present), `roles`, `available`, and ' +
+            '`orderBy` (incl. metadata.<key>) — all role-scoped and run in SQL. ' +
             'Returns full records including metadata, workflow linkage, assignment, and signal_key.',
         inputSchema: schemas_1.findEscalationsSchema,
     }, async (args) => {
@@ -96,6 +99,14 @@ function registerEscalationTools(server) {
             offset: args.offset,
             sort_by: args.sort_by,
             order: args.order,
+            // Faceted metadata query (composes with role-scope in SQL).
+            roles: args.roles,
+            facets: args.facets,
+            block: args.block,
+            range: args.range,
+            exists: args.exists,
+            available: args.available,
+            orderBy: args.orderBy,
         }, await systemAuth());
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
@@ -220,6 +231,60 @@ function registerEscalationTools(server) {
         }
         return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
     });
+    // mirrors POST /api/escalations/resolve-by-ids
+    server.registerTool('resolve_by_ids', {
+        title: 'Resolve by IDs',
+        description: 'Resolve a SET of escalations by id in one guarded statement. RBAC-scoped: ' +
+            'callers may only resolve rows whose role they hold. For bookkeeping rows woken ' +
+            'collectively (no per-row signal delivery).',
+        inputSchema: schemas_1.resolveByIdsSchema,
+    }, async (args) => {
+        const result = await escalationApi.resolveByIds({ ids: args.ids, resolverPayload: args.resolverPayload, metadata: args.metadata }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/search-by-facets
+    server.registerTool('search_by_facets', {
+        title: 'Search by Facets',
+        description: 'Faceted search over a pond, scoped to the caller\'s role. Filter by status, ' +
+            'availability, and metadata facets; sort by columns; page with limit/offset.',
+        inputSchema: schemas_1.searchByFacetsSchema,
+    }, async (args) => {
+        const result = await escalationApi.searchByFacets(args, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/claim-groups
+    server.registerTool('claim_groups', {
+        title: 'Claim Groups',
+        description: 'Batch-claim complete origin groups (orders) in priority order over a pond, ' +
+            'assigned to the calling principal. RBAC-scoped to the pond role.',
+        inputSchema: schemas_1.claimGroupsSchema,
+    }, async (args) => {
+        const result = await escalationApi.claimGroups({ query: args.query, limit: args.limit, durationMinutes: args.durationMinutes, sizeFacet: args.sizeFacet }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/claim-by-facets
+    server.registerTool('claim_by_facets', {
+        title: 'Claim by Facets',
+        description: 'Batch-claim individual rows matching a facet query (FOR UPDATE SKIP LOCKED), ' +
+            'assigned to the calling principal. With allOrNone, commits only the full set. ' +
+            'RBAC-scoped to the pond role.',
+        inputSchema: schemas_1.claimByFacetsSchema,
+    }, async (args) => {
+        const result = await escalationApi.claimByFacets({ query: args.query, limit: args.limit, durationMinutes: args.durationMinutes, allOrNone: args.allOrNone }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
     // mirrors PATCH /api/escalations/:id/escalate
     server.registerTool('escalate_escalation', {
         title: 'Escalate Escalation',