@hotmeshio/long-tail 0.14.1 → 0.14.4

package/build/api/escalations/bulk.d.ts

@@ -49,6 +49,9 @@ export declare function bulkClaim(input: {
  * @param input.query — `{ role, facets? }` selector (query form)
  * @param input.targetUserId — user to assign to
  * @param input.durationMinutes — assignment duration (default: 30)
+ * @param input.reassign — also take over rows under a LIVE claim (ids form
+ *   only; requires admin/superadmin). Default false: live claims are skipped
+ *   and counted in `skipped`.
  * @param auth — authenticated user context
  * @returns `{ status: 200, data: { assigned, skipped } }`
  */
@@ -60,6 +63,21 @@ export declare function bulkAssign(input: {
     };
     targetUserId: string;
     durationMinutes?: number;
+    reassign?: boolean;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Return claimed escalations to the available pool — the admin override of
+ * someone else's live claim (self-return stays the release verb). One
+ * guarded statement; unclaimed and terminal rows are skipped. Publishes a
+ * `released` event per returned row with the acting admin in the delta.
+ *
+ * RBAC: admin/superadmin (global escalation access) only.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @returns `{ status: 200, data: { unassigned, skipped } }`
+ */
+export declare function bulkUnassign(input: {
+    ids?: string[];
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * Route multiple escalations to a different role.

package/build/api/escalations/bulk.js

@@ -37,6 +37,7 @@ exports.releaseExpiredClaims = releaseExpiredClaims;
 exports.updatePriority = updatePriority;
 exports.bulkClaim = bulkClaim;
 exports.bulkAssign = bulkAssign;
+exports.bulkUnassign = bulkUnassign;
 exports.bulkEscalate = bulkEscalate;
 exports.bulkTriage = bulkTriage;
 const escalationService = __importStar(require("../../services/escalation"));
@@ -133,12 +134,15 @@ async function bulkClaim(input, auth) {
  * @param input.query — `{ role, facets? }` selector (query form)
  * @param input.targetUserId — user to assign to
  * @param input.durationMinutes — assignment duration (default: 30)
+ * @param input.reassign — also take over rows under a LIVE claim (ids form
+ *   only; requires admin/superadmin). Default false: live claims are skipped
+ *   and counted in `skipped`.
  * @param auth — authenticated user context
  * @returns `{ status: 200, data: { assigned, skipped } }`
  */
 async function bulkAssign(input, auth) {
     try {
-        const { ids, query, targetUserId, durationMinutes } = input;
+        const { ids, query, targetUserId, durationMinutes, reassign } = input;
         if (!targetUserId || typeof targetUserId !== 'string') {
             return { status: 400, error: 'targetUserId is required' };
         }
@@ -147,6 +151,14 @@ async function bulkAssign(input, auth) {
         if (hasIds === hasQuery) {
             return { status: 400, error: 'provide exactly one of ids or query' };
         }
+        if (reassign === true && hasQuery) {
+            return { status: 400, error: 'reassign requires the ids form' };
+        }
+        // Taking over a LIVE claim is a management override — stricter than
+        // pre-assigning pool rows, which role-scoped admins may do.
+        if (reassign === true && !(await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId))) {
+            return { status: 403, error: 'Forbidden: reassign requires admin access' };
+        }
         if (hasQuery) {
             if (!query.role || typeof query.role !== 'string') {
                 return { status: 400, error: 'query.role is required' };
@@ -186,6 +198,14 @@ async function bulkAssign(input, auth) {
                 }
             }
         }
+        if (reassign === true) {
+            const result = await escalationService.bulkReassignEscalations(ids, targetUserId, durationMinutes ?? 30);
+            if (result.assigned > 0) {
+                const priorById = new Map(result.changes.map((c) => [c.id, c.prior_assignee]));
+                (0, helpers_1.publishBulkClaimEvents)(result.changes.map((c) => c.id), targetUserId, undefined, priorById);
+            }
+            return { status: 200, data: { assigned: result.assigned, skipped: result.skipped } };
+        }
         const result = await escalationService.bulkAssignEscalations(ids, targetUserId, durationMinutes ?? 30);
         if (result.assigned > 0)
             (0, helpers_1.publishBulkClaimEvents)(ids, targetUserId);
@@ -195,6 +215,34 @@ async function bulkAssign(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Return claimed escalations to the available pool — the admin override of
+ * someone else's live claim (self-return stays the release verb). One
+ * guarded statement; unclaimed and terminal rows are skipped. Publishes a
+ * `released` event per returned row with the acting admin in the delta.
+ *
+ * RBAC: admin/superadmin (global escalation access) only.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @returns `{ status: 200, data: { unassigned, skipped } }`
+ */
+async function bulkUnassign(input, auth) {
+    try {
+        if (!(0, helpers_1.validateIds)(input.ids ?? [])) {
+            return { status: 400, error: 'ids must be a non-empty array' };
+        }
+        if (!(await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId))) {
+            return { status: 403, error: 'Forbidden: unassign requires admin access' };
+        }
+        const result = await escalationService.bulkUnassignEscalations(input.ids);
+        if (result.unassigned > 0)
+            (0, helpers_1.publishBulkReleaseEvents)(result.changes, auth.userId);
+        return { status: 200, data: { unassigned: result.unassigned, skipped: result.skipped } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 /**
  * Route multiple escalations to a different role.
  *

package/build/api/escalations/helpers.d.ts

@@ -150,4 +150,14 @@ export declare function publishBulkReassignEvents(beforeRows: Array<{
     id: string;
     role: string;
 }>, targetRole: string): void;
-export declare function publishBulkClaimEvents(ids: string[], assignedTo: string, knownRole?: string): void;
+export declare function publishBulkClaimEvents(ids: string[], assignedTo: string, knownRole?: string, priorById?: Map<string, string | null>): void;
+/**
+ * Per-row released events for an admin unassign — the row returns to the
+ * pool under the same verb a self-release produces, with the acting admin in
+ * the delta.
+ */
+export declare function publishBulkReleaseEvents(changes: Array<{
+    id: string;
+    role: string;
+    prior_assignee: string | null;
+}>, releasedBy: string): void;

package/build/api/escalations/helpers.js

@@ -46,6 +46,7 @@ exports.resolveAssignee = resolveAssignee;
 exports.ensureRoleMembership = ensureRoleMembership;
 exports.publishBulkReassignEvents = publishBulkReassignEvents;
 exports.publishBulkClaimEvents = publishBulkClaimEvents;
+exports.publishBulkReleaseEvents = publishBulkReleaseEvents;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
 const publish_1 = require("../../lib/events/publish");
@@ -283,10 +284,11 @@ function publishBulkReassignEvents(beforeRows, targetRole) {
         }
     }
 }
-function publishBulkClaimEvents(ids, assignedTo, knownRole) {
+function publishBulkClaimEvents(ids, assignedTo, knownRole, priorById) {
     // The claimed subject carries each row's role token. Query-form callers
     // already know the single role; id-form callers resolve roles with one
-    // indexed read. Fire-and-forget, like every event publish.
+    // indexed read. Fire-and-forget, like every event publish. `priorById`
+    // (reassign) adds the displaced assignee to each row's delta.
     void (async () => {
         const roleById = new Map();
         if (knownRole) {
@@ -299,6 +301,7 @@ function publishBulkClaimEvents(ids, assignedTo, knownRole) {
                 roleById.set(row.id, row.role);
         }
         for (const id of ids) {
+            const prior = priorById?.get(id);
             (0, publish_1.publishEscalationEvent)({
                 type: 'escalation.claimed',
                 source: 'api',
@@ -310,8 +313,32 @@ function publishBulkClaimEvents(ids, assignedTo, knownRole) {
                 status: 'claimed',
                 // Bulk exception to the one-shape convention (see lib/events/escalation-wire.ts):
                 // delta + `bulk: true`, no per-row fetch. Subscribers fetch by id for detail.
-                data: { assigned_to: assignedTo, bulk: true },
+                data: { assigned_to: assignedTo, bulk: true, ...(prior ? { reassigned_from: prior } : {}) },
             });
         }
     })().catch(() => { });
 }
+/**
+ * Per-row released events for an admin unassign — the row returns to the
+ * pool under the same verb a self-release produces, with the acting admin in
+ * the delta.
+ */
+function publishBulkReleaseEvents(changes, releasedBy) {
+    for (const change of changes) {
+        void (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.released',
+            source: 'api',
+            workflowId: '',
+            workflowName: '',
+            taskQueue: '',
+            escalationId: change.id,
+            role: change.role,
+            status: 'released',
+            data: {
+                released_by: releasedBy,
+                bulk: true,
+                ...(change.prior_assignee ? { unassigned_from: change.prior_assignee } : {}),
+            },
+        });
+    }
+}

package/build/api/escalations/index.d.ts

@@ -2,7 +2,7 @@ export { createEscalation } from './create';
 export { listEscalations, listAvailableEscalations, listDistinctTypes, listFacetKeys, getEscalationStats, getStationMetrics } from './list';
 export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './single';
 export { claimEscalation, releaseEscalation } from './claim';
-export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkEscalate, bulkTriage } from './bulk';
+export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkUnassign, bulkEscalate, bulkTriage } from './bulk';
 export { resolveEscalation, resolveBySignalKey, resolveByIds, resolveAllOrNone } from './resolve';
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -22,6 +22,7 @@ Object.defineProperty(exports, "releaseExpiredClaims", { enumerable: true, get:
 Object.defineProperty(exports, "updatePriority", { enumerable: true, get: function () { return bulk_1.updatePriority; } });
 Object.defineProperty(exports, "bulkClaim", { enumerable: true, get: function () { return bulk_1.bulkClaim; } });
 Object.defineProperty(exports, "bulkAssign", { enumerable: true, get: function () { return bulk_1.bulkAssign; } });
+Object.defineProperty(exports, "bulkUnassign", { enumerable: true, get: function () { return bulk_1.bulkUnassign; } });
 Object.defineProperty(exports, "bulkEscalate", { enumerable: true, get: function () { return bulk_1.bulkEscalate; } });
 Object.defineProperty(exports, "bulkTriage", { enumerable: true, get: function () { return bulk_1.bulkTriage; } });
 var resolve_1 = require("./resolve");

package/build/routes/escalations/bulk.js

@@ -54,9 +54,15 @@ function registerBulkRoutes(router) {
             query: req.body?.query,
             targetUserId: req.body?.targetUserId,
             durationMinutes: req.body?.durationMinutes,
+            // Take over live claims too (ids form; admin/superadmin only).
+            reassign: req.body?.reassign === true,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    router.post('/bulk-unassign', async (req, res) => {
+        const result = await api.bulkUnassign({ ids: req.body?.ids }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     router.patch('/bulk-escalate', async (req, res) => {
         const result = await api.bulkEscalate({ ids: req.body?.ids, targetRole: req.body?.targetRole }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });

package/build/sdk/index.d.ts

@@ -181,6 +181,10 @@ export declare function createClient(options?: LTClientOptions): {
             };
             targetUserId: string;
             durationMinutes?: number;
+            reassign?: boolean;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        bulkUnassign: (input: {
+            ids?: string[];
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         bulkEscalate: (input: {
             ids: string[];

package/build/sdk/index.js

@@ -136,6 +136,7 @@ function createClient(options = {}) {
             updatePriority: bindAuth(escalationsApi.updatePriority, auth),
             bulkClaim: bindAuth(escalationsApi.bulkClaim, auth),
             bulkAssign: bindAuth(escalationsApi.bulkAssign, auth),
+            bulkUnassign: bindAuth(escalationsApi.bulkUnassign, auth),
             bulkEscalate: bindAuth(escalationsApi.bulkEscalate, auth),
             bulkTriage: bindAuth(escalationsApi.bulkTriage, auth),
             findByMetadata: bindAuth(escalationsApi.findByMetadata, auth),

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

@@ -1,4 +1,10 @@
 import type { LTEscalationRecord } from '../../types';
+/** One row touched by a reassign/unassign, with its pre-update assignee. */
+export interface AssignmentChange {
+    id: string;
+    role: string;
+    prior_assignee: string | null;
+}
 /**
  * Bulk claim escalations for a user.
  * Items already claimed by another active user are skipped.
@@ -29,6 +35,27 @@ export declare function bulkAssignEscalationsByQuery(query: {
     assigned: number;
     ids: string[];
 }>;
+/**
+ * Reassign pending rows to a user, INCLUDING rows under a live claim — the
+ * management override plain assign is not (claimMany skips live claims). One
+ * guarded statement; rows not returned were terminal or missing. Each
+ * returned row carries its pre-update assignee for the event.
+ */
+export declare function bulkReassignEscalations(ids: string[], targetUserId: string, durationMinutes?: number): Promise<{
+    assigned: number;
+    skipped: number;
+    changes: AssignmentChange[];
+}>;
+/**
+ * Return pending claimed rows to the available pool (admin override of
+ * someone else's claim — self-return stays the release verb). One guarded
+ * statement; unclaimed and terminal rows are skipped.
+ */
+export declare function bulkUnassignEscalations(ids: string[]): Promise<{
+    unassigned: number;
+    skipped: number;
+    changes: AssignmentChange[];
+}>;
 /**
  * Bulk reassign escalations to a different role.
  * Clears assignment on all affected rows.

package/build/services/escalation/bulk.js

@@ -3,11 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.bulkClaimEscalations = bulkClaimEscalations;
 exports.bulkAssignEscalations = bulkAssignEscalations;
 exports.bulkAssignEscalationsByQuery = bulkAssignEscalationsByQuery;
+exports.bulkReassignEscalations = bulkReassignEscalations;
+exports.bulkUnassignEscalations = bulkUnassignEscalations;
 exports.bulkEscalateToRole = bulkEscalateToRole;
 exports.bulkCancelEscalations = bulkCancelEscalations;
 exports.bulkResolveForTriage = bulkResolveForTriage;
+const db_1 = require("../../lib/db");
 const client_1 = require("./client");
 const map_1 = require("./map");
+const sql_1 = require("./sql");
 /**
  * Bulk claim escalations for a user.
  * Items already claimed by another active user are skipped.
@@ -49,6 +53,41 @@ async function bulkAssignEscalationsByQuery(query, targetUserId, durationMinutes
     });
     return { assigned: claimed, ids: entries.map((e) => e.id) };
 }
+/**
+ * Reassign pending rows to a user, INCLUDING rows under a live claim — the
+ * management override plain assign is not (claimMany skips live claims). One
+ * guarded statement; rows not returned were terminal or missing. Each
+ * returned row carries its pre-update assignee for the event.
+ */
+async function bulkReassignEscalations(ids, targetUserId, durationMinutes = 30) {
+    if (ids.length === 0)
+        return { assigned: 0, skipped: 0, changes: [] };
+    await (0, client_1.ensureEscalationCompatView)();
+    const { rows } = await (0, db_1.getPool)().query(sql_1.BULK_REASSIGN, [ids, targetUserId, durationMinutes]);
+    const changes = rows.map((r) => ({
+        id: r.id,
+        role: r.role,
+        prior_assignee: r.prior_assignee ?? null,
+    }));
+    return { assigned: rows.length, skipped: ids.length - rows.length, changes };
+}
+/**
+ * Return pending claimed rows to the available pool (admin override of
+ * someone else's claim — self-return stays the release verb). One guarded
+ * statement; unclaimed and terminal rows are skipped.
+ */
+async function bulkUnassignEscalations(ids) {
+    if (ids.length === 0)
+        return { unassigned: 0, skipped: 0, changes: [] };
+    await (0, client_1.ensureEscalationCompatView)();
+    const { rows } = await (0, db_1.getPool)().query(sql_1.BULK_UNASSIGN, [ids]);
+    const changes = rows.map((r) => ({
+        id: r.id,
+        role: r.role,
+        prior_assignee: r.prior_assignee ?? null,
+    }));
+    return { unassigned: rows.length, skipped: ids.length - rows.length, changes };
+}
 /**
  * Bulk reassign escalations to a different role.
  * Clears assignment on all affected rows.

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

@@ -8,6 +8,23 @@
  * table. Clears both `assigned_until` and `claim_expires_at`.
  */
 export declare const RELEASE_EXPIRED_CLAIMS = "UPDATE public.hmsh_escalations\nSET assigned_to = NULL,\n    assigned_until = NULL,\n    claimed_at = NULL,\n    claim_expires_at = NULL,\n    updated_at = NOW()\nWHERE status = 'pending'\n  AND assigned_to IS NOT NULL\n  AND assigned_until <= NOW()";
+/**
+ * Reassign: hand pending rows to a user, INCLUDING rows under a live claim —
+ * the management override that plain assign (claimMany, which skips live
+ * claims) deliberately is not. One statement: the CTE reads each row's
+ * pre-update assignee (CTEs share one snapshot), so callers get
+ * prior_assignee for the event with no read-then-write window. An in-flight
+ * resolve by the prior assignee fails its claim assertion once assigned_to
+ * changes.
+ */
+export declare const BULK_REASSIGN = "WITH prior AS (\n  SELECT id, assigned_to FROM public.hmsh_escalations WHERE id = ANY($1::uuid[])\n)\nUPDATE public.hmsh_escalations e\nSET assigned_to = $2,\n    assigned_until = NOW() + ($3::int * interval '1 minute'),\n    claimed_at = NOW(),\n    updated_at = NOW()\nFROM prior\nWHERE e.id = prior.id\n  AND e.status = 'pending'\nRETURNING e.*, prior.assigned_to AS prior_assignee";
+/**
+ * Unassign: return pending claimed rows to the available pool (an admin
+ * override of someone else's claim — self-return stays the release verb).
+ * Clears the same field set as RELEASE_EXPIRED_CLAIMS, without the expiry
+ * predicate.
+ */
+export declare const BULK_UNASSIGN = "WITH prior AS (\n  SELECT id, assigned_to FROM public.hmsh_escalations WHERE id = ANY($1::uuid[])\n)\nUPDATE public.hmsh_escalations e\nSET assigned_to = NULL,\n    assigned_until = NULL,\n    claimed_at = NULL,\n    claim_expires_at = NULL,\n    updated_at = NOW()\nFROM prior\nWHERE e.id = prior.id\n  AND e.status = 'pending'\n  AND e.assigned_to IS NOT NULL\nRETURNING e.*, prior.assigned_to AS prior_assignee";
 /** Count matching the search WHERE (params $1–$13). */
 export declare const COUNT_SEARCH_ESCALATIONS = "SELECT COUNT(*)::int AS total\n  FROM public.lt_escalations\n  WHERE ($1::text IS NULL OR status = $1)\n    AND ($2::text IS NULL OR role = $2)\n    AND (\n         ($3::text[] IS NULL AND $10::text[] IS NULL)\n      OR ($3::text[] IS NOT NULL AND role = ANY($3))\n      OR ($10::text[] IS NOT NULL AND role = ANY($10) AND assigned_to = $11)\n    )\n    AND ($4::text IS NULL OR type = $4)\n    AND ($5::text IS NULL OR subtype = $5)\n    AND ($6::int IS NULL OR priority = $6)\n    AND ($7::text IS NULL OR assigned_to = $7)\n    AND ($8::boolean IS NULL OR available = $8)\n    AND ($12::jsonb IS NULL OR metadata @> $12)\n    AND ($9::text IS NULL OR origin_id = $9 OR workflow_id = $9\n      OR ($13::uuid IS NOT NULL AND id = $13::uuid))";
 /**

package/build/services/escalation/sql.js

@@ -11,7 +11,7 @@
 // `hmsh_escalations` here rather than composed from generic SDK calls.
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STATION_PERIOD_METRICS_SQL = exports.STATION_LIVE_COUNTS_SQL = exports.RESOLVE_BY_METADATA_ATOMIC = exports.COUNT_SEARCH_ESCALATIONS = exports.RELEASE_EXPIRED_CLAIMS = void 0;
+exports.STATION_PERIOD_METRICS_SQL = exports.STATION_LIVE_COUNTS_SQL = exports.RESOLVE_BY_METADATA_ATOMIC = exports.COUNT_SEARCH_ESCALATIONS = exports.BULK_UNASSIGN = exports.BULK_REASSIGN = exports.RELEASE_EXPIRED_CLAIMS = void 0;
 exports.searchEscalationsQuery = searchEscalationsQuery;
 /**
  * Sweep expired claims back to the available pool.
@@ -32,6 +32,49 @@ SET assigned_to = NULL,
 WHERE status = 'pending'
   AND assigned_to IS NOT NULL
   AND assigned_until <= NOW()`;
+/**
+ * Reassign: hand pending rows to a user, INCLUDING rows under a live claim —
+ * the management override that plain assign (claimMany, which skips live
+ * claims) deliberately is not. One statement: the CTE reads each row's
+ * pre-update assignee (CTEs share one snapshot), so callers get
+ * prior_assignee for the event with no read-then-write window. An in-flight
+ * resolve by the prior assignee fails its claim assertion once assigned_to
+ * changes.
+ */
+exports.BULK_REASSIGN = `\
+WITH prior AS (
+  SELECT id, assigned_to FROM public.hmsh_escalations WHERE id = ANY($1::uuid[])
+)
+UPDATE public.hmsh_escalations e
+SET assigned_to = $2,
+    assigned_until = NOW() + ($3::int * interval '1 minute'),
+    claimed_at = NOW(),
+    updated_at = NOW()
+FROM prior
+WHERE e.id = prior.id
+  AND e.status = 'pending'
+RETURNING e.*, prior.assigned_to AS prior_assignee`;
+/**
+ * Unassign: return pending claimed rows to the available pool (an admin
+ * override of someone else's claim — self-return stays the release verb).
+ * Clears the same field set as RELEASE_EXPIRED_CLAIMS, without the expiry
+ * predicate.
+ */
+exports.BULK_UNASSIGN = `\
+WITH prior AS (
+  SELECT id, assigned_to FROM public.hmsh_escalations WHERE id = ANY($1::uuid[])
+)
+UPDATE public.hmsh_escalations e
+SET assigned_to = NULL,
+    assigned_until = NULL,
+    claimed_at = NULL,
+    claim_expires_at = NULL,
+    updated_at = NOW()
+FROM prior
+WHERE e.id = prior.id
+  AND e.status = 'pending'
+  AND e.assigned_to IS NOT NULL
+RETURNING e.*, prior.assigned_to AS prior_assignee`;
 /**
  * Escalation search by correlation id.
  *

package/build/shared/form-validation/field-validator.js

@@ -5,6 +5,7 @@ exports.validateRequireAll = validateRequireAll;
 exports.validateFieldType = validateFieldType;
 exports.validateFieldConstraints = validateFieldConstraints;
 exports.validateField = validateField;
+const x_lt_options_1 = require("./x-lt-options");
 /**
  * Resolve a checklist widget's item definitions from its `x-lt-source`
  * "domain.path" against the escalation context. Missing domain/path or a
@@ -94,10 +95,11 @@ function validateFieldType(value, fieldSchema) {
 function validateFieldConstraints(value, fieldSchema, ctx) {
     if (!fieldSchema)
         return undefined;
-    // Enum membership — the form's select widget constrains choices; API-first
-    // callers are unconstrained, so the schema's enum is the contract.
-    const allowed = fieldSchema.enum;
-    if (Array.isArray(allowed) && allowed.length > 0
+    // Option membership — the form's select widget constrains choices; API-first
+    // callers are unconstrained, so the effective option list is the contract:
+    // the static enum, or the x-lt-options list resolved from context.
+    const allowed = (0, x_lt_options_1.resolveFieldOptions)(fieldSchema, ctx);
+    if (allowed && allowed.length > 0
         && value !== undefined && value !== null && value !== ''
         && !allowed.includes(value)) {
         return `Must be one of: ${allowed.map((v) => String(v)).join(', ')}`;

package/build/shared/form-validation/index.d.ts

@@ -14,5 +14,7 @@ export * from './x-lt-query';
 export * from './x-lt-submit-guard';
 export * from './x-lt-show-if';
 export * from './x-lt-require-any';
+export * from './x-lt-require-sum';
+export * from './x-lt-options';
 export * from './field-validator';
 export * from './validate-resolver-payload';

package/build/shared/form-validation/index.js

@@ -30,5 +30,7 @@ __exportStar(require("./x-lt-query"), exports);
 __exportStar(require("./x-lt-submit-guard"), exports);
 __exportStar(require("./x-lt-show-if"), exports);
 __exportStar(require("./x-lt-require-any"), exports);
+__exportStar(require("./x-lt-require-sum"), exports);
+__exportStar(require("./x-lt-options"), exports);
 __exportStar(require("./field-validator"), exports);
 __exportStar(require("./validate-resolver-payload"), exports);

package/build/shared/form-validation/validate-resolver-payload.d.ts

@@ -17,6 +17,8 @@
  *
  * Root-level x-lt-require-any groups run after the per-field pass: each group
  * needs a value in at least one visible member (all-hidden groups are waived).
+ * x-lt-require-sum groups follow the same visibility rules but read members
+ * as numbers: the group's visible members must sum to at least its minimum.
  *
  * The showIf/`resolver.*` domain is always the FLAT form representation, so a
  * condition like `resolver.approved` reads the same on both sides.

package/build/shared/form-validation/validate-resolver-payload.js

@@ -21,6 +21,8 @@ exports.validateResolverPayload = validateResolverPayload;
  *
  * Root-level x-lt-require-any groups run after the per-field pass: each group
  * needs a value in at least one visible member (all-hidden groups are waived).
+ * x-lt-require-sum groups follow the same visibility rules but read members
+ * as numbers: the group's visible members must sum to at least its minimum.
  *
  * The showIf/`resolver.*` domain is always the FLAT form representation, so a
  * condition like `resolver.approved` reads the same on both sides.
@@ -29,6 +31,7 @@ const field_validator_1 = require("./field-validator");
 const x_lt_show_if_1 = require("./x-lt-show-if");
 const x_lt_bind_1 = require("./x-lt-bind");
 const x_lt_require_any_1 = require("./x-lt-require-any");
+const x_lt_require_sum_1 = require("./x-lt-require-sum");
 /**
  * Validate FLAT form values against the form schema. This is the dashboard's
  * entry point (the values the user edits, keyed by field name).
@@ -65,6 +68,22 @@ function validateResolverForm(schema, formValues, ctx) {
             message: `Enter a value for at least one of: ${titles.join(', ')}`,
         });
     }
+    // Require-sum groups: the numeric values of VISIBLE members must total at
+    // least the group's minimum. A `0` is a real number here — unlike
+    // require-any, defaulted-zero quantities do not satisfy the group.
+    for (const group of (0, x_lt_require_sum_1.readRequireSumGroups)(schema)) {
+        const visible = group.fields.filter((k) => properties[k] && (0, x_lt_show_if_1.evaluateShowIf)(properties[k]['x-lt-showIf'], liveCtx));
+        if (visible.length === 0)
+            continue;
+        const total = visible.reduce((sum, k) => sum + (0, x_lt_require_sum_1.requireSumContribution)(formValues[k]), 0);
+        if (total >= group.minimum)
+            continue;
+        const titles = visible.map((k) => properties[k].title ?? k);
+        errors.push({
+            field: visible[0],
+            message: `Combined value of ${titles.join(', ')} must be at least ${group.minimum}`,
+        });
+    }
     return errors;
 }
 /**

package/build/shared/form-validation/x-lt-options.d.ts

@@ -0,0 +1,22 @@
+/**
+ * x-lt-options — a select's option list resolved from the escalation context.
+ * The field-level token names a `"domain.path"`; the value at that path is an
+ * array of scalars (strings or numbers) that becomes the field's option list,
+ * so one static role form can offer a different legal set per escalation
+ * (e.g. `[1..N]` where N rides the envelope).
+ *
+ *   x-lt-options   "domain.path" — e.g. "envelope.left_quantity_options"
+ *
+ * A static `enum` takes precedence when both are present — the same
+ * static-over-dynamic rule as x-lt-minimum/x-lt-maximum. A path that resolves
+ * to nothing, or to no scalar entries, yields no options: the field renders as
+ * a plain input for its type and membership is not enforced. Non-scalar
+ * entries in a resolved array are dropped.
+ */
+export declare const X_LT_OPTIONS = "x-lt-options";
+export type OptionValue = string | number;
+/**
+ * The field's effective option list: the static `enum` when present, else the
+ * scalars at the token's `"domain.path"`. Undefined when neither yields any.
+ */
+export declare function resolveFieldOptions(fieldSchema: Record<string, unknown> | null | undefined, ctx: Record<string, unknown> | undefined): OptionValue[] | undefined;

package/build/shared/form-validation/x-lt-options.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * x-lt-options — a select's option list resolved from the escalation context.
+ * The field-level token names a `"domain.path"`; the value at that path is an
+ * array of scalars (strings or numbers) that becomes the field's option list,
+ * so one static role form can offer a different legal set per escalation
+ * (e.g. `[1..N]` where N rides the envelope).
+ *
+ *   x-lt-options   "domain.path" — e.g. "envelope.left_quantity_options"
+ *
+ * A static `enum` takes precedence when both are present — the same
+ * static-over-dynamic rule as x-lt-minimum/x-lt-maximum. A path that resolves
+ * to nothing, or to no scalar entries, yields no options: the field renders as
+ * a plain input for its type and membership is not enforced. Non-scalar
+ * entries in a resolved array are dropped.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.X_LT_OPTIONS = void 0;
+exports.resolveFieldOptions = resolveFieldOptions;
+exports.X_LT_OPTIONS = 'x-lt-options';
+/**
+ * The field's effective option list: the static `enum` when present, else the
+ * scalars at the token's `"domain.path"`. Undefined when neither yields any.
+ */
+function resolveFieldOptions(fieldSchema, ctx) {
+    if (!fieldSchema)
+        return undefined;
+    const staticEnum = fieldSchema.enum;
+    if (Array.isArray(staticEnum) && staticEnum.length > 0) {
+        return staticEnum;
+    }
+    const sourcePath = fieldSchema[exports.X_LT_OPTIONS];
+    if (typeof sourcePath !== 'string' || !ctx)
+        return undefined;
+    const dot = sourcePath.indexOf('.');
+    if (dot === -1)
+        return undefined;
+    const domainObj = ctx[sourcePath.slice(0, dot)];
+    if (!domainObj || typeof domainObj !== 'object')
+        return undefined;
+    let cur = domainObj;
+    for (const p of sourcePath.slice(dot + 1).split('.')) {
+        cur = cur[p];
+        if (cur === undefined)
+            return undefined;
+    }
+    if (!Array.isArray(cur))
+        return undefined;
+    const scalars = cur.filter((v) => typeof v === 'string' || (typeof v === 'number' && Number.isFinite(v)));
+    return scalars.length > 0 ? scalars : undefined;
+}

package/build/shared/form-validation/x-lt-require-sum.d.ts

@@ -0,0 +1,30 @@
+/**
+ * x-lt-require-sum — "these quantities must total at least N" as a
+ * root-schema token. Where x-lt-require-any asks that one member carry any
+ * answer (so a count defaulting to `0` vacuously satisfies it), require-sum
+ * reads the members as numbers and demands their sum reach a minimum. The
+ * canonical case: a Left quantity and a Right quantity that both default to
+ * `0`, where at least one side must be positive.
+ *
+ *   x-lt-require-sum   { fields: string[], minimum?: number }[]
+ *                      — e.g. [{ "fields": ["left_quantity", "right_quantity"] }]
+ *
+ * `minimum` defaults to 1. Numbers contribute their value and numeric strings
+ * coerce (the same reading as dynamic bounds); everything else contributes 0.
+ * Visibility rules compose the same way as require-any: a member hidden by
+ * its `x-lt-showIf` (or naming no schema property) contributes nothing and is
+ * not demanded, and a group whose members are ALL hidden is waived.
+ */
+export declare const X_LT_REQUIRE_SUM = "x-lt-require-sum";
+export interface RequireSumGroup {
+    fields: string[];
+    minimum: number;
+}
+/**
+ * The schema's require-sum groups. Malformed declarations (non-array token,
+ * groups without a fields array, non-string members, non-numeric minimum)
+ * read as no groups — a bad token never bricks submission.
+ */
+export declare function readRequireSumGroups(schema: Record<string, unknown> | null | undefined): RequireSumGroup[];
+/** A member's numeric contribution: numbers as-is, numeric strings coerced, all else 0. */
+export declare function requireSumContribution(value: unknown): number;