@hotmeshio/long-tail 0.6.2 → 0.7.0

package/build/services/escalation/queries.js

@@ -6,12 +6,16 @@ exports.getEscalationStats = getEscalationStats;
 exports.listDistinctTypes = listDistinctTypes;
 exports.listEscalations = listEscalations;
 exports.listAvailableEscalations = listAvailableEscalations;
+exports.invalidateEscalationAggregates = invalidateEscalationAggregates;
+exports.resetStationMetricsCache = resetStationMetricsCache;
+exports.getStationMetrics = getStationMetrics;
 const db_1 = require("../../lib/db");
 const client_1 = require("./client");
 const map_1 = require("./map");
 const facet_sql_1 = require("./facet-sql");
 const types_1 = require("./types");
 const sql_1 = require("./sql");
+const metrics_cache_1 = require("./metrics-cache");
 /**
  * Default sort is priority ASC, created_at ASC. A user-chosen `sort_by` maps to
  * a single column (DESC unless `order='asc'`), matching the legacy behavior.
@@ -36,6 +40,13 @@ function buildSearchOrderBy(sortBy, order) {
     }
     return 'priority ASC, created_at ASC';
 }
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * The id arm of the correlation search binds a uuid param only when the term
+ * parses as one — comparing `id::text = $term` casts the uuid column and has
+ * no index path, which drags the whole OR into a full history scan.
+ */
+const asUuidOrNull = (term) => term && UUID_RE.test(term) ? term : null;
 /**
  * Server-side free-text search over the `lt_escalations` view. Runs when a
  * caller supplies a non-empty `search` term — the SDK `client.list()` cannot do
@@ -62,6 +73,7 @@ async function searchEscalations(params) {
         params.selfRoles && params.selfRoles.length ? params.selfRoles : null,
         params.meUserId || null,
         params.metadata ? JSON.stringify(params.metadata) : null,
+        asUuidOrNull(params.search),
     ];
     const orderBy = buildSearchOrderBy(params.sort_by, params.order);
     const [rows, countRows] = await Promise.all([
@@ -78,7 +90,8 @@ async function searchEscalations(params) {
  * predicate (global → none; else `role ∈ allRoles OR (role ∈ selfRoles AND
  * assigned_to = me)`) with the full FacetQuery language (`buildFacetWhere`:
  * facets `@>`, block, numeric range, exists, status, available) plus the extra
- * top-level filters (type/subtype/priority/assigned_to) and free-text, then orders
+ * top-level filters (type/subtype/priority/assigned_to) and an exact correlation-id
+ * match (id/workflow_id/origin_id), then orders
  * by `buildFacetOrder` (columns + `metadata.<key>`). Every value is bound; the
  * COUNT shares the WHERE so totals stay correct across pages — no client-side
  * filtering. Reads go through the `public.lt_escalations` view.
@@ -110,13 +123,14 @@ async function searchEscalationsFaceted(opts) {
         clauses.push(`priority = $${params.push(opts.priority)}`);
     if (opts.assigned_to)
         clauses.push(`assigned_to = $${params.push(opts.assigned_to)}`);
-    // 4. Free-text (same fields as the list search path).
+    // 4. Correlation-id match (exact) — same fields as the list search path.
+    // Equality keeps it index-served (origin_id / workflow_id btree, id pk); the
+    // id arm binds a pre-parsed uuid so the PK can serve it, and metadata is
+    // searched precisely via the facets above, never a full-table text scan.
     if (opts.search) {
         const i = params.push(opts.search);
-        clauses.push(`(description ILIKE '%' || $${i} || '%' OR type ILIKE '%' || $${i} || '%'
-        OR subtype ILIKE '%' || $${i} || '%' OR role ILIKE '%' || $${i} || '%'
-        OR workflow_id ILIKE '%' || $${i} || '%' OR origin_id ILIKE '%' || $${i} || '%'
-        OR id::text ILIKE '%' || $${i} || '%' OR metadata::text ILIKE '%' || $${i} || '%')`);
+        const u = params.push(asUuidOrNull(opts.search));
+        clauses.push(`(origin_id = $${i} OR workflow_id = $${i} OR ($${u}::uuid IS NOT NULL AND id = $${u}::uuid))`);
     }
     const where = clauses.length ? `WHERE ${clauses.join('\n  AND ')}` : '';
     const orderBy = (0, facet_sql_1.buildFacetOrder)(opts.facet.orderBy);
@@ -152,13 +166,46 @@ async function listFacetKeys(opts) {
        FROM public.lt_escalations
       WHERE ${clauses.join('\n        AND ')}
       ORDER BY key`, params);
-    return rows.map((r) => r.key);
+    const actualKeys = new Set(rows.map((r) => r.key));
+    // Also surface keys declared in metadata_schema for visible roles — so the
+    // autocomplete offers expected keys even before any data has been created.
+    const roleFilter = opts.global
+        ? null
+        : [...(opts.visibleRoles ?? []), ...(opts.selfRoles ?? [])];
+    if (roleFilter === null || roleFilter.length > 0) {
+        const schemaParam = roleFilter === null ? null : roleFilter;
+        const { rows: schemaRows } = await pool.query(`SELECT metadata_schema FROM lt_roles
+        WHERE metadata_schema IS NOT NULL
+          AND ($1::text[] IS NULL OR role = ANY($1))`, [schemaParam]);
+        for (const row of schemaRows) {
+            const schema = row.metadata_schema;
+            if (schema?.properties && typeof schema.properties === 'object') {
+                for (const key of Object.keys(schema.properties)) {
+                    actualKeys.add(key);
+                }
+            }
+        }
+    }
+    return [...actualKeys].sort();
 }
+// Escalation stats back the home + overview surfaces and refresh on every
+// escalation event. As of hotmesh 0.25.0 the SDK stats query reads three
+// bounded, index-only sources (pending backlog, created window, resolved
+// window), so it is cheap enough to run per-request — this short single-flight
+// window exists purely to collapse the refetch burst a busy escalation stream
+// triggers (every event → every open dashboard refetches at once). Local
+// writes clear the cache (see crud.ts publishEscalationChange), so a refetch
+// on this container always observes its own write.
+const ESCALATION_STATS_CACHE_TTL_MS = 2_500;
+const escalationStatsCache = new metrics_cache_1.TtlCache(ESCALATION_STATS_CACHE_TTL_MS);
 async function getEscalationStats(visibleRoles, period) {
-    const client = await (0, client_1.escalations)();
-    return client.stats({
-        roles: visibleRoles,
-        period: period,
+    const key = `${period ?? '24h'}::${visibleRoles ? [...visibleRoles].sort().join(',') : 'ALL'}`;
+    return escalationStatsCache.resolve(key, async () => {
+        const client = await (0, client_1.escalations)();
+        return client.stats({
+            roles: visibleRoles,
+            period: period,
+        });
     });
 }
 async function listDistinctTypes() {
@@ -266,3 +313,66 @@ async function listAvailableEscalations(filters) {
     ]);
     return { escalations: (0, map_1.toEscalationRecords)(rows), total };
 }
+// Period metrics (percentiles + throughput) are expensive and slow-changing, so
+// they are cached ~30s and shared, via single-flight, across the socket-driven
+// refresh burst and all concurrent viewers. Live counts are never cached — they
+// refresh on every event. Per-container cache; 30-60s staleness is acceptable.
+const STATION_PERIOD_CACHE_TTL_MS = 30_000;
+const stationPeriodCache = new metrics_cache_1.TtlCache(STATION_PERIOD_CACHE_TTL_MS);
+/**
+ * Drop cached aggregates (period metrics + escalation stats). Called by the
+ * write paths in crud.ts alongside each escalation event publish: the event
+ * tells dashboards "data changed", so the very next fetch on this container
+ * must recompute rather than serve the pre-change aggregate for up to a TTL.
+ * Cross-container staleness within the TTL remains and is acceptable.
+ */
+function invalidateEscalationAggregates() {
+    stationPeriodCache.clear();
+    escalationStatsCache.clear();
+}
+/** Test hook: drop cached period metrics AND escalation stats so tests observe fresh rows. */
+function resetStationMetricsCache() {
+    invalidateEscalationAggregates();
+}
+const toNum = (v) => (v != null ? Number(v) : null);
+async function getStationMetrics(visibleRoles, period) {
+    await (0, client_1.ensureEscalationCompatView)();
+    // hasOwnProperty: a caller-supplied period like 'constructor' must fall back
+    // to 24h, not resolve to an inherited Object.prototype member.
+    const intervalStr = period && Object.prototype.hasOwnProperty.call(types_1.VALID_PERIODS, period)
+        ? types_1.VALID_PERIODS[period]
+        : '24 hours';
+    const roles = visibleRoles ?? null;
+    const pool = (0, db_1.getPool)();
+    // Live counts: always fresh (cheap — bounded pending working set).
+    // Period metrics: cached ~30s, single-flight (expensive percentile sort).
+    const cacheKey = `${period ?? '24h'}::${roles ? [...roles].sort().join(',') : 'ALL'}`;
+    const [countsResult, periodRows] = await Promise.all([
+        pool.query(sql_1.STATION_LIVE_COUNTS_SQL, [roles]),
+        stationPeriodCache.resolve(cacheKey, async () => (await pool.query(sql_1.STATION_PERIOD_METRICS_SQL, [roles, intervalStr])).rows),
+    ]);
+    const periodByRole = new Map(periodRows.map((r) => [r.role, r]));
+    return countsResult.rows.map((c) => {
+        const p = periodByRole.get(c.role);
+        return {
+            role: c.role,
+            pending: Number(c.pending ?? 0),
+            claimed: Number(c.claimed ?? 0),
+            resolved: Number(p?.resolved ?? 0),
+            in_arrears: Number(c.in_arrears ?? 0),
+            throughput_pct: p?.throughput_pct != null ? Number(p.throughput_pct) : null,
+            wait: {
+                p99: toNum(p?.p99_wait_min),
+                p50: toNum(p?.p50_wait_min),
+                avg: toNum(p?.avg_wait_min),
+                max: toNum(p?.max_wait_min),
+            },
+            work: {
+                p99: toNum(p?.p99_work_min),
+                p50: toNum(p?.p50_work_min),
+                avg: toNum(p?.avg_work_min),
+                max: toNum(p?.max_work_min),
+            },
+        };
+    });
+}

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

