@hotmeshio/long-tail 0.7.3 → 0.7.5

package/build/api/roles.d.ts

@@ -91,6 +91,10 @@ export declare function updateRole(input: {
     sla_minutes?: number | null;
     target_per_hour?: number | null;
     worker_count?: number | null;
+    /** Max age (minutes) before a pending unclaimed item counts as priority on the Pace Board. Falls back to sla_minutes. */
+    priority_threshold_minutes?: number | null;
+    /** Escalation metadata key holding the age origin (ISO 8601 UTC timestamp). Falls back to created_at. */
+    priority_facet?: string | null;
     /** Replace the upstream-input set (omitted = preserve; null or [] = clear). */
     upstream_roles?: string[] | null;
     /** Recorded on the schema snapshot when this update changes a schema field. */

package/build/api/roles.js

@@ -46,6 +46,7 @@ exports.getRoleSchema = getRoleSchema;
 exports.listRoleSchemaVersions = listRoleSchemaVersions;
 exports.deleteRole = deleteRole;
 const roleService = __importStar(require("../services/role"));
+const facet_sql_1 = require("../services/escalation/facet-sql");
 /**
  * List all distinct role names in the system.
  *
@@ -207,7 +208,7 @@ async function updateRole(input) {
         if (!input.role) {
             return { status: 400, error: 'role is required' };
         }
-        for (const field of ['sla_minutes', 'target_per_hour', 'worker_count']) {
+        for (const field of ['sla_minutes', 'target_per_hour', 'worker_count', 'priority_threshold_minutes']) {
             const value = input[field];
             if (value !== undefined && value !== null && (typeof value !== 'number' || !Number.isFinite(value) || value < 0)) {
                 return { status: 400, error: `${field} must be a non-negative number or null` };
@@ -216,6 +217,9 @@ async function updateRole(input) {
         if (input.worker_count != null && !Number.isInteger(input.worker_count)) {
             return { status: 400, error: 'worker_count must be a whole number' };
         }
+        if (input.priority_facet != null && (typeof input.priority_facet !== 'string' || !facet_sql_1.FACET_KEY.test(input.priority_facet))) {
+            return { status: 400, error: 'priority_facet must be a metadata key (letters, numbers, underscores) or null' };
+        }
         if (input.ops_visible !== undefined && typeof input.ops_visible !== 'boolean') {
             return { status: 400, error: 'ops_visible must be a boolean' };
         }
@@ -246,6 +250,8 @@ async function updateRole(input) {
             sla_minutes: input.sla_minutes,
             target_per_hour: input.target_per_hour,
             worker_count: input.worker_count,
+            priority_threshold_minutes: input.priority_threshold_minutes,
+            priority_facet: input.priority_facet,
             upstream_roles: input.upstream_roles,
             change_summary: input.change_summary,
         });

package/build/lib/db/schemas/019_role_priority.sql

@@ -0,0 +1,28 @@
+-- Migration 019: Role priority threshold
+--
+-- Per-role tuning for the Pace Board priority count: pending, unclaimed
+-- escalations whose age exceeds the threshold appear as a count the floor
+-- pulls to the front of the rack. The signal is deliberately boolean per
+-- item (past threshold or not) — a count to rebalance by, not a queue to
+-- keep re-sorting.
+--
+--   priority_threshold_minutes — max age before an item counts as priority.
+--                                Falls back to sla_minutes when NULL.
+--   priority_facet             — lt_escalations.metadata key holding the age
+--                                origin as an ISO 8601 UTC timestamp (e.g.
+--                                the order's authorized date). Falls back to
+--                                created_at when NULL. When set, items
+--                                missing the key or holding an unparseable
+--                                value are not counted.
+--
+-- With both NULL the count still works for any role with sla_minutes set
+-- (age from created_at) — one signal, no parallel SLA pattern.
+--
+-- No new lt_escalations index: the count rides the bounded pending-only scan
+-- in STATION_LIVE_COUNTS_SQL. The GIN metadata index only serves containment
+-- (@>), not age comparisons, and the pending working set is bounded by real
+-- backlog depth.
+
+ALTER TABLE lt_roles
+  ADD COLUMN IF NOT EXISTS priority_threshold_minutes NUMERIC,
+  ADD COLUMN IF NOT EXISTS priority_facet             TEXT;

package/build/routes/roles.js

@@ -95,7 +95,7 @@ router.delete('/escalation-chains', auth_1.requireRoleManager, async (req, res)
 /**
  * PATCH /api/roles/:role
  * Update role metadata. Requires admin.
- * Body: { title?, description?, form_schema?, metadata_schema?, properties?, ops_visible?, parent_role?, sla_minutes?, target_per_hour?, worker_count? }
+ * Body: { title?, description?, form_schema?, metadata_schema?, properties?, ops_visible?, parent_role?, sla_minutes?, target_per_hour?, worker_count?, priority_threshold_minutes?, priority_facet? }
  */
 router.patch('/:role', auth_1.requireRoleManager, async (req, res) => {
     // URL is the resource identity — a `role` key in the body must not redirect

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

@@ -39,6 +39,12 @@
  * down gradually, and resolves feed the next station a trickle instead of a
  * wave.
  *
+ * Every escalation this run creates carries `metadata.authorized_at` — an ISO
+ * 8601 UTC timestamp stamped when the order arrives, identical across all of
+ * that order's stages (main line and shoe side-quest). Point a role's
+ * `priority_facet` at `authorized_at` with a threshold (e.g. 1 minute) and the
+ * Pace Board priority count lights up as orders age through the run.
+ *
  * ── The shoe side-quest ──────────────────────────────────────────────────────
  * A shoe order exercises the cross-sequence model (ordering → inserting feeds
  * ship via upstream_roles — its own Operations sequence, not a bend in the
@@ -94,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): Promise<boolean>;
+declare function createSideEscalation(role: string, workflowId: string, orderId: string, runId: string, description: string, authorizedAt: string): Promise<boolean>;
 declare function claimBatch(batchTag: string): Promise<number>;
 declare function resolveBatch(batchTag: string, runId: string): Promise<number>;
 interface PlannedOrder {

package/build/scripts/ortho-populate.js

@@ -40,6 +40,12 @@
  * down gradually, and resolves feed the next station a trickle instead of a
  * wave.
  *
+ * Every escalation this run creates carries `metadata.authorized_at` — an ISO
+ * 8601 UTC timestamp stamped when the order arrives, identical across all of
+ * that order's stages (main line and shoe side-quest). Point a role's
+ * `priority_facet` at `authorized_at` with a threshold (e.g. 1 minute) and the
+ * Pace Board priority count lights up as orders age through the run.
+ *
  * ── The shoe side-quest ──────────────────────────────────────────────────────
  * A shoe order exercises the cross-sequence model (ordering → inserting feeds
  * ship via upstream_roles — its own Operations sequence, not a bend in the
@@ -158,7 +164,7 @@ async function ensureSideQuestRoles() {
     console.log(`[${ts()}] Side-quest roles ready (ordering → inserting ⇒ ship)`);
 }
 // ── Side-quest escalations (standalone rows — no workflow behind them) ────────
-async function createSideEscalation(role, workflowId, orderId, runId, description) {
+async function createSideEscalation(role, workflowId, orderId, runId, description, authorizedAt) {
     try {
         await api('POST', '/api/escalations', {
             type: 'ortho-stage',
@@ -167,7 +173,7 @@ async function createSideEscalation(role, workflowId, orderId, runId, descriptio
             description,
             workflow_id: workflowId,
             envelope: JSON.stringify({ order_id: orderId }),
-            metadata: { order_id: orderId, source: 'populate', run_id: runId },
+            metadata: { order_id: orderId, source: 'populate', run_id: runId, authorized_at: authorizedAt },
         });
         return true;
     }
@@ -237,10 +243,11 @@ async function resolveBatch(batchTag, runId) {
                 resolved++;
                 console.log(`[${ts()}]   [resolve] ${esc.role.padEnd(9)} ${esc.id.slice(0, 8)}… held ${heldS.toFixed(1)}s [${totalResolved} total]`);
                 // Shoes arrived — the side quest advances to inserting, which sits
-                // available until the manufactured inserts catch up with it.
+                // available until the manufactured inserts catch up with it. The
+                // 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}`);
+                    await createSideEscalation('inserting', esc.workflow_id, orderId, runId, `Stuff inserts into shoes for ${orderId}`, esc.metadata?.authorized_at ?? new Date().toISOString());
                 }
             }
             catch (err) {
@@ -264,10 +271,18 @@ async function runOrders(batchTag, runId, plan, target) {
         for (const order of plan) {
             if (done)
                 break;
+            // The order's authorization moment — stamped once at arrival and carried
+            // on every stage escalation via the workflow's metadata passthrough, so
+            // an `authorized_at` priority facet measures journey age.
+            const authorizedAt = new Date().toISOString();
             try {
                 await api('POST', '/api/workflows/orthoPipeline/invoke', {
                     workflowId: order.wfId,
-                    data: { order_id: order.orderId, item_type: 'insole-standard' },
+                    data: {
+                        order_id: order.orderId,
+                        item_type: 'insole-standard',
+                        metadata: { source: 'populate', run_id: runId, authorized_at: authorizedAt },
+                    },
                     metadata: { source: 'populate', run_id: runId, shoes: order.shoes },
                 });
                 workflowIds.push(order.wfId);
@@ -279,7 +294,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}`);
+                const ok = await createSideEscalation('ordering', `${order.wfId}-shoes`, order.orderId, runId, `Order shoes for ${order.orderId}`, authorizedAt);
                 if (!ok)
                     target.value -= 2;
             }

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

@@ -1,4 +1,5 @@
 import type { FacetOrder, FacetQuery } from '../../types';
+export declare const FACET_KEY: RegExp;
 /**
  * Build the WHERE clause for a faceted query, pushing bound params into `params`.
  * Every value is parameterized; only validated column names / metadata keys and

package/build/services/escalation/facet-sql.js

@@ -7,7 +7,7 @@
 // as services/escalation/sql.ts. Metadata facets use the GIN index (`@>`).
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENSURE_ORIGIN_INDEX = void 0;
+exports.ENSURE_ORIGIN_INDEX = exports.FACET_KEY = void 0;
 exports.buildFacetWhere = buildFacetWhere;
 exports.buildFacetOrder = buildFacetOrder;
 exports.buildGroupOrder = buildGroupOrder;
@@ -16,7 +16,8 @@ exports.buildGroupOrder = buildGroupOrder;
 const ORDER_COLUMNS = new Set(['priority', 'created_at', 'updated_at', 'status', 'role']);
 const RANGE_OPS = new Set(['<', '<=', '>', '>=', '=']);
 // Metadata keys are interpolated (as a JSON path), so they are strictly validated.
-const FACET_KEY = /^[a-zA-Z0-9_]+$/;
+// Exported so role config (priority_facet) validates keys against the same rule.
+exports.FACET_KEY = /^[a-zA-Z0-9_]+$/;
 /** A metadata extraction expression for a validated key (text or numeric). */
 function metaExpr(key, numeric = false) {
     return numeric ? `(metadata->>'${key}')::numeric` : `(metadata->>'${key}')`;
@@ -49,13 +50,13 @@ function buildFacetWhere(q, params) {
         clauses.push(`NOT (metadata @> ANY($${params.length}::jsonb[]))`);
     }
     for (const r of q.range ?? []) {
-        if (!FACET_KEY.test(r.facet) || !RANGE_OPS.has(r.op))
+        if (!exports.FACET_KEY.test(r.facet) || !RANGE_OPS.has(r.op))
             continue;
         params.push(r.value);
         clauses.push(`${metaExpr(r.facet, true)} ${r.op} $${params.length}`);
     }
     for (const key of q.exists ?? []) {
-        if (!FACET_KEY.test(key))
+        if (!exports.FACET_KEY.test(key))
             continue;
         clauses.push(`metadata ? '${key}'`);
     }
@@ -80,7 +81,7 @@ function buildFacetOrder(orderBy) {
         }
         else if (o.field.startsWith('metadata.')) {
             const key = o.field.slice('metadata.'.length);
-            if (!FACET_KEY.test(key))
+            if (!exports.FACET_KEY.test(key))
                 continue;
             parts.push(`${metaExpr(key, o.numeric)} ${dir} NULLS LAST`);
         }
@@ -106,7 +107,7 @@ function buildGroupOrder(orderBy) {
         }
         else if (o.field.startsWith('metadata.')) {
             const key = o.field.slice('metadata.'.length);
-            if (!FACET_KEY.test(key))
+            if (!exports.FACET_KEY.test(key))
                 continue;
             parts.push(`${agg}(${metaExpr(key, o.numeric)}) ${dir} NULLS LAST`);
         }

package/build/services/escalation/queries.js

@@ -212,6 +212,22 @@ async function listDistinctTypes() {
     const client = await (0, client_1.escalations)();
     return client.listDistinctTypes();
 }
+/**
+ * Narrow the caller's explicit role filter WITHIN their read scope. The SDK
+ * store gives `roles[]` precedence over `role` when both are set, so passing
+ * both would silently DROP the explicit filter for scoped (non-global)
+ * callers — a role-filtered list would return the scope's rows instead.
+ * Intersecting first keeps the plain path's semantics identical to the
+ * faceted path's: a role filter can only narrow scope, never widen past it,
+ * and an out-of-scope role yields an empty result, not someone else's rows.
+ */
+function narrowRoleWithinScope(role, visibleRoles) {
+    if (!role || !visibleRoles)
+        return { role, roles: visibleRoles, empty: false };
+    if (!visibleRoles.includes(role))
+        return { empty: true };
+    return { role, roles: undefined, empty: false };
+}
 async function listEscalations(filters) {
     // Active claim semantics: assigned_to-active and `claimed` both mean "held now".
     const heldNow = !!(filters.assigned_to || filters.claimed);
@@ -240,15 +256,18 @@ async function listEscalations(filters) {
             order: filters.order,
         });
     }
+    const scoped = narrowRoleWithinScope(filters.role, filters.visibleRoles);
+    if (scoped.empty)
+        return { escalations: [], total: 0 };
     const client = await (0, client_1.escalations)();
     // Shared filter — passed to both list() and count() so totals stay in sync.
     const where = {
         status: filters.status,
-        role: filters.role,
+        role: scoped.role,
         type: filters.type,
         subtype: filters.subtype,
         priority: filters.priority,
-        roles: filters.visibleRoles,
+        roles: scoped.roles,
     };
     if (filters.assigned_to)
         where.assignedTo = filters.assigned_to;
@@ -292,15 +311,18 @@ async function listAvailableEscalations(filters) {
             order: filters.order,
         });
     }
+    const scoped = narrowRoleWithinScope(filters.role, filters.visibleRoles);
+    if (scoped.empty)
+        return { escalations: [], total: 0 };
     const client = await (0, client_1.escalations)();
     const where = {
         status: 'pending',
         available: true,
-        role: filters.role,
+        role: scoped.role,
         type: filters.type,
         subtype: filters.subtype,
         priority: filters.priority,
-        roles: filters.visibleRoles,
+        roles: scoped.roles,
     };
     const [rows, total] = await Promise.all([
         client.list({
@@ -359,7 +381,7 @@ async function getStationMetrics(visibleRoles, period) {
             pending: Number(c.pending ?? 0),
             claimed: Number(c.claimed ?? 0),
             resolved: Number(p?.resolved ?? 0),
-            in_arrears: Number(c.in_arrears ?? 0),
+            priority_count: Number(c.priority_count ?? 0),
             throughput_pct: p?.throughput_pct != null ? Number(p.throughput_pct) : null,
             wait: {
                 p99: toNum(p?.p99_wait_min),

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

@@ -45,15 +45,32 @@ export declare function searchEscalationsQuery(orderBy: string): string;
  */
 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.
+ * Live counts — pending, active claims, and priority (past-threshold) 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.
+ *
+ * priority_count is the Pace Board rebalance signal: pending AND unclaimed
+ * items older than the role's threshold. One signal, two per-role dials with
+ * fallbacks so it works from sla_minutes alone:
+ *
+ *   age origin — priority_facet metadata key (an ISO 8601 UTC timestamp, e.g.
+ *                the order's authorized date) when set, else created_at.
+ *   threshold  — priority_threshold_minutes when set, else sla_minutes.
+ *
+ * Claimed items are excluded — they are already in someone's hands; the count
+ * is what the floor must still pull forward. The GIN metadata index only
+ * serves containment, not age comparisons, so the facet read rides the same
+ * bounded pending scan as the other counts. The cast is guarded by
+ * pg_input_is_valid inside a CASE (Postgres does not promise AND evaluation
+ * order) so one malformed metadata value can never break the stats query;
+ * with a facet configured, items missing the key or holding an unparseable
+ * value do not count (NULL age never passes the comparison).
  */
-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";
+export declare const STATION_LIVE_COUNTS_SQL = "\nWITH role_targets AS (\n  SELECT role, sla_minutes, priority_threshold_minutes, priority_facet\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 COALESCE(rt.priority_threshold_minutes, rt.sla_minutes) IS NOT NULL\n        AND (e.assigned_to IS NULL OR e.assigned_until IS NULL OR e.assigned_until <= NOW())\n        AND CASE\n          WHEN rt.priority_facet IS NULL THEN e.created_at\n          WHEN pg_input_is_valid(e.metadata->>rt.priority_facet, 'timestamptz')\n            THEN (e.metadata->>rt.priority_facet)::timestamptz\n          ELSE NULL\n        END < NOW() - (COALESCE(rt.priority_threshold_minutes, rt.sla_minutes) * INTERVAL '1 minute')\n    )                                                                                AS priority_count\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.priority_count, 0) AS priority_count\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.

package/build/services/escalation/sql.js

@@ -192,7 +192,7 @@ LEFT JOIN resolved ON resolved.id = target.id`;
 // 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
+//   STATION_LIVE_COUNTS_SQL    — pending / claimed / priority_count. 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.
@@ -204,17 +204,34 @@ LEFT JOIN resolved ON resolved.id = target.id`;
 // and the service merges them by role into one StationMetric per station.
 // ---------------------------------------------------------------------------
 /**
- * Live counts — pending, active claims, and past-SLA (in_arrears) per role.
+ * Live counts — pending, active claims, and priority (past-threshold) 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.
+ *
+ * priority_count is the Pace Board rebalance signal: pending AND unclaimed
+ * items older than the role's threshold. One signal, two per-role dials with
+ * fallbacks so it works from sla_minutes alone:
+ *
+ *   age origin — priority_facet metadata key (an ISO 8601 UTC timestamp, e.g.
+ *                the order's authorized date) when set, else created_at.
+ *   threshold  — priority_threshold_minutes when set, else sla_minutes.
+ *
+ * Claimed items are excluded — they are already in someone's hands; the count
+ * is what the floor must still pull forward. The GIN metadata index only
+ * serves containment, not age comparisons, so the facet read rides the same
+ * bounded pending scan as the other counts. The cast is guarded by
+ * pg_input_is_valid inside a CASE (Postgres does not promise AND evaluation
+ * order) so one malformed metadata value can never break the stats query;
+ * with a facet configured, items missing the key or holding an unparseable
+ * value do not count (NULL age never passes the comparison).
  */
 exports.STATION_LIVE_COUNTS_SQL = `
 WITH role_targets AS (
-  SELECT role, sla_minutes
+  SELECT role, sla_minutes, priority_threshold_minutes, priority_facet
   FROM lt_roles
   WHERE ($1::text[] IS NULL OR role = ANY($1::text[]))
 ),
@@ -224,9 +241,15 @@ live_counts AS (
     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
+      WHERE COALESCE(rt.priority_threshold_minutes, rt.sla_minutes) IS NOT NULL
+        AND (e.assigned_to IS NULL OR e.assigned_until IS NULL OR e.assigned_until <= NOW())
+        AND CASE
+          WHEN rt.priority_facet IS NULL THEN e.created_at
+          WHEN pg_input_is_valid(e.metadata->>rt.priority_facet, 'timestamptz')
+            THEN (e.metadata->>rt.priority_facet)::timestamptz
+          ELSE NULL
+        END < NOW() - (COALESCE(rt.priority_threshold_minutes, rt.sla_minutes) * INTERVAL '1 minute')
+    )                                                                                AS priority_count
   FROM hmsh_escalations e
   JOIN role_targets rt ON rt.role = e.role
   WHERE e.status = 'pending'
@@ -234,9 +257,9 @@ live_counts AS (
 )
 SELECT
   rt.role,
-  COALESCE(lc.pending,    0) AS pending,
-  COALESCE(lc.claimed,    0) AS claimed,
-  COALESCE(lc.in_arrears, 0) AS in_arrears
+  COALESCE(lc.pending,        0) AS pending,
+  COALESCE(lc.claimed,        0) AS claimed,
+  COALESCE(lc.priority_count, 0) AS priority_count
 FROM role_targets rt
 LEFT JOIN live_counts lc ON lc.role = rt.role
 ORDER BY rt.role

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

@@ -50,7 +50,13 @@ export interface StationMetric {
     pending: number;
     claimed: number;
     resolved: number;
-    in_arrears: number;
+    /**
+     * Pending, unclaimed items past the role's threshold — the Pace Board
+     * rebalance signal. Age is measured from the role's priority_facet metadata
+     * timestamp (created_at when unset) against priority_threshold_minutes
+     * (sla_minutes when unset). 0 when neither threshold is configured.
+     */
+    priority_count: number;
     /** resolved_in_period / (target_per_hour × period_hours) × 100. Null when no target set. */
     throughput_pct: number | null;
     wait: StationMetricPeriod;

package/build/services/role/index.js

@@ -139,6 +139,8 @@ async function updateRoleMetadata(role, input) {
         provided('sla_minutes'), input.sla_minutes ?? null,
         provided('target_per_hour'), input.target_per_hour ?? null,
         provided('worker_count'), input.worker_count ?? null,
+        provided('priority_threshold_minutes'), input.priority_threshold_minutes ?? null,
+        provided('priority_facet'), input.priority_facet ?? null,
         input.change_summary ?? null,
         provided('upstream_roles'), upstreams,
     ]);

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

@@ -27,15 +27,15 @@ export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
  * evaluated against the pre-update row), current_schema_version advances and
  * the post-update schema pair is snapshotted into lt_role_schemas. A no-change
  * save leaves the version alone and the snapshot INSERT conflicts away.
- * $22 = optional change summary recorded on the snapshot.
+ * $26 = optional change summary recorded on the snapshot.
  *
- * Upstream inputs ($23 = provided sentinel, $24 = replacement set) sync in the
+ * Upstream inputs ($27 = provided sentinel, $28 = replacement set) sync in the
  * same statement with replace semantics. The two CTEs deliberately avoid
  * touching the same row: the DELETE only removes rows leaving the set, and the
  * INSERT's ON CONFLICT DO NOTHING skips rows that stay (delete+insert of the
  * SAME key in one statement would silently drop it — CTEs share a snapshot).
  */
-export declare const UPDATE_ROLE_METADATA = "\n  WITH updated AS (\n    UPDATE lt_roles SET\n      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,\n      current_schema_version = CASE\n        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)\n          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)\n        THEN COALESCE(current_schema_version, 0) + 1\n        ELSE current_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,\n      current_schema_version\n  ), snapshot AS (\n    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)\n    SELECT role, current_schema_version, form_schema, metadata_schema, $22\n    FROM updated\n    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), upstream_prune AS (\n    DELETE FROM lt_role_upstreams\n    WHERE $23::boolean AND role = $1 AND upstream_role <> ALL($24::text[])\n  ), upstream_add AS (\n    INSERT INTO lt_role_upstreams (role, upstream_role)\n    SELECT $1, u FROM unnest($24::text[]) AS u\n    WHERE $23::boolean\n    ON CONFLICT DO NOTHING\n  )\n  SELECT * FROM updated";
+export declare const UPDATE_ROLE_METADATA = "\n  WITH updated AS (\n    UPDATE lt_roles SET\n      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,\n      priority_threshold_minutes\n                      = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,\n      priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,\n      current_schema_version = CASE\n        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)\n          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)\n        THEN COALESCE(current_schema_version, 0) + 1\n        ELSE current_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,\n      priority_threshold_minutes, priority_facet,\n      current_schema_version\n  ), snapshot AS (\n    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)\n    SELECT role, current_schema_version, form_schema, metadata_schema, $26\n    FROM updated\n    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL\n    ON CONFLICT (role, version) DO NOTHING\n  ), upstream_prune AS (\n    DELETE FROM lt_role_upstreams\n    WHERE $27::boolean AND role = $1 AND upstream_role <> ALL($28::text[])\n  ), upstream_add AS (\n    INSERT INTO lt_role_upstreams (role, upstream_role)\n    SELECT $1, u FROM unnest($28::text[]) AS u\n    WHERE $27::boolean\n    ON CONFLICT DO NOTHING\n  )\n  SELECT * FROM updated";
 export declare const GET_ROLE_FORM_SCHEMA = "\n  SELECT form_schema FROM lt_roles WHERE role = $1";
 export declare const GET_ROLE_METADATA_SCHEMA = "\n  SELECT metadata_schema FROM lt_roles WHERE role = $1";
 export declare const GET_ROLE_UPSTREAMS = "\n  SELECT upstream_role FROM lt_role_upstreams WHERE role = $1 ORDER BY upstream_role";
@@ -46,7 +46,7 @@ export declare const GET_ROLE_SCHEMA_VERSION = "\n  SELECT s.role, s.version, s.
  * versioned its schema still answers, with version NULL).
  */
 export declare const GET_ROLE_SCHEMA_CURRENT = "\n  SELECT r.role, r.current_schema_version AS version, r.form_schema,\n         r.metadata_schema, s.change_summary, s.created_at,\n         r.current_schema_version AS latest_version\n  FROM lt_roles r\n  LEFT JOIN lt_role_schemas s\n    ON s.role = r.role AND s.version = r.current_schema_version\n  WHERE r.role = $1";
-export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  ),\n  upstreams AS (\n    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups\n    FROM lt_role_upstreams\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    r.current_schema_version,\n    COALESCE(up.ups, '{}') AS upstream_roles,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  LEFT JOIN upstreams up ON up.role = r.role\n  ORDER BY r.role";
+export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  ),\n  upstreams AS (\n    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups\n    FROM lt_role_upstreams\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    r.priority_threshold_minutes,\n    r.priority_facet,\n    r.current_schema_version,\n    COALESCE(up.ups, '{}') AS upstream_roles,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  LEFT JOIN upstreams up ON up.role = r.role\n  ORDER BY r.role";
 export declare const COUNT_USER_ROLE_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_user_roles WHERE role = $1";
 export declare const COUNT_CHAIN_REFS = "\n  SELECT COUNT(*)::int AS cnt\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 OR target_role = $1";
 export declare const COUNT_WORKFLOW_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_config_roles WHERE role = $1";

package/build/services/role/sql.js

@@ -61,9 +61,9 @@ exports.DELETE_ROLE = `
  * evaluated against the pre-update row), current_schema_version advances and
  * the post-update schema pair is snapshotted into lt_role_schemas. A no-change
  * save leaves the version alone and the snapshot INSERT conflicts away.
- * $22 = optional change summary recorded on the snapshot.
+ * $26 = optional change summary recorded on the snapshot.
  *
- * Upstream inputs ($23 = provided sentinel, $24 = replacement set) sync in the
+ * Upstream inputs ($27 = provided sentinel, $28 = replacement set) sync in the
  * same statement with replace semantics. The two CTEs deliberately avoid
  * touching the same row: the DELETE only removes rows leaving the set, and the
  * INSERT's ON CONFLICT DO NOTHING skips rows that stay (delete+insert of the
@@ -82,6 +82,9 @@ exports.UPDATE_ROLE_METADATA = `
       sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,
       target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,
       worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,
+      priority_threshold_minutes
+                      = CASE WHEN $22::boolean THEN $23::numeric                      ELSE priority_threshold_minutes END,
+      priority_facet  = CASE WHEN $24::boolean THEN $25                               ELSE priority_facet  END,
       current_schema_version = CASE
         WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)
           OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)
@@ -91,20 +94,21 @@ exports.UPDATE_ROLE_METADATA = `
     RETURNING
       role, title, description, form_schema, metadata_schema, properties,
       ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,
+      priority_threshold_minutes, priority_facet,
       current_schema_version
   ), snapshot AS (
     INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)
-    SELECT role, current_schema_version, form_schema, metadata_schema, $22
+    SELECT role, current_schema_version, form_schema, metadata_schema, $26
     FROM updated
     WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL
     ON CONFLICT (role, version) DO NOTHING
   ), upstream_prune AS (
     DELETE FROM lt_role_upstreams
-    WHERE $23::boolean AND role = $1 AND upstream_role <> ALL($24::text[])
+    WHERE $27::boolean AND role = $1 AND upstream_role <> ALL($28::text[])
   ), upstream_add AS (
     INSERT INTO lt_role_upstreams (role, upstream_role)
-    SELECT $1, u FROM unnest($24::text[]) AS u
-    WHERE $23::boolean
+    SELECT $1, u FROM unnest($28::text[]) AS u
+    WHERE $27::boolean
     ON CONFLICT DO NOTHING
   )
   SELECT * FROM updated`;
@@ -184,6 +188,8 @@ exports.LIST_ROLES_WITH_DETAILS = `
     r.sla_minutes,
     r.target_per_hour,
     r.worker_count,
+    r.priority_threshold_minutes,
+    r.priority_facet,
     r.current_schema_version,
     COALESCE(up.ups, '{}') AS upstream_roles,
     COALESCE(uc.cnt, 0) AS user_count,

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

@@ -25,6 +25,18 @@ export interface RoleDetail {
     target_per_hour: number | null;
     /** Capacity at this station (people or machines). Part of the ops triangle. */
     worker_count: number | null;
+    /**
+     * Max age (minutes) before a pending, unclaimed escalation counts toward the
+     * Pace Board priority count. Falls back to sla_minutes when null.
+     */
+    priority_threshold_minutes: number | null;
+    /**
+     * lt_escalations.metadata key holding the age origin for the priority count
+     * as an ISO 8601 UTC timestamp (e.g. the order's authorized date). Falls
+     * back to created_at when null. When set, items missing the key or holding
+     * an unparseable value are not counted.
+     */
+    priority_facet: string | null;
     /**
      * Version of the live form_schema/metadata_schema pair. Advances whenever a
      * schema field changes; each version is snapshotted in lt_role_schemas so
@@ -74,6 +86,8 @@ export interface UpdateRoleInput {
     sla_minutes?: number | null;
     target_per_hour?: number | null;
     worker_count?: number | null;
+    priority_threshold_minutes?: number | null;
+    priority_facet?: string | null;
     /**
      * Replace the upstream-input set (omitted = preserve; null or [] = clear).
      * Every entry must name an existing role other than this one.

package/build/system/mcp-servers/admin/schemas.d.ts

@@ -562,6 +562,8 @@ export declare const updateRoleSchema: z.ZodObject<{
     sla_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     target_per_hour: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     worker_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    priority_threshold_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    priority_facet: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     upstream_roles: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
     change_summary: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -576,6 +578,8 @@ export declare const updateRoleSchema: z.ZodObject<{
     sla_minutes?: number | null | undefined;
     target_per_hour?: number | null | undefined;
     worker_count?: number | null | undefined;
+    priority_threshold_minutes?: number | null | undefined;
+    priority_facet?: string | null | undefined;
     upstream_roles?: string[] | null | undefined;
     change_summary?: string | undefined;
 }, {
@@ -590,6 +594,8 @@ export declare const updateRoleSchema: z.ZodObject<{
     sla_minutes?: number | null | undefined;
     target_per_hour?: number | null | undefined;
     worker_count?: number | null | undefined;
+    priority_threshold_minutes?: number | null | undefined;
+    priority_facet?: string | null | undefined;
     upstream_roles?: string[] | null | undefined;
     change_summary?: string | undefined;
 }>;