@hotmeshio/long-tail 0.18.1 → 0.19.0

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

@@ -1,5 +1,5 @@
 export { createEscalation } from './create';
-export { listEscalations, listAvailableEscalations, listDistinctTypes, listFacetKeys, getEscalationStats, getStationMetrics } from './list';
+export { listEscalations, listAvailableEscalations, listDistinctTypes, listFacetKeys, listFacetValues, getEscalationStats, getStationMetrics } from './list';
 export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './single';
 export { getEscalationLookups } from './lookups';
 export { claimEscalation, releaseEscalation } from './claim';

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.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = 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.getEscalationLookups = 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.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = 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.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetValues = 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");
@@ -8,6 +8,7 @@ Object.defineProperty(exports, "listEscalations", { enumerable: true, get: funct
 Object.defineProperty(exports, "listAvailableEscalations", { enumerable: true, get: function () { return list_1.listAvailableEscalations; } });
 Object.defineProperty(exports, "listDistinctTypes", { enumerable: true, get: function () { return list_1.listDistinctTypes; } });
 Object.defineProperty(exports, "listFacetKeys", { enumerable: true, get: function () { return list_1.listFacetKeys; } });
+Object.defineProperty(exports, "listFacetValues", { enumerable: true, get: function () { return list_1.listFacetValues; } });
 Object.defineProperty(exports, "getEscalationStats", { enumerable: true, get: function () { return list_1.getEscalationStats; } });
 Object.defineProperty(exports, "getStationMetrics", { enumerable: true, get: function () { return list_1.getStationMetrics; } });
 var single_1 = require("./single");

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

@@ -90,6 +90,16 @@ export declare function listAvailableEscalations(input: {
  * @returns `{ status: 200, data: { keys: string[] } }`
  */
 export declare function listFacetKeys(_input: unknown, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Distinct VALUES for one metadata facet key, role-scoped — powers the facet
+ * value picker (e.g. facility → north|south). A missing/malformed key returns
+ * an empty list, never an error.
+ *
+ * @returns `{ status: 200, data: { values: string[] } }`
+ */
+export declare function listFacetValues(input: {
+    key?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * List all distinct escalation type values.
  *
@@ -108,4 +118,5 @@ export declare function getEscalationStats(input: {
 }, auth: LTApiAuth): Promise<LTApiResult>;
 export declare function getStationMetrics(input: {
     period?: string;
+    facets?: Record<string, unknown>;
 }, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/list.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.listEscalations = listEscalations;
 exports.listAvailableEscalations = listAvailableEscalations;
 exports.listFacetKeys = listFacetKeys;
+exports.listFacetValues = listFacetValues;
 exports.listDistinctTypes = listDistinctTypes;
 exports.getEscalationStats = getEscalationStats;
 exports.getStationMetrics = getStationMetrics;
@@ -239,6 +240,34 @@ async function listFacetKeys(_input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Distinct VALUES for one metadata facet key, role-scoped — powers the facet
+ * value picker (e.g. facility → north|south). A missing/malformed key returns
+ * an empty list, never an error.
+ *
+ * @returns `{ status: 200, data: { values: string[] } }`
+ */
+async function listFacetValues(input, auth) {
+    try {
+        const key = input?.key;
+        if (!key)
+            return { status: 200, data: { values: [] } };
+        const scope = await (0, helpers_1.getEscalationReadScope)(auth.userId);
+        if (!scope.global && scope.allRoles.length === 0 && scope.selfRoles.length === 0) {
+            return { status: 200, data: { values: [] } };
+        }
+        const values = await escalationService.listFacetValues(key, {
+            global: scope.global,
+            visibleRoles: scope.global ? undefined : scope.allRoles,
+            selfRoles: scope.global ? undefined : scope.selfRoles,
+            meUserId: auth.userId,
+        });
+        return { status: 200, data: { values } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 /**
  * List all distinct escalation type values.
  *
@@ -297,7 +326,7 @@ async function getStationMetrics(input, auth) {
         // elsewhere) — without the selfRoles union, a self-scoped operator would
         // see an empty board on their own lanes.
         if ((0, features_1.getFeatureFlags)().publicPaceBoard) {
-            const stations = await escalationService.getStationMetrics(undefined, input.period);
+            const stations = await escalationService.getStationMetrics(undefined, input.period, input.facets);
             return { status: 200, data: { stations } };
         }
         const scope = await (0, helpers_1.getEscalationReadScope)(auth.userId);
@@ -305,7 +334,7 @@ async function getStationMetrics(input, auth) {
         if (!scope.global && memberRoles.length === 0) {
             return { status: 200, data: { stations: [] } };
         }
-        const stations = await escalationService.getStationMetrics(scope.global ? undefined : memberRoles, input.period);
+        const stations = await escalationService.getStationMetrics(scope.global ? undefined : memberRoles, input.period, input.facets);
         return { status: 200, data: { stations } };
     }
     catch (err) {

package/build/api/users.d.ts

@@ -19,6 +19,17 @@ export declare function listUsers(input: {
     limit?: number;
     offset?: number;
 }): Promise<LTApiResult>;
+/**
+ * Resolve many user ids to display fields (id, display_name, external_id, email)
+ * in one call. Thin projection only — no secrets, scopes, or metadata. Non-UUID
+ * ids are dropped, ids deduped, and the batch capped by the service.
+ *
+ * @param input.ids — the user ids to resolve
+ * @returns `{ status: 200, data: { users: [{ id, display_name, external_id, email }] } }`
+ */
+export declare function getUserNames(input: {
+    ids?: string[];
+}): Promise<LTApiResult>;
 /**
  * Retrieve a single user by ID.
  *

package/build/api/users.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listUsers = listUsers;
+exports.getUserNames = getUserNames;
 exports.getUser = getUser;
 exports.createUser = createUser;
 exports.updateUser = updateUser;
@@ -64,6 +65,24 @@ async function listUsers(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Resolve many user ids to display fields (id, display_name, external_id, email)
+ * in one call. Thin projection only — no secrets, scopes, or metadata. Non-UUID
+ * ids are dropped, ids deduped, and the batch capped by the service.
+ *
+ * @param input.ids — the user ids to resolve
+ * @returns `{ status: 200, data: { users: [{ id, display_name, external_id, email }] } }`
+ */
+async function getUserNames(input) {
+    try {
+        const ids = Array.isArray(input.ids) ? input.ids : [];
+        const users = await userService.getUserNames(ids);
+        return { status: 200, data: { users } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 /**
  * Retrieve a single user by ID.
  *

package/build/lib/uuid.d.ts

@@ -0,0 +1,11 @@
+/**
+ * UUID shape guard for open input reaching uuid-typed columns. Postgres
+ * throws `invalid input syntax for type uuid` on a bad cast, so every
+ * caller-supplied id must pass this gate BEFORE it reaches SQL — a
+ * non-UUID string is definitionally not-found, never a 500.
+ */
+export declare const UUID_RE: RegExp;
+export declare function isUuid(value: unknown): value is string;
+/** The UUID members of a caller-supplied id list; non-UUIDs are dropped —
+ *  they can match nothing, exactly like a well-formed id that does not exist. */
+export declare function onlyUuids(ids: string[]): string[];

package/build/lib/uuid.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * UUID shape guard for open input reaching uuid-typed columns. Postgres
+ * throws `invalid input syntax for type uuid` on a bad cast, so every
+ * caller-supplied id must pass this gate BEFORE it reaches SQL — a
+ * non-UUID string is definitionally not-found, never a 500.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UUID_RE = void 0;
+exports.isUuid = isUuid;
+exports.onlyUuids = onlyUuids;
+exports.UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(value) {
+    return typeof value === 'string' && exports.UUID_RE.test(value);
+}
+/** The UUID members of a caller-supplied id list; non-UUIDs are dropped —
+ *  they can match nothing, exactly like a well-formed id that does not exist. */
+function onlyUuids(ids) {
+    return ids.filter((id) => isUuid(id));
+}

package/build/routes/escalations/list.js

@@ -158,6 +158,15 @@ function registerListRoutes(router) {
         const result = await api.listFacetKeys(undefined, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    /**
+     * GET /api/escalations/facet-values?key=<facet>
+     * Distinct VALUES for one metadata facet key, visible to the caller
+     * (role-scoped). Powers the facet value picker (e.g. facility → north|south).
+     */
+    router.get('/facet-values', async (req, res) => {
+        const result = await api.listFacetValues({ key: req.query.key }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * GET /api/escalations/station-metrics
      * Per-role P99/P50/avg/max wait + work times, resolved count, and in-arrears
@@ -165,7 +174,7 @@ function registerListRoutes(router) {
      * RBAC: superadmin sees all; others scoped to their roles.
      */
     router.get('/station-metrics', async (req, res) => {
-        const result = await api.getStationMetrics({ period: req.query.period || undefined }, req.auth);
+        const result = await api.getStationMetrics({ period: req.query.period || undefined, facets: jsonParam(req.query.facets) }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
     /**

package/build/routes/users.js

@@ -55,6 +55,15 @@ router.get('/', async (req, res) => {
     });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * POST /api/users/names
+ * Batch-resolve user ids to display fields. Body: { ids: string[] }.
+ * Any authenticated user — display names carry no secrets.
+ */
+router.post('/names', async (req, res) => {
+    const result = await api.getUserNames({ ids: req.body?.ids });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * GET /api/users/system-property-keys
  * The property keys the platform resolves identities against (enabled

package/build/scripts/ortho-populate.d.ts

@@ -100,7 +100,7 @@ declare function holdFor(esc: {
 declare function api(method: string, path: string, body?: unknown): Promise<any>;
 declare function login(): Promise<void>;
 declare function ensureSideQuestRoles(): Promise<void>;
-declare function createSideEscalation(role: string, workflowId: string, orderId: string, runId: string, description: string, authorizedAt: string): Promise<boolean>;
+declare function createSideEscalation(role: string, workflowId: string, orderId: string, runId: string, description: string, authorizedAt: string, facility?: string): Promise<boolean>;
 declare function claimBatch(batchTag: string): Promise<number>;
 declare function resolveBatch(batchTag: string, runId: string): Promise<number>;
 interface PlannedOrder {
@@ -108,7 +108,9 @@ interface PlannedOrder {
     wfId: string;
     orderId: string;
     shoes: boolean;
+    facility: string;
 }
+declare const FACILITIES: readonly ["north", "south"];
 declare function runOrders(batchTag: string, runId: string, plan: PlannedOrder[], target: {
     value: number;
 }): Promise<string[]>;

package/build/scripts/ortho-populate.js

@@ -178,7 +178,7 @@ async function ensureSideQuestRoles() {
         console.log(`[${ts()}] Entity declared on ${declared} role(s): order_id`);
 }
 // ── Side-quest escalations (standalone rows — no workflow behind them) ────────
-async function createSideEscalation(role, workflowId, orderId, runId, description, authorizedAt) {
+async function createSideEscalation(role, workflowId, orderId, runId, description, authorizedAt, facility) {
     try {
         await api('POST', '/api/escalations', {
             type: 'ortho-stage',
@@ -186,8 +186,8 @@ async function createSideEscalation(role, workflowId, orderId, runId, descriptio
             role,
             description,
             workflow_id: workflowId,
-            envelope: JSON.stringify({ order_id: orderId }),
-            metadata: { order_id: orderId, source: 'populate', run_id: runId, authorized_at: authorizedAt },
+            envelope: JSON.stringify({ order_id: orderId, ...(facility ? { facility } : {}) }),
+            metadata: { order_id: orderId, source: 'populate', run_id: runId, authorized_at: authorizedAt, ...(facility ? { facility } : {}) },
         });
         return true;
     }
@@ -261,7 +261,7 @@ async function resolveBatch(batchTag, runId) {
                 // order's authorized_at rides along from the ordering escalation.
                 if (esc.role === 'ordering') {
                     const orderId = esc.metadata?.order_id ?? '';
-                    await createSideEscalation('inserting', esc.workflow_id, orderId, runId, `Stuff inserts into shoes for ${orderId}`, esc.metadata?.authorized_at ?? new Date().toISOString());
+                    await createSideEscalation('inserting', esc.workflow_id, orderId, runId, `Stuff inserts into shoes for ${orderId}`, esc.metadata?.authorized_at ?? new Date().toISOString(), esc.metadata?.facility);
                 }
             }
             catch (err) {
@@ -275,6 +275,10 @@ async function resolveBatch(batchTag, runId) {
         return 0;
     }
 }
+// Two manufacturing sites — each order is assigned one at arrival and every
+// escalation it spawns carries it, so the Pace Board's facet scope
+// (facility = north|south) has real data to narrow.
+const FACILITIES = ['north', 'south'];
 async function runOrders(batchTag, runId, plan, target) {
     let done = false;
     const workflowIds = [];
@@ -295,6 +299,9 @@ async function runOrders(batchTag, runId, plan, target) {
                     data: {
                         order_id: order.orderId,
                         item_type: 'insole-standard',
+                        // Stamped on the envelope; the workflow applies it to every stage
+                        // escalation's metadata as the facility facet.
+                        facility: order.facility,
                         metadata: { source: 'populate', run_id: runId, authorized_at: authorizedAt },
                     },
                     metadata: { source: 'populate', run_id: runId, shoes: order.shoes },
@@ -308,7 +315,7 @@ async function runOrders(batchTag, runId, plan, target) {
                 continue;
             }
             if (order.shoes) {
-                const ok = await createSideEscalation('ordering', `${order.wfId}-shoes`, order.orderId, runId, `Order shoes for ${order.orderId}`, authorizedAt);
+                const ok = await createSideEscalation('ordering', `${order.wfId}-shoes`, order.orderId, runId, `Order shoes for ${order.orderId}`, authorizedAt, order.facility);
                 if (!ok)
                     target.value -= 2;
             }
@@ -372,6 +379,9 @@ async function main() {
         wfId: `${batchTag}-${i}`,
         orderId: `ORD-${runId}-${i}`,
         shoes: hasShoes(i),
+        // Pseudo-random per order (hashed on the workflow id): reproducible across
+        // re-runs, roughly balanced across both sites.
+        facility: FACILITIES[Math.floor(jitter(`${batchTag}-${i}`, 'facility') * FACILITIES.length)],
     }));
     const shoeCount = plan.filter((o) => o.shoes).length;
     // Each order resolves 8 manufacturing stages; a shoe order adds

package/build/sdk/index.d.ts

@@ -123,6 +123,7 @@ export declare function createClient(options?: LTClientOptions): {
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         getStationMetrics: (input: {
             period?: string;
+            facets?: Record<string, unknown>;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         get: (input: {
             id: string;

package/build/services/escalation/batch.js

@@ -4,6 +4,7 @@ exports.resolveBatchItem = resolveBatchItem;
 exports.resolveBatchItemBySignalKey = resolveBatchItemBySignalKey;
 exports.resolveBatchItemByMetadata = resolveBatchItemByMetadata;
 const escalation_wire_1 = require("../../lib/events/escalation-wire");
+const uuid_1 = require("../../lib/uuid");
 const client_1 = require("./client");
 const crud_1 = require("./crud");
 const map_1 = require("./map");
@@ -15,6 +16,8 @@ const map_1 = require("./map");
  * outcomes publish nothing — the row was untouched.
  */
 async function resolveBatchItem(id, itemKey, payload, metadata, assertClaim, resolvedBy) {
+    if (!(0, uuid_1.isUuid)(id))
+        return { outcome: 'not-found', remaining: -1, escalation: null };
     const client = await (0, client_1.escalations)();
     const result = await client.resolveBatchItem({
         id,

package/build/services/escalation/bulk.js

@@ -8,6 +8,7 @@ exports.bulkUnassignEscalations = bulkUnassignEscalations;
 exports.bulkEscalateToRole = bulkEscalateToRole;
 exports.bulkCancelEscalations = bulkCancelEscalations;
 exports.bulkResolveForTriage = bulkResolveForTriage;
+const uuid_1 = require("../../lib/uuid");
 const db_1 = require("../../lib/db");
 const client_1 = require("./client");
 const map_1 = require("./map");
@@ -17,6 +18,7 @@ const sql_1 = require("./sql");
  * Items already claimed by another active user are skipped.
  */
 async function bulkClaimEscalations(ids, userId, durationMinutes = 30) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return { claimed: 0, skipped: 0 };
     const client = await (0, client_1.escalations)();
@@ -27,6 +29,7 @@ async function bulkClaimEscalations(ids, userId, durationMinutes = 30) {
  * Items already claimed by another active user are skipped.
  */
 async function bulkAssignEscalations(ids, targetUserId, durationMinutes = 30) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return { assigned: 0, skipped: 0 };
     const client = await (0, client_1.escalations)();
@@ -60,6 +63,7 @@ async function bulkAssignEscalationsByQuery(query, targetUserId, durationMinutes
  * returned row carries its pre-update assignee for the event.
  */
 async function bulkReassignEscalations(ids, targetUserId, durationMinutes = 30) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return { assigned: 0, skipped: 0, changes: [] };
     await (0, client_1.ensureEscalationCompatView)();
@@ -77,6 +81,7 @@ async function bulkReassignEscalations(ids, targetUserId, durationMinutes = 30)
  * statement; unclaimed and terminal rows are skipped.
  */
 async function bulkUnassignEscalations(ids) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return { unassigned: 0, skipped: 0, changes: [] };
     await (0, client_1.ensureEscalationCompatView)();
@@ -93,6 +98,7 @@ async function bulkUnassignEscalations(ids) {
  * Clears assignment on all affected rows.
  */
 async function bulkEscalateToRole(ids, targetRole) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return 0;
     const client = await (0, client_1.escalations)();
@@ -104,6 +110,7 @@ async function bulkEscalateToRole(ids, targetRole) {
  * successfully cancelled.
  */
 async function bulkCancelEscalations(ids) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return { cancelled: 0, skipped: 0 };
     const client = await (0, client_1.escalations)();
@@ -126,6 +133,7 @@ async function bulkCancelEscalations(ids) {
  * `pending`; only the returned rows enter triage.
  */
 async function bulkResolveForTriage(ids, hint) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return [];
     const client = await (0, client_1.escalations)();

package/build/services/escalation/crud.js

@@ -29,6 +29,7 @@ const db_1 = require("../../lib/db");
 const publish_1 = require("../../lib/events/publish");
 const escalation_wire_1 = require("../../lib/events/escalation-wire");
 const escalation_1 = require("../../types/escalation");
+const uuid_1 = require("../../lib/uuid");
 const client_1 = require("./client");
 const queries_1 = require("./queries");
 const map_1 = require("./map");
@@ -95,6 +96,8 @@ async function createEscalation(input) {
  * user re-claims (extends expiry). Returns null when the row is not claimable.
  */
 async function claimEscalation(id, userId, durationMinutes = 30) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
     const client = await (0, client_1.escalations)();
     const result = await client.claim({ id, assignee: userId, durationMinutes });
     if (!result.ok)
@@ -132,6 +135,8 @@ async function claimEscalation(id, userId, durationMinutes = 30) {
  * the stored `resolver_payload`.
  */
 async function resolveEscalation(id, resolverPayload, metadata, assertClaim, resolvedBy) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
     const client = await (0, client_1.escalations)();
     // `assertClaim` rides the SDK's guarded UPDATE: no active claim lock may
     // stand against this assignee, or the resolve blocks (claim-expired /
@@ -169,6 +174,7 @@ async function resolveEscalation(id, resolverPayload, metadata, assertClaim, res
  * `resolveEscalation` (which delivers the signal).
  */
 async function resolveEscalationsByIds(ids, resolverPayload, metadata) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return [];
     const client = await (0, client_1.escalations)();
@@ -209,6 +215,12 @@ async function resolveEscalationsByIds(ids, resolverPayload, metadata) {
 async function resolveEscalationsAllOrNone(items, metadata, assertAssignee, resolvedBy) {
     if (items.length === 0)
         return { ok: true, escalations: [] };
+    // A malformed id blocks the batch exactly like a well-formed missing one —
+    // and never reaches the uuid cast.
+    const malformed = items.filter((i) => !(0, uuid_1.isUuid)(i.id));
+    if (malformed.length > 0) {
+        return { ok: false, failed: malformed.map((i) => ({ id: i.id, reason: 'not-found' })) };
+    }
     const client = await (0, client_1.escalations)();
     const result = await client.resolveAllOrNone({ items, metadata, assertAssignee, resolvedBy });
     if (!result.ok)
@@ -235,6 +247,7 @@ async function resolveEscalationsAllOrNone(items, metadata, assertAssignee, reso
  * fields — signal routing shape, `metadata.form_schema` for redaction.
  */
 async function getEscalationsByIds(ids) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return [];
     const client = await (0, client_1.escalations)();
@@ -278,6 +291,8 @@ async function resolveEscalationBySignalKey(signalKey, resolverPayload, metadata
  * already terminal.
  */
 async function cancelEscalation(id) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
     const client = await (0, client_1.escalations)();
     const result = await client.cancel(id);
     if (!result.ok)
@@ -301,6 +316,7 @@ async function cancelEscalation(id) {
  * updated.
  */
 async function updateEscalationsPriority(ids, priority) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return 0;
     const client = await (0, client_1.escalations)();
@@ -311,6 +327,7 @@ async function updateEscalationsPriority(ids, priority) {
  * Used for permission validation before bulk operations.
  */
 async function getEscalationRoles(ids) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return [];
     const client = await (0, client_1.escalations)();
@@ -323,6 +340,7 @@ async function getEscalationRoles(ids) {
  * write_self by ownership (assigned_to = caller). One query, no N+1.
  */
 async function getEscalationScopeRows(ids) {
+    ids = (0, uuid_1.onlyUuids)(ids);
     if (ids.length === 0)
         return [];
     const client = await (0, client_1.escalations)();
@@ -344,6 +362,8 @@ async function getEscalationScopeRows(ids) {
  * stays loud.
  */
 async function releaseEscalation(id, userId, opts) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
     const client = await (0, client_1.escalations)();
     const result = await client.release({ id, assignee: userId });
     if (!result.ok)
@@ -381,6 +401,8 @@ async function releaseExpiredClaims() {
  * Clears the current assignment so it becomes available to the new role.
  */
 async function escalateToRole(id, targetRole) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
     const client = await (0, client_1.escalations)();
     // The departing role is read before the move: the returned entry already
     // carries the target role, and role-scoped subscribers of the OLD queue
@@ -414,6 +436,8 @@ async function escalateToRole(id, targetRole) {
     return escalation;
 }
 async function getEscalation(id) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
     const client = await (0, client_1.escalations)();
     const entry = await client.get(id);
     return entry ? (0, map_1.toEscalationRecord)(entry) : null;
@@ -474,6 +498,8 @@ async function cancelEscalationsByWorkflowId(workflowId) {
     return rows.length;
 }
 async function enrichEscalationRouting(id, metadataPatch, workflowFields) {
+    if (!(0, uuid_1.isUuid)(id))
+        return null;
     const client = await (0, client_1.escalations)();
     const entry = await client.update({
         id,

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

@@ -54,6 +54,19 @@ export declare function listFacetKeys(opts: {
     selfRoles?: string[];
     meUserId?: string;
 }): Promise<string[]>;
+/**
+ * Distinct VALUES for one metadata facet key, visible to the caller — feeds
+ * the value picker (e.g. facility → [north, south]) so a bound scope offers
+ * real choices. Role-scoped with the same predicate as {@link listFacetKeys};
+ * the key is parameterized (never interpolated) and charset-validated, so a
+ * malformed key returns [] rather than reaching an unguarded path.
+ */
+export declare function listFacetValues(key: string, opts: {
+    global?: boolean;
+    visibleRoles?: string[];
+    selfRoles?: string[];
+    meUserId?: string;
+}): Promise<string[]>;
 export declare function getEscalationStats(visibleRoles?: string[], period?: string): Promise<EscalationStats>;
 export declare function listDistinctTypes(): Promise<string[]>;
 export declare function listEscalations(filters: {
@@ -108,4 +121,4 @@ export declare function listAvailableEscalations(filters: {
 export declare function invalidateEscalationAggregates(): void;
 /** Test hook: drop cached period metrics AND escalation stats so tests observe fresh rows. */
 export declare function resetStationMetricsCache(): void;
-export declare function getStationMetrics(visibleRoles: string[] | undefined, period?: string): Promise<StationMetric[]>;
+export declare function getStationMetrics(visibleRoles: string[] | undefined, period?: string, facets?: Record<string, unknown>): Promise<StationMetric[]>;