@hotmeshio/long-tail 0.6.2 → 0.7.0

package/build/scripts/ortho-populate.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * ortho-populate — Populate the Operations dashboard with ortho pipeline history.
+ *
+ * Adapted from the boilerplate's 08-day-resolver.ts pattern:
+ *   - concurrent claim loop + resolve loop + watchdog via Promise.all
+ *   - hold time read from esc.claimed_at (API), not tracked in memory
+ *   - simple resolve payload { approved: true, station: role }
+ *
+ * Usage:
+ *   npx ts-node scripts/ortho-populate.ts
+ *   ORDERS=50 HOLD_S=3 npx ts-node scripts/ortho-populate.ts
+ *   ORDERS=5  HOLD_S=0 POLL_MS=500 npx ts-node scripts/ortho-populate.ts
+ *
+ * Env vars:
+ *   ORDERS    — number of orders to run (default 20)
+ *   HOLD_S    — seconds to hold each escalation before resolving (default 2)
+ *   POLL_MS   — poll interval ms (default 1000)
+ *   BASE_URL  — server URL (default http://localhost:3000)
+ */
+try {
+    require('dotenv/config');
+}
+catch { }
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+const ORDERS = parseInt(process.env.ORDERS || '20', 10);
+const HOLD_S = parseFloat(process.env.HOLD_S || '2');
+const POLL_MS = parseInt(process.env.POLL_MS || '1000', 10);
+const ORTHO_ROLES = ['design', 'review', 'print', 'grind', 'glue', 'finish', 'qa', 'ship'];
+let token = '';
+let userId = '';
+let totalClaimed = 0;
+let totalResolved = 0;
+function ts() { return new Date().toISOString().slice(11, 19); }
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+function ageSeconds(iso) { return (Date.now() - new Date(iso).getTime()) / 1000; }
+// ── HTTP helper (mirrors boilerplate 07-shared) ───────────────────────────────
+async function api(method, path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok)
+        throw new Error(`${method} ${path} → ${res.status}: ${JSON.stringify(data)}`);
+    return data;
+}
+// ── Auth ─────────────────────────────────────────────────────────────────────
+async function login() {
+    const auth = await api('POST', '/api/auth/login', { username: 'superadmin', password: 'l0ngt@1l' });
+    token = auth.token;
+    userId = auth.user?.id || '';
+    if (!token) {
+        console.error('[auth] Login failed');
+        process.exit(1);
+    }
+    console.log(`[${ts()}] Logged in (userId: ${userId.slice(0, 8)}…)`);
+}
+// ── Claim: grab available ortho-stage escalations for this run ────────────────
+async function claimBatch(batchTag) {
+    try {
+        const resp = await api('GET', '/api/escalations/available?type=ortho-stage&limit=100&sort_by=created_at&order=asc');
+        const escalations = resp?.escalations ?? [];
+        let claimed = 0;
+        for (const esc of escalations) {
+            if (!ORTHO_ROLES.includes(esc.role))
+                continue;
+            if (!String(esc.workflow_id ?? '').includes(batchTag))
+                continue;
+            try {
+                await api('POST', `/api/escalations/${esc.id}/claim`, { durationMinutes: 600 });
+                totalClaimed++;
+                claimed++;
+                console.log(`[${ts()}]   [claim]   ${esc.role.padEnd(8)} ${esc.id.slice(0, 8)}… [${totalClaimed} total]`);
+            }
+            catch (err) {
+                const msg = String(err.message).slice(0, 80);
+                if (!msg.includes('409') && !msg.includes('conflict') && !msg.includes('already')) {
+                    console.warn(`[${ts()}]   [claim]   err: ${msg}`);
+                }
+            }
+        }
+        return claimed;
+    }
+    catch (err) {
+        console.error(`[${ts()}]   [claim] poll error: ${err.message.slice(0, 80)}`);
+        return 0;
+    }
+}
+// ── Resolve: drain all claimed+held escalations for this run ─────────────────
+async function resolveBatch(batchTag) {
+    try {
+        const resp = await api('GET', `/api/escalations?type=ortho-stage&status=pending&assigned_to=${userId}&limit=100&sort_by=created_at&order=asc`);
+        const escalations = resp?.escalations ?? [];
+        let resolved = 0;
+        for (const esc of escalations) {
+            if (!ORTHO_ROLES.includes(esc.role))
+                continue;
+            if (!String(esc.workflow_id ?? '').includes(batchTag))
+                continue;
+            const heldS = esc.claimed_at ? ageSeconds(esc.claimed_at) : 0;
+            if (heldS < HOLD_S)
+                continue;
+            try {
+                await api('POST', `/api/escalations/${esc.id}/resolve`, {
+                    resolverPayload: { approved: true, station: esc.role, completed_at: new Date().toISOString() },
+                });
+                totalResolved++;
+                resolved++;
+                console.log(`[${ts()}]   [resolve] ${esc.role.padEnd(8)} ${esc.id.slice(0, 8)}… held ${heldS.toFixed(1)}s [${totalResolved} total]`);
+            }
+            catch (err) {
+                console.error(`[${ts()}]   [resolve] ${esc.id.slice(0, 8)}… error: ${err.message.slice(0, 60)}`);
+            }
+        }
+        return resolved;
+    }
+    catch (err) {
+        console.error(`[${ts()}]   [resolve] poll error: ${err.message.slice(0, 80)}`);
+        return 0;
+    }
+}
+// ── Run all orders through all 8 stages ───────────────────────────────────────
+async function runOrders(batchTag, target) {
+    let done = false;
+    // Claim loop — runs continuously until done.
+    const claimLoop = async () => {
+        while (!done) {
+            await claimBatch(batchTag);
+            if (!done)
+                await sleep(POLL_MS);
+        }
+    };
+    // Resolve loop — drains all held escalations each poll.
+    const resolveLoop = async () => {
+        while (!done) {
+            await resolveBatch(batchTag);
+            if (!done)
+                await sleep(POLL_MS);
+        }
+    };
+    // Watchdog — stops when target hit or stalled too long.
+    const STALL_S = Math.max(30, HOLD_S * 6);
+    const watchdog = async () => {
+        let lastResolved = totalResolved;
+        let stalledFor = 0;
+        while (!done) {
+            await sleep(1000);
+            if (totalResolved >= target) {
+                done = true;
+                break;
+            }
+            if (totalResolved > lastResolved) {
+                stalledFor = 0;
+                lastResolved = totalResolved;
+            }
+            else {
+                stalledFor++;
+                if (stalledFor % 10 === 0) {
+                    console.log(`[${ts()}]   … ${totalResolved}/${target} resolved — waiting (${stalledFor}s quiet)`);
+                }
+                if (stalledFor >= STALL_S) {
+                    console.warn(`[${ts()}]   ⚠ stalled ${stalledFor}s with ${totalResolved}/${target} — stopping`);
+                    done = true;
+                    break;
+                }
+            }
+        }
+    };
+    await Promise.all([claimLoop(), resolveLoop(), watchdog()]);
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+async function main() {
+    console.log(`\n  Ortho Populate  ──  ${ORDERS} orders × 8 stages  (hold=${HOLD_S}s, poll=${POLL_MS}ms)`);
+    console.log(`  Server: ${BASE_URL}\n`);
+    await login();
+    const runId = Math.floor(Date.now() / 1000).toString();
+    const batchTag = `ortho-pop-${runId}`;
+    const workflowIds = [];
+    // Enqueue all orders.
+    console.log(`[${ts()}] Enqueuing ${ORDERS} orders…`);
+    for (let i = 0; i < ORDERS; i++) {
+        const wfId = `${batchTag}-${i}`;
+        try {
+            await api('POST', '/api/workflows/orthoPipeline/invoke', {
+                workflowId: wfId,
+                data: { order_id: `ORD-${runId}-${i}`, item_type: 'insole-standard' },
+                metadata: { source: 'populate', run_id: runId },
+            });
+            workflowIds.push(wfId);
+            console.log(`[${ts()}]   ${i + 1}/${ORDERS} → ${wfId}`);
+        }
+        catch (err) {
+            console.error(`[${ts()}]   ${i + 1}/${ORDERS} FAILED: ${err.message}`);
+        }
+    }
+    if (workflowIds.length === 0) {
+        console.error('Nothing enqueued — aborting');
+        process.exit(1);
+    }
+    const target = workflowIds.length * 8;
+    console.log(`\n[${ts()}] Running — target: ${target} resolutions (${workflowIds.length} orders × 8 stages)\n`);
+    const startMs = Date.now();
+    await runOrders(batchTag, target);
+    const elapsed = ((Date.now() - startMs) / 1000).toFixed(1);
+    await sleep(2000);
+    // Count completed workflows.
+    let completed = 0;
+    for (const wfId of workflowIds) {
+        try {
+            const resp = await api('GET', `/api/workflows/${wfId}/result`);
+            if (resp?.result?.data?.results?.length === 8)
+                completed++;
+        }
+        catch { /* still running */ }
+    }
+    console.log(`\n[${ts()}] Done in ${elapsed}s`);
+    console.log(`  Orders submitted:  ${workflowIds.length}`);
+    console.log(`  Orders completed:  ${completed}`);
+    console.log(`  Claimed:           ${totalClaimed}`);
+    console.log(`  Resolved:          ${totalResolved}`);
+    console.log(`\n  Dashboard: ${BASE_URL}/operations\n`);
+}
+main().catch((err) => { console.error(err); process.exit(1); });

package/build/sdk/index.d.ts

@@ -119,6 +119,9 @@ export declare function createClient(options?: LTClientOptions): {
         getStats: (input: {
             period?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        getStationMetrics: (input: {
+            period?: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         get: (input: {
             id: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
@@ -268,6 +271,7 @@ export declare function createClient(options?: LTClientOptions): {
         list: typeof rolesApi.listRoles;
         listWithDetails: typeof rolesApi.listRolesWithDetails;
         create: typeof rolesApi.createRole;
+        update: typeof rolesApi.updateRole;
         delete: typeof rolesApi.deleteRole;
         getEscalationChains: typeof rolesApi.getEscalationChains;
         addEscalationChain: typeof rolesApi.addEscalationChain;

package/build/sdk/index.js

@@ -119,6 +119,7 @@ function createClient(options = {}) {
             listTypes: escalationsApi.listDistinctTypes,
             listFacetKeys: bindAuth(escalationsApi.listFacetKeys, auth),
             getStats: bindAuth(escalationsApi.getEscalationStats, auth),
+            getStationMetrics: bindAuth(escalationsApi.getStationMetrics, auth),
             get: bindAuth(escalationsApi.getEscalation, auth),
             getByWorkflowId: escalationsApi.getEscalationsByWorkflowId,
             escalate: bindAuth(escalationsApi.escalateToRole, auth),
@@ -193,6 +194,7 @@ function createClient(options = {}) {
             list: rolesApi.listRoles,
             listWithDetails: rolesApi.listRolesWithDetails,
             create: rolesApi.createRole,
+            update: rolesApi.updateRole,
             delete: rolesApi.deleteRole,
             getEscalationChains: rolesApi.getEscalationChains,
             addEscalationChain: rolesApi.addEscalationChain,

package/build/services/escalation/client.js

@@ -66,14 +66,69 @@ async function installEscalationCompatView() {
     const client = await pool.connect();
     try {
         await client.query('SELECT pg_advisory_lock($1)', [COMPAT_VIEW_LOCK_ID]);
-        await client.query(MIGRATE_AND_RENAME_LEGACY_TABLE);
-        await client.query(CREATE_COMPAT_VIEW);
+        // Atomic table→view swap. The legacy-row migration + RENAME and the
+        // CREATE VIEW commit together, so `lt_escalations` is never momentarily
+        // absent — a concurrent reader sees either the old table or the new view,
+        // never nothing. Postgres DDL is transactional, so a crash mid-swap rolls
+        // back cleanly and the next container retries from a consistent state.
+        try {
+            await client.query('BEGIN');
+            await client.query(MIGRATE_AND_RENAME_LEGACY_TABLE);
+            await client.query(CREATE_COMPAT_VIEW);
+            await client.query('COMMIT');
+        }
+        catch (err) {
+            await client.query('ROLLBACK').catch(() => { });
+            throw err;
+        }
+        // Superseded-index drops run AFTER the swap, in autocommit — instant
+        // catalog operations, idempotent across retries and multi-container
+        // restarts. hmsh 0.25.0's stats indexes (idx_hmsh_esc_stats_pending /
+        // _created / _resolved, shipped by the SDK's own deploy) serve the backlog
+        // and window aggregates these earlier app-layer indexes covered, so
+        // keeping them would only amplify every insert/claim/resolve write.
+        await client.query(DROP_OLD_RESOLVED_INDEX);
+        await client.query(DROP_OLD_CLAIMED_INDEX);
+        await client.query(DROP_SUPERSEDED_PENDING_INDEX);
+        await client.query(DROP_UNCONSUMED_CLAIMED_COVER_INDEX);
         logger_1.loggerRegistry.info('[escalation] lt_escalations compatibility view ensured');
     }
     finally {
         await client.query('SELECT pg_advisory_unlock($1)', [COMPAT_VIEW_LOCK_ID]).catch(() => { });
         client.release();
     }
+    // The one index long-tail still owns builds OUTSIDE the advisory lock:
+    // CREATE INDEX CONCURRENTLY waits on every transaction holding a snapshot,
+    // and sibling containers parked inside `SELECT pg_advisory_lock(...)` hold
+    // exactly that — building inside the critical section would stall the build
+    // against its own waiters. Out here the build blocks nothing (writes proceed
+    // during CONCURRENTLY) and nothing blocks it.
+    await ensureResolvedCoverIndex();
+}
+/**
+ * Idempotent, concurrent-boot-safe build of idx_hmsh_esc_resolved_cover.
+ *
+ * A crashed CONCURRENTLY build leaves an INVALID index behind, and
+ * `CREATE INDEX CONCURRENTLY IF NOT EXISTS` would then skip it forever — so
+ * validity is checked first and an invalid leftover is dropped and rebuilt.
+ * A create that loses a cross-container race logs and defers to the next
+ * boot, which observes the winner's valid index and no-ops.
+ */
+async function ensureResolvedCoverIndex() {
+    const pool = (0, db_1.getPool)();
+    try {
+        const { rows } = await pool.query(RESOLVED_COVER_INDEX_STATE);
+        if (rows[0]?.valid === true)
+            return;
+        if (rows.length > 0) {
+            await pool.query('DROP INDEX IF EXISTS idx_hmsh_esc_resolved_cover');
+        }
+        await pool.query(ENSURE_RESOLVED_COVER_INDEX);
+        logger_1.loggerRegistry.info('[escalation] idx_hmsh_esc_resolved_cover ensured');
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[escalation] resolved-cover index build deferred to next boot: ${err.message}`);
+    }
 }
 // Migrate legacy `lt_escalations` rows into `hmsh_escalations` (idempotent),
 // then preserve the original table as `lt_escalations_legacy` rather than
@@ -139,3 +194,39 @@ CREATE OR REPLACE VIEW public.lt_escalations AS
   SELECT *,
     (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()) AS available
   FROM public.hmsh_escalations;`;
+// Index ownership — hmsh 0.25.0 ships the general aggregate indexes on
+// hmsh_escalations (idx_hmsh_esc_stats_pending covers the pending backlog
+// incl. assigned_to/assigned_until; _stats_created and _stats_resolved bound
+// the created/resolved windows). Long-tail keeps exactly ONE app-layer index:
+//
+//   idx_hmsh_esc_resolved_cover (role, resolved_at DESC, claimed_at, created_at)
+//     WHERE status = 'resolved'
+//     Serves STATION_PERIOD_METRICS_SQL: the (role, resolved_at ≥ window)
+//     prefix bounds each station's percentile scan to its own window, and the
+//     trailing claimed_at/created_at feed PERCENTILE_CONT(resolved_at -
+//     claimed_at) and (claimed_at - created_at) from the index.
+//
+// Everything else this branch once created is dropped below: the pending
+// index duplicated _stats_pending, and the claimed cover had no consuming
+// query — both were pure write amplification on the hot claim/resolve path.
+// ── Drops: superseded or branch-era-only names (idempotent no-ops elsewhere) ─
+const DROP_OLD_RESOLVED_INDEX = `
+DROP INDEX IF EXISTS idx_hmsh_escalations_role_resolved_at`;
+const DROP_OLD_CLAIMED_INDEX = `
+DROP INDEX IF EXISTS idx_hmsh_escalations_role_claimed_at`;
+const DROP_SUPERSEDED_PENDING_INDEX = `
+DROP INDEX IF EXISTS idx_hmsh_esc_pending_role_created`;
+const DROP_UNCONSUMED_CLAIMED_COVER_INDEX = `
+DROP INDEX IF EXISTS idx_hmsh_esc_claimed_cover`;
+// ── The station-percentile cover ─────────────────────────────────────────────
+/** Reports existence + validity so a crash-orphaned INVALID build is rebuilt. */
+const RESOLVED_COVER_INDEX_STATE = `
+SELECT i.indisvalid AS valid
+FROM pg_class c
+JOIN pg_index i ON i.indexrelid = c.oid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relname = 'idx_hmsh_esc_resolved_cover' AND n.nspname = 'public'`;
+const ENSURE_RESOLVED_COVER_INDEX = `\
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_hmsh_esc_resolved_cover
+  ON public.hmsh_escalations (role, resolved_at DESC, claimed_at, created_at)
+  WHERE status = 'resolved'`;

package/build/services/escalation/crud.js

@@ -28,6 +28,15 @@ const client_1 = require("./client");
 const queries_1 = require("./queries");
 const map_1 = require("./map");
 const sql_1 = require("./sql");
+/**
+ * Every escalation write publishes an event AND drops this container's cached
+ * aggregates — the event triggers a dashboard refetch, which must observe the
+ * write rather than a pre-change aggregate held for up to a cache TTL.
+ */
+function publishEscalationChange(...args) {
+    (0, queries_1.invalidateEscalationAggregates)();
+    return (0, publish_1.publishEscalationEvent)(...args);
+}
 // All escalation state lives in `public.hmsh_escalations` (HotMesh 0.22.3),
 // reached through `client.escalations.*`. The function signatures and return
 // shapes below are the frozen public surface — only the storage path changed.
@@ -56,7 +65,7 @@ async function createEscalation(input) {
         escalationPayload: (0, map_1.toJsonObject)(input.escalation_payload),
     });
     const escalation = (0, map_1.toEscalationRecord)(entry);
-    (0, publish_1.publishEscalationEvent)({
+    publishEscalationChange({
         type: 'escalation.created',
         source: 'service',
         workflowId: escalation.workflow_id || '',
@@ -79,7 +88,7 @@ async function claimEscalation(id, userId, durationMinutes = 30) {
     if (!result.ok)
         return null;
     const escalation = (0, map_1.toEscalationRecord)(result.entry);
-    (0, publish_1.publishEscalationEvent)({
+    publishEscalationChange({
         type: 'escalation.claimed',
         source: 'service',
         workflowId: escalation.workflow_id || '',
@@ -110,7 +119,7 @@ async function resolveEscalation(id, resolverPayload, metadata) {
     if (!result.ok)
         return null;
     const escalation = (0, map_1.toEscalationRecord)(result.entry);
-    (0, publish_1.publishEscalationEvent)({
+    publishEscalationChange({
         type: 'escalation.resolved',
         source: 'service',
         workflowId: escalation.workflow_id || '',
@@ -142,7 +151,7 @@ async function resolveEscalationsByIds(ids, resolverPayload, metadata) {
     const rows = await client.resolveMany({ ids, resolverPayload, metadata });
     const records = (0, map_1.toEscalationRecords)(rows);
     for (const escalation of records) {
-        (0, publish_1.publishEscalationEvent)({
+        publishEscalationChange({
             type: 'escalation.resolved',
             source: 'service',
             workflowId: escalation.workflow_id || '',
@@ -197,7 +206,7 @@ async function cancelEscalation(id) {
     if (!result.ok)
         return null;
     const cancelled = (0, map_1.toEscalationRecord)(result.entry);
-    (0, publish_1.publishEscalationEvent)({
+    publishEscalationChange({
         type: 'escalation.cancelled',
         source: 'service',
         workflowId: cancelled.workflow_id || '',
@@ -256,7 +265,7 @@ async function releaseEscalation(id, userId) {
     if (!result.ok)
         return null;
     const released = (0, map_1.toEscalationRecord)(result.entry);
-    (0, publish_1.publishEscalationEvent)({
+    publishEscalationChange({
         type: 'escalation.released',
         source: 'service',
         workflowId: released.workflow_id || '',
@@ -332,7 +341,7 @@ async function cancelEscalationsByWorkflowId(workflowId) {
         AND status = 'pending'
       RETURNING id, workflow_id, workflow_type, task_queue`, [workflowId]);
     for (const row of rows) {
-        (0, publish_1.publishEscalationEvent)({
+        publishEscalationChange({
             type: 'escalation.cancelled',
             source: 'service',
             workflowId: row.workflow_id || '',
@@ -419,7 +428,7 @@ async function claimByMetadata(key, value, userId, durationMinutes = 30, metadat
     if (!result.ok)
         return null;
     const escalation = (0, map_1.toEscalationRecord)(result.entry);
-    (0, publish_1.publishEscalationEvent)({
+    publishEscalationChange({
         type: 'escalation.claimed',
         source: 'service',
         workflowId: escalation.workflow_id || '',
@@ -461,7 +470,7 @@ async function resolveByMetadataAtomic(key, value, userId, resolverPayload, meta
     const row = rows[0];
     if (row.outcome === 'resolved') {
         const escalation = (0, map_1.toEscalationRecord)(row);
-        (0, publish_1.publishEscalationEvent)({
+        publishEscalationChange({
             type: 'escalation.resolved',
             source: 'service',
             workflowId: escalation.workflow_id || '',

package/build/services/escalation/metrics-cache.d.ts

@@ -0,0 +1,14 @@
+export declare class TtlCache<T> {
+    private readonly ttlMs;
+    private readonly store;
+    constructor(ttlMs: number);
+    /**
+     * Return the cached value for `key` when it is younger than the TTL. On a
+     * miss, run `compute`, cache the in-flight promise so concurrent callers
+     * share one computation (no thundering herd), and return it. A rejected
+     * computation is evicted so the next caller retries rather than caching the
+     * failure.
+     */
+    resolve(key: string, compute: () => Promise<T>): Promise<T>;
+    clear(): void;
+}

package/build/services/escalation/metrics-cache.js

@@ -0,0 +1,53 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Single-flight, short-TTL in-process cache.
+//
+// Memoizes the expensive half of the station-metrics query (percentile /
+// throughput aggregates) so a burst of socket-driven dashboard refreshes and
+// all concurrent viewers collapse to one computation per TTL window. Live
+// counts are never cached — only slow-changing historical aggregates, which
+// tolerate 30-60s staleness.
+//
+// Per-container by design: the values are read-only aggregates and cross-
+// container drift within the TTL is acceptable. No cross-node coordination.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TtlCache = void 0;
+class TtlCache {
+    constructor(ttlMs) {
+        this.ttlMs = ttlMs;
+        this.store = new Map();
+    }
+    /**
+     * Return the cached value for `key` when it is younger than the TTL. On a
+     * miss, run `compute`, cache the in-flight promise so concurrent callers
+     * share one computation (no thundering herd), and return it. A rejected
+     * computation is evicted so the next caller retries rather than caching the
+     * failure.
+     */
+    async resolve(key, compute) {
+        const hit = this.store.get(key);
+        if (hit && Date.now() - hit.at < this.ttlMs)
+            return hit.value;
+        // Sweep every expired entry on each miss. Keys embed the caller's role
+        // set × period, so without eviction the map accretes one row-array per
+        // distinct viewer cohort for the life of the process.
+        for (const [k, entry] of this.store) {
+            if (Date.now() - entry.at >= this.ttlMs)
+                this.store.delete(k);
+        }
+        const value = compute();
+        this.store.set(key, { at: Date.now(), value });
+        try {
+            return await value;
+        }
+        catch (err) {
+            this.store.delete(key);
+            throw err;
+        }
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+exports.TtlCache = TtlCache;

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

@@ -1,12 +1,13 @@
 import type { LTEscalationRecord, LTEscalationStatus } from '../../types';
-import type { EscalationStats } from './types';
+import type { EscalationStats, StationMetric } from './types';
 import type { FacetQuery } from '../../types';
 /**
  * Scoped faceted search — the HUMAN operations query. Composes the read-scope
  * 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.
@@ -83,3 +84,14 @@ export declare function listAvailableEscalations(filters: {
     escalations: LTEscalationRecord[];
     total: number;
 }>;
+/**
+ * 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.
+ */
+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[]>;