@@ -8,8 +8,8 @@
  * 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()";
-/** Count matching the search WHERE (params $1–$12). */
-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 (\n          description ILIKE '%' || $9 || '%'\n       OR type ILIKE '%' || $9 || '%'\n       OR subtype ILIKE '%' || $9 || '%'\n       OR role ILIKE '%' || $9 || '%'\n       OR workflow_id ILIKE '%' || $9 || '%'\n       OR origin_id ILIKE '%' || $9 || '%'\n       OR id::text ILIKE '%' || $9 || '%'\n       OR metadata::text ILIKE '%' || $9 || '%'\n    ))";
+/** 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))";
 /**
  * Build the search SELECT. `orderBy` is composed from a whitelist by the caller
  * (never raw user input), so it is safe to interpolate; everything else is bound.
@@ -44,3 +44,30 @@ export declare function searchEscalationsQuery(orderBy: string): string;
  * already assigned to them ($2). assigned_to is indexed, so the self-branch scales.
  */
 export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (\n         $5::text[] IS NULL\n      OR role = ANY($5)\n      OR (role = ANY($6::text[]) AND assigned_to = $2)\n    )\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND target.signal_key IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE public.hmsh_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n    AND (claimed.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.signal_key AS signal_key,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  (target.assigned_to IS NOT NULL\n    AND target.assigned_until IS NOT NULL\n    AND target.assigned_until > NOW()) AS signal_already_claimed,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";
+/**
+ * Live counts — pending, active claims, and past-SLA (in_arrears) per role.
+ *
+ * $1 TEXT[] — role filter (NULL = all roles / superadmin).
+ *
+ * Hits idx_hmsh_esc_pending_role_created (role, created_at DESC) WHERE
+ * status='pending'. The pending working set is bounded by real backlog depth,
+ * so this stays cheap as historical volume grows — safe on the hot refresh path.
+ */
+export declare const STATION_LIVE_COUNTS_SQL = "\nWITH role_targets AS (\n  SELECT role, sla_minutes\n  FROM lt_roles\n  WHERE ($1::text[] IS NULL OR role = ANY($1::text[]))\n),\nlive_counts AS (\n  SELECT\n    e.role,\n    COUNT(*)                                                                         AS pending,\n    COUNT(*) FILTER (WHERE e.assigned_to IS NOT NULL AND e.assigned_until > NOW())  AS claimed,\n    COUNT(*) FILTER (\n      WHERE rt.sla_minutes IS NOT NULL\n        AND e.created_at < NOW() - (rt.sla_minutes * INTERVAL '1 minute')\n    )                                                                                AS in_arrears\n  FROM hmsh_escalations e\n  JOIN role_targets rt ON rt.role = e.role\n  WHERE e.status = 'pending'\n  GROUP BY e.role\n)\nSELECT\n  rt.role,\n  COALESCE(lc.pending,    0) AS pending,\n  COALESCE(lc.claimed,    0) AS claimed,\n  COALESCE(lc.in_arrears, 0) AS in_arrears\nFROM role_targets rt\nLEFT JOIN live_counts lc ON lc.role = rt.role\nORDER BY rt.role\n";
+/**
+ * Period metrics — resolved count, throughput efficiency, and P99/P50/avg/max
+ * latency for wait (queue time) and work (processing) per role.
+ *
+ * $1 TEXT[]   — role filter (NULL = all roles / superadmin).
+ * $2 INTERVAL — time window (e.g. '24 hours', '15 minutes').
+ *
+ * Hits idx_hmsh_esc_resolved_cover (role, resolved_at DESC, claimed_at,
+ * created_at) WHERE status='resolved' — a covering index, so the percentile
+ * scan is index-only. PERCENTILE_CONT still sorts the qualifying set in memory,
+ * which is why the service caches this result rather than running it per event.
+ *
+ * Latency is computed over CLOSED work (status='resolved' in the period), not a
+ * mix of resolved + in-flight — a clean "how did completed work perform?" read.
+ * throughput_pct is NULL when the role has no target_per_hour (NULLIF guard).
+ */
+export declare const STATION_PERIOD_METRICS_SQL = "\nWITH role_targets AS (\n  SELECT role, target_per_hour\n  FROM lt_roles\n  WHERE ($1::text[] IS NULL OR role = ANY($1::text[]))\n),\nperiod_metrics AS (\n  SELECT\n    e.role,\n    COUNT(*)                                                                         AS resolved,\n    ROUND((PERCENTILE_CONT(0.99) WITHIN GROUP (\n      ORDER BY EXTRACT(EPOCH FROM (e.claimed_at - e.created_at)) / 60)\n      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS p99_wait_min,\n    ROUND((PERCENTILE_CONT(0.50) WITHIN GROUP (\n      ORDER BY EXTRACT(EPOCH FROM (e.claimed_at - e.created_at)) / 60)\n      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS p50_wait_min,\n    ROUND((AVG(EXTRACT(EPOCH FROM (e.claimed_at - e.created_at)) / 60)\n      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS avg_wait_min,\n    ROUND((MAX(EXTRACT(EPOCH FROM (e.claimed_at - e.created_at)) / 60)\n      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS max_wait_min,\n    ROUND((PERCENTILE_CONT(0.99) WITHIN GROUP (\n      ORDER BY EXTRACT(EPOCH FROM (e.resolved_at - e.claimed_at)) / 60)\n      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS p99_work_min,\n    ROUND((PERCENTILE_CONT(0.50) WITHIN GROUP (\n      ORDER BY EXTRACT(EPOCH FROM (e.resolved_at - e.claimed_at)) / 60)\n      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS p50_work_min,\n    ROUND((AVG(EXTRACT(EPOCH FROM (e.resolved_at - e.claimed_at)) / 60)\n      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS avg_work_min,\n    ROUND((MAX(EXTRACT(EPOCH FROM (e.resolved_at - e.claimed_at)) / 60)\n      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS max_work_min\n  FROM hmsh_escalations e\n  WHERE e.status = 'resolved'\n    AND e.resolved_at >= NOW() - $2::interval\n    AND ($1::text[] IS NULL OR e.role = ANY($1::text[]))\n  GROUP BY e.role\n)\nSELECT\n  rt.role,\n  COALESCE(pm.resolved, 0) AS resolved,\n  ROUND(\n    (COALESCE(pm.resolved, 0)::numeric\n      / NULLIF(rt.target_per_hour::numeric * EXTRACT(EPOCH FROM $2::interval) / 3600.0, 0)\n      * 100\n    )::numeric, 1\n  )                        AS throughput_pct,\n  pm.p99_wait_min,\n  pm.p50_wait_min,\n  pm.avg_wait_min,\n  pm.max_wait_min,\n  pm.p99_work_min,\n  pm.p50_work_min,\n  pm.avg_work_min,\n  pm.max_work_min\nFROM role_targets rt\nLEFT JOIN period_metrics pm ON pm.role = rt.role\nORDER BY rt.role\n";

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.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.RELEASE_EXPIRED_CLAIMS = void 0;
 exports.searchEscalationsQuery = searchEscalationsQuery;
 /**
  * Sweep expired claims back to the available pool.
@@ -33,19 +33,20 @@ WHERE status = 'pending'
   AND assigned_to IS NOT NULL
   AND assigned_until <= NOW()`;
 /**
- * Free-text escalation search.
+ * Escalation search by correlation id.
  *
- * The SDK's `client.list()` filters by structured columns only — it has no
- * free-text predicate. Long-tail's contract needs a search box that matches a
- * correlation key (order id, ticket id) or any visible field across the WHOLE
- * result set, not just the current page. That is server-side SQL here (over the
- * `lt_escalations` view, which adds the computed `available` flag), following the
- * same raw-SQL-on-the-shared-table pattern as the atomic resolve below — so the
- * filter flows SQL→service→API→route→dashboard rather than being faked client-side.
+ * The SDK's `client.list()` filters by structured columns only. Long-tail adds a
+ * search box that resolves a correlation id — the escalation id, its workflow id,
+ * or the origin id (order/ticket) — to the matching rows across the WHOLE result
+ * set, not just the current page. This is exact-match (equality), so it stays
+ * index-served: `origin_id` and `workflow_id` each have a btree index and `id` is
+ * the primary key. It deliberately does NOT run substring `ILIKE` over free text
+ * or `metadata::text` — a leading-wildcard ILIKE cannot use any index and would
+ * sequentially scan (and cast to text) every row, unbounded by history size.
  *
- * All structured filters are optional and combine with the search term (AND).
- * `metadata::text ILIKE` scans the JSONB as text (the GIN index is containment-only
- * and cannot serve ILIKE) — bounded in practice by the other filters and the page.
+ * Metadata is searched precisely through the GIN-served `metadata @> $12`
+ * containment path instead (see `searchEscalationsFaceted`), which needs no status
+ * filter — e.g. "every escalation for order X, any status" is one indexed lookup.
  *
  * Role-scope visibility ($3 allRoles, $10 selfRoles, $11 meUserId):
  *   - global access  → $3 NULL and $10 NULL → no role filter (sees everything)
@@ -56,9 +57,15 @@ WHERE status = 'pending'
  * (idx_lt_escalations_assigned), so the self-branch is index-served at scale.
  *
  * $1 status, $2 role, $3 allRoles (text[]), $4 type, $5 subtype, $6 priority,
- * $7 assigned_to, $8 available (bool), $9 search, $10 selfRoles (text[]),
- * $11 meUserId, $12 metadata (jsonb containment, GIN-served). The list query
- * adds $13 limit, $14 offset.
+ * $7 assigned_to, $8 available (bool), $9 search (exact workflow_id/origin_id
+ * match), $10 selfRoles (text[]), $11 meUserId, $12 metadata (jsonb containment,
+ * GIN-served), $13 search-as-uuid (the search term when it parses as a UUID,
+ * else NULL). The list query adds $14 limit, $15 offset.
+ *
+ * The id arm binds $13::uuid instead of comparing id::text = $9: casting the
+ * uuid COLUMN to text has no index path, and one unindexable arm forces the
+ * whole OR off BitmapOr into a full scan of escalation history. With the
+ * app-side parse, all three arms are index-served (origin/workflow btrees, PK).
  *
  * `metadata @> $12` is exact JSONB containment (the GIN index serves it) — this is
  * how findByMetadata routes through the scoped query so its role-scope filter and
@@ -79,24 +86,16 @@ const SEARCH_ESCALATIONS_WHERE = `\
     AND ($7::text IS NULL OR assigned_to = $7)
     AND ($8::boolean IS NULL OR available = $8)
     AND ($12::jsonb IS NULL OR metadata @> $12)
-    AND ($9::text IS NULL OR (
-          description ILIKE '%' || $9 || '%'
-       OR type ILIKE '%' || $9 || '%'
-       OR subtype ILIKE '%' || $9 || '%'
-       OR role ILIKE '%' || $9 || '%'
-       OR workflow_id ILIKE '%' || $9 || '%'
-       OR origin_id ILIKE '%' || $9 || '%'
-       OR id::text ILIKE '%' || $9 || '%'
-       OR metadata::text ILIKE '%' || $9 || '%'
-    ))`;
-/** Count matching the search WHERE (params $1–$12). */
+    AND ($9::text IS NULL OR origin_id = $9 OR workflow_id = $9
+      OR ($13::uuid IS NOT NULL AND id = $13::uuid))`;
+/** Count matching the search WHERE (params $1–$13). */
 exports.COUNT_SEARCH_ESCALATIONS = `SELECT COUNT(*)::int AS total\n${SEARCH_ESCALATIONS_WHERE}`;
 /**
  * Build the search SELECT. `orderBy` is composed from a whitelist by the caller
  * (never raw user input), so it is safe to interpolate; everything else is bound.
  */
 function searchEscalationsQuery(orderBy) {
-    return `SELECT *\n${SEARCH_ESCALATIONS_WHERE}\n  ORDER BY ${orderBy}\n  LIMIT $13 OFFSET $14`;
+    return `SELECT *\n${SEARCH_ESCALATIONS_WHERE}\n  ORDER BY ${orderBy}\n  LIMIT $14 OFFSET $15`;
 }
 /**
  * Atomic resolve by metadata with signal guard.
@@ -185,3 +184,133 @@ SELECT
   CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome
 FROM target
 LEFT JOIN resolved ON resolved.id = target.id`;
+// ---------------------------------------------------------------------------
+// Station metrics — split into two queries with very different cost profiles.
+//
+// The Operations dashboard refreshes on every escalation socket event (a
+// debounced burst) plus a periodic fallback. Computing percentiles on that hot
+// path is wasteful: percentile aggregates sort every qualifying resolved row,
+// while the live counts are cheap and bounded. So the two halves are separated:
+//
+//   STATION_LIVE_COUNTS_SQL    — pending / claimed / in_arrears. Cheap, always
+//                                run fresh. Scans only pending rows (backlog is
+//                                bounded no matter how much history accrues).
+//   STATION_PERIOD_METRICS_SQL — resolved / throughput / latency percentiles.
+//                                Expensive, slow-changing; the service layer
+//                                caches it (~30s) and shares it across the
+//                                refresh burst and all concurrent viewers.
+//
+// Both drive off role_targets so every configured role appears even when idle,
+// and the service merges them by role into one StationMetric per station.
+// ---------------------------------------------------------------------------
+/**
+ * Live counts — pending, active claims, and past-SLA (in_arrears) per role.
+ *
+ * $1 TEXT[] — role filter (NULL = all roles / superadmin).
+ *
+ * Hits idx_hmsh_esc_pending_role_created (role, created_at DESC) WHERE
+ * status='pending'. The pending working set is bounded by real backlog depth,
+ * so this stays cheap as historical volume grows — safe on the hot refresh path.
+ */
+exports.STATION_LIVE_COUNTS_SQL = `
+WITH role_targets AS (
+  SELECT role, sla_minutes
+  FROM lt_roles
+  WHERE ($1::text[] IS NULL OR role = ANY($1::text[]))
+),
+live_counts AS (
+  SELECT
+    e.role,
+    COUNT(*)                                                                         AS pending,
+    COUNT(*) FILTER (WHERE e.assigned_to IS NOT NULL AND e.assigned_until > NOW())  AS claimed,
+    COUNT(*) FILTER (
+      WHERE rt.sla_minutes IS NOT NULL
+        AND e.created_at < NOW() - (rt.sla_minutes * INTERVAL '1 minute')
+    )                                                                                AS in_arrears
+  FROM hmsh_escalations e
+  JOIN role_targets rt ON rt.role = e.role
+  WHERE e.status = 'pending'
+  GROUP BY e.role
+)
+SELECT
+  rt.role,
+  COALESCE(lc.pending,    0) AS pending,
+  COALESCE(lc.claimed,    0) AS claimed,
+  COALESCE(lc.in_arrears, 0) AS in_arrears
+FROM role_targets rt
+LEFT JOIN live_counts lc ON lc.role = rt.role
+ORDER BY rt.role
+`;
+/**
+ * Period metrics — resolved count, throughput efficiency, and P99/P50/avg/max
+ * latency for wait (queue time) and work (processing) per role.
+ *
+ * $1 TEXT[]   — role filter (NULL = all roles / superadmin).
+ * $2 INTERVAL — time window (e.g. '24 hours', '15 minutes').
+ *
+ * Hits idx_hmsh_esc_resolved_cover (role, resolved_at DESC, claimed_at,
+ * created_at) WHERE status='resolved' — a covering index, so the percentile
+ * scan is index-only. PERCENTILE_CONT still sorts the qualifying set in memory,
+ * which is why the service caches this result rather than running it per event.
+ *
+ * Latency is computed over CLOSED work (status='resolved' in the period), not a
+ * mix of resolved + in-flight — a clean "how did completed work perform?" read.
+ * throughput_pct is NULL when the role has no target_per_hour (NULLIF guard).
+ */
+exports.STATION_PERIOD_METRICS_SQL = `
+WITH role_targets AS (
+  SELECT role, target_per_hour
+  FROM lt_roles
+  WHERE ($1::text[] IS NULL OR role = ANY($1::text[]))
+),
+period_metrics AS (
+  SELECT
+    e.role,
+    COUNT(*)                                                                         AS resolved,
+    ROUND((PERCENTILE_CONT(0.99) WITHIN GROUP (
+      ORDER BY EXTRACT(EPOCH FROM (e.claimed_at - e.created_at)) / 60)
+      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS p99_wait_min,
+    ROUND((PERCENTILE_CONT(0.50) WITHIN GROUP (
+      ORDER BY EXTRACT(EPOCH FROM (e.claimed_at - e.created_at)) / 60)
+      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS p50_wait_min,
+    ROUND((AVG(EXTRACT(EPOCH FROM (e.claimed_at - e.created_at)) / 60)
+      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS avg_wait_min,
+    ROUND((MAX(EXTRACT(EPOCH FROM (e.claimed_at - e.created_at)) / 60)
+      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS max_wait_min,
+    ROUND((PERCENTILE_CONT(0.99) WITHIN GROUP (
+      ORDER BY EXTRACT(EPOCH FROM (e.resolved_at - e.claimed_at)) / 60)
+      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS p99_work_min,
+    ROUND((PERCENTILE_CONT(0.50) WITHIN GROUP (
+      ORDER BY EXTRACT(EPOCH FROM (e.resolved_at - e.claimed_at)) / 60)
+      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS p50_work_min,
+    ROUND((AVG(EXTRACT(EPOCH FROM (e.resolved_at - e.claimed_at)) / 60)
+      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS avg_work_min,
+    ROUND((MAX(EXTRACT(EPOCH FROM (e.resolved_at - e.claimed_at)) / 60)
+      FILTER (WHERE e.claimed_at IS NOT NULL))::numeric, 3)                        AS max_work_min
+  FROM hmsh_escalations e
+  WHERE e.status = 'resolved'
+    AND e.resolved_at >= NOW() - $2::interval
+    AND ($1::text[] IS NULL OR e.role = ANY($1::text[]))
+  GROUP BY e.role
+)
+SELECT
+  rt.role,
+  COALESCE(pm.resolved, 0) AS resolved,
+  ROUND(
+    (COALESCE(pm.resolved, 0)::numeric
+      / NULLIF(rt.target_per_hour::numeric * EXTRACT(EPOCH FROM $2::interval) / 3600.0, 0)
+      * 100
+    )::numeric, 1
+  )                        AS throughput_pct,
+  pm.p99_wait_min,
+  pm.p50_wait_min,
+  pm.avg_wait_min,
+  pm.max_wait_min,
+  pm.p99_work_min,
+  pm.p50_work_min,
+  pm.avg_work_min,
+  pm.max_work_min
+FROM role_targets rt
+LEFT JOIN period_metrics pm ON pm.role = rt.role
+ORDER BY rt.role
+`;

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

@@ -39,5 +39,22 @@ export interface EscalationStats {
     }[];
 }
 export declare const VALID_PERIODS: Record<string, string>;
+export interface StationMetricPeriod {
+    p99: number | null;
+    p50: number | null;
+    avg: number | null;
+    max: number | null;
+}
+export interface StationMetric {
+    role: string;
+    pending: number;
+    claimed: number;
+    resolved: number;
+    in_arrears: number;
+    /** resolved_in_period / (target_per_hour × period_hours) × 100. Null when no target set. */
+    throughput_pct: number | null;
+    wait: StationMetricPeriod;
+    work: StationMetricPeriod;
+}
 /** Columns allowed for user-chosen ORDER BY. */
 export declare const SORTABLE_COLUMNS: Set<string>;

package/build/services/escalation/types.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SORTABLE_COLUMNS = exports.VALID_PERIODS = void 0;
 exports.VALID_PERIODS = {
+    '15m': '15 minutes',
     '1h': '1 hour',
     '24h': '24 hours',
     '7d': '7 days',

package/build/services/mcp/external-server.js

@@ -75,8 +75,12 @@ function isToolAllowed(toolName, serverName, exposure, callerScopes) {
     const manifest = config?.toolManifest;
     if (!manifest)
         return true; // no manifest = allow (conservative)
+    // Fail closed: a server that publishes a manifest declares its read-safe
+    // surface completely. A tool missing from the manifest is treated as a
+    // write tool — otherwise every newly registered tool ships pre-exposed to
+    // read-scoped callers until someone remembers the manifest entry.
     const entry = manifest.find((t) => t.name === toolName);
-    return entry?.read_safe !== false; // allow if read_safe is true or absent
+    return entry?.read_safe === true;
 }
 // ── Unified server creation ──────────────────────────────────────────────────
 /**

package/build/services/orchestrator/condition.d.ts

@@ -23,6 +23,26 @@ import type { Types } from '@hotmeshio/hotmesh';
  * });
  * ```
  *
+ * **With an SLA (hotmesh 0.25.1+) — add `timeout` to the config.** The same
+ * single wait arms a resume timer alongside the escalation row: when the timer
+ * fires first, this helper returns `false`, the row transitions to
+ * `status='expired'` (engine-side, atomically), and a late resolve fails as
+ * `already-expired`. A signal that arrives first resolves normally and the
+ * timer is inert.
+ *
+ * ```typescript
+ * const decision = await conditionLT<{ approved: boolean }>(signalId, {
+ *   role: 'reviewer',
+ *   description: instructions,
+ *   metadata: { orderId },
+ *   timeout: '24h',                       // SLA deadline for this worklist row
+ * });
+ * if (decision === false) {
+ *   // deadline passed — the row is already status='expired'; branch to the
+ *   // fallback path (auto-reject, escalate the order, notify, …)
+ * }
+ * ```
+ *
  * **Legacy (two-step) — no config.** Create the escalation first (e.g. via
  * `ltCreateEscalation`) with `signal_id`/`signal_routing` metadata, then wait.
  * On resume the signal payload carries an injected `$escalation_id`; this helper

package/build/services/orchestrator/condition.js

@@ -61,6 +61,26 @@ const LT_ACTIVITY_QUEUE = 'lt-interceptor';
  * });
  * ```
  *
+ * **With an SLA (hotmesh 0.25.1+) — add `timeout` to the config.** The same
+ * single wait arms a resume timer alongside the escalation row: when the timer
+ * fires first, this helper returns `false`, the row transitions to
+ * `status='expired'` (engine-side, atomically), and a late resolve fails as
+ * `already-expired`. A signal that arrives first resolves normally and the
+ * timer is inert.
+ *
+ * ```typescript
+ * const decision = await conditionLT<{ approved: boolean }>(signalId, {
+ *   role: 'reviewer',
+ *   description: instructions,
+ *   metadata: { orderId },
+ *   timeout: '24h',                       // SLA deadline for this worklist row
+ * });
+ * if (decision === false) {
+ *   // deadline passed — the row is already status='expired'; branch to the
+ *   // fallback path (auto-reject, escalate the order, notify, …)
+ * }
+ * ```
+ *
  * **Legacy (two-step) — no config.** Create the escalation first (e.g. via
  * `ltCreateEscalation`) with `signal_id`/`signal_routing` metadata, then wait.
  * On resume the signal payload carries an injected `$escalation_id`; this helper

package/build/services/role/index.d.ts

@@ -1,4 +1,4 @@
-import type { EscalationChain, RoleDetail } from './types';
+import type { EscalationChain, RoleDetail, UpdateRoleInput } from './types';
 /**
  * Get the roles a given source role can escalate to.
  */
@@ -35,9 +35,28 @@ export declare function listDistinctRoles(): Promise<string[]>;
  */
 export declare function listRolesWithDetails(): Promise<RoleDetail[]>;
 /**
- * Create a standalone role entry.
+ * Create a standalone role entry. Returns true when the role was created by
+ * this call, false when it already existed — seeders use this to write
+ * default metadata exactly once and leave later admin edits alone.
  */
-export declare function createRole(role: string): Promise<void>;
+export declare function createRole(role: string): Promise<boolean>;
+/**
+ * Update role metadata with PATCH semantics: a field omitted from the input
+ * (undefined) keeps its current value; explicit null clears it (properties
+ * resets to {}). One atomic UPDATE — see UPDATE_ROLE_METADATA.
+ */
+export declare function updateRoleMetadata(role: string, input: UpdateRoleInput): Promise<RoleDetail | null>;
+/**
+ * Fetch form_schema for a role (used as default escalation form when workflow
+ * config does not specify a resolver_schema).
+ */
+export declare function getRoleFormSchema(role: string): Promise<Record<string, any> | null>;
+/**
+ * Fetch metadata_schema for a role. Used at escalation creation time to
+ * validate the caller-supplied metadata bag, and by the faceted-query UI
+ * to surface expected keys before any data exists.
+ */
+export declare function getRoleMetadataSchema(role: string): Promise<Record<string, any> | null>;
 /**
  * Delete a role. Returns an error message if the role is referenced.
  */