@hotmeshio/long-tail 0.10.14 → 0.11.0

package/build/services/escalation/aggregates.js

@@ -0,0 +1,204 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Escalation analytics service — grouped/temporal reads over the interval
+// time-series (see aggregate-sql.ts for the SQL semantics). Pure read surface:
+// no lifecycle change, no write path.
+//
+// Caching splits by anchor. A now-anchored result (membership now, a window
+// reaching now) is pace-board-grade: short TTL, cleared by
+// invalidateEscalationAggregates() on every escalation write on this
+// container. A fully-past anchor is immutable under every long-tail write
+// path — created_at is set at insert and terminal transitions stamp NOW(),
+// which is strictly after any past anchor — so those entries survive
+// invalidation and live on the longer TTL (bounding the documented SDK
+// post-terminal-touch caveat rather than caching forever). Keys canonicalize
+// the whole input, so both caches are LRU-bounded.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearNowAnchoredAnalyticsCache = clearNowAnchoredAnalyticsCache;
+exports.resetAnalyticsCaches = resetAnalyticsCaches;
+exports.resolveEntitySystem = resolveEntitySystem;
+exports.aggregateByFacets = aggregateByFacets;
+exports.timelineByFacet = timelineByFacet;
+const db_1 = require("../../lib/db");
+const config_1 = require("../../modules/config");
+const facets_1 = require("./facets");
+const metrics_cache_1 = require("./metrics-cache");
+const aggregate_sql_1 = require("./aggregate-sql");
+const aggregate_validate_1 = require("./aggregate-validate");
+const nowAnchoredCache = new metrics_cache_1.BoundedTtlCache(config_1.config.LT_ANALYTICS_CACHE_TTL_MS, config_1.config.LT_ANALYTICS_CACHE_MAX_ENTRIES);
+const pastAnchoredCache = new metrics_cache_1.BoundedTtlCache(config_1.config.LT_ANALYTICS_PAST_CACHE_TTL_MS, config_1.config.LT_ANALYTICS_CACHE_MAX_ENTRIES);
+/** Key-order-independent stringify, so `{a,b}` and `{b,a}` share one entry. */
+function canonical(value) {
+    return JSON.stringify(value, (_key, v) => v && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : 1)))
+        : v);
+}
+/** Called on every escalation write (via invalidateEscalationAggregates). */
+function clearNowAnchoredAnalyticsCache() {
+    nowAnchoredCache.clear();
+}
+/** Test hook: drop BOTH analytics caches. */
+function resetAnalyticsCaches() {
+    nowAnchoredCache.clear();
+    pastAnchoredCache.clear();
+}
+function matchesState(row, m) {
+    if (m.role !== undefined && row.role !== m.role)
+        return false;
+    if (m.roles !== undefined && !m.roles.includes(row.role))
+        return false;
+    if (m.subtype !== undefined && row.subtype !== m.subtype)
+        return false;
+    for (const [key, value] of Object.entries(m.facets ?? {})) {
+        if (row.facets[key] == null || row.facets[key] !== String(value))
+            return false;
+    }
+    for (const key of m.exists ?? []) {
+        if (row.facets[key] == null)
+            return false;
+    }
+    return true;
+}
+function toAggregateRow(raw, built, states) {
+    const facets = {};
+    for (const key of built.facets)
+        facets[key] = raw[`facet_${key}`] ?? null;
+    const row = { facets, sampleCount: Number(raw.sample_count) };
+    for (const column of built.columns)
+        row[column] = raw[column] ?? undefined;
+    if (built.measureKind === 'membership')
+        row.count = Number(raw.count);
+    else
+        row.dwellSeconds = Number(raw.dwell_seconds);
+    if (built.stateGrouped) {
+        row.state = raw.state_label;
+    }
+    else {
+        const label = (states ?? []).find((s) => matchesState(row, s.match));
+        if (label)
+            row.state = label.name;
+    }
+    return row;
+}
+function toIso(value) {
+    return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}
+function toTimelineInterval(raw, built) {
+    const facets = {};
+    for (const key of built.facets)
+        facets[key] = raw[`facet_${key}`] ?? null;
+    const interval = {
+        role: raw.role,
+        facets,
+        startedAt: toIso(raw.started_at),
+        endedAt: raw.ended_at == null ? null : toIso(raw.ended_at),
+        durationSeconds: Number(raw.duration_seconds),
+    };
+    if (built.columns.includes('subtype'))
+        interval.subtype = raw.subtype ?? undefined;
+    if (built.columns.includes('status'))
+        interval.status = raw.status;
+    return interval;
+}
+// ── Entity-system resolution ─────────────────────────────────────────────────
+const ENTITY_SYSTEM_SQL = `
+  SELECT role, entity_state_source FROM lt_roles WHERE entity_facet = $1 ORDER BY role`;
+const STATE_SOURCES_SQL = `
+  SELECT role, entity_state_source FROM lt_roles WHERE role = ANY($1::text[])`;
+/**
+ * The roles declaring `entity_facet = key` — the entity's SYSTEM — with each
+ * role's state naming. Loud when nothing declares the key: an empty system is
+ * a config gap, not an empty result.
+ */
+async function resolveEntitySystem(entityKey) {
+    (0, aggregate_validate_1.requireFacetKey)(entityKey, 'query.entity');
+    await (0, facets_1.ensureFacetReady)();
+    const { rows } = await (0, db_1.getPool)().query(ENTITY_SYSTEM_SQL, [entityKey]);
+    if (rows.length === 0) {
+        throw new aggregate_sql_1.AnalyticsInputError(`no roles declare entity_facet "${entityKey}" — set Entity on the roles this entity moves through`);
+    }
+    return rows.map((r) => ({
+        role: r.role,
+        source: r.entity_state_source === 'subtype' ? 'subtype' : 'role',
+    }));
+}
+/** State naming for an explicit role list (roles missing from lt_roles default to 'role'). */
+async function stateSourcesFor(roles) {
+    const { rows } = await (0, db_1.getPool)().query(STATE_SOURCES_SQL, [roles]);
+    const sources = {};
+    for (const role of roles)
+        sources[role] = 'role';
+    for (const r of rows)
+        sources[r.role] = r.entity_state_source === 'subtype' ? 'subtype' : 'role';
+    return sources;
+}
+/**
+ * Resolve `query.entity` (and `groupBy.state`) into concrete scope: the
+ * system's roles replace `entity` on the filter (plus `exists: [entityKey]`
+ * so rows without the entity stay out), and per-role state sources ride along
+ * for the builder. The resolved system joins the cache key, so a role-config
+ * edit changes the key rather than serving a stale state shape.
+ */
+async function resolveScope(query, needsStateSources) {
+    if (query.entity !== undefined) {
+        const system = await resolveEntitySystem(query.entity);
+        const { entity, ...rest } = query;
+        const resolved = {
+            ...rest,
+            roles: system.map((s) => s.role),
+            exists: [...new Set([...(rest.exists ?? []), entity])],
+        };
+        const sources = {};
+        for (const s of system)
+            sources[s.role] = s.source;
+        return { query: resolved, stateSources: sources, cacheSuffix: `:${canonical(system)}` };
+    }
+    if (needsStateSources) {
+        const roles = query.role ? [query.role] : query.roles ?? [];
+        if (roles.length === 0)
+            return { query, cacheSuffix: '' }; // builder rejects loudly
+        const sources = await stateSourcesFor(roles);
+        return { query, stateSources: sources, cacheSuffix: `:${canonical(sources)}` };
+    }
+    return { query, cacheSuffix: '' };
+}
+/**
+ * Grouped aggregate over the escalation intervals — membership at an instant
+ * or dwell over a window, grouped by columns + facets (+ the derived state
+ * label). One call replaces N countByFacets round-trips.
+ */
+async function aggregateByFacets(input) {
+    const scope = await resolveScope(input.query ?? {}, input.groupBy?.state === true);
+    const effective = { ...input, query: scope.query };
+    // Validates loudly BEFORE any cache entry.
+    const built = (0, aggregate_sql_1.buildAggregateQuery)(effective, { stateSources: scope.stateSources });
+    const cache = built.nowAnchored ? nowAnchoredCache : pastAnchoredCache;
+    return (await cache.resolve(`agg:${canonical(input)}${scope.cacheSuffix}`, async () => {
+        await (0, facets_1.ensureFacetReady)();
+        const { rows } = await (0, db_1.getPool)().query(built.sql, built.params);
+        return {
+            groups: rows.slice(0, built.pageLimit).map((r) => toAggregateRow(r, built, input.states)),
+            overflow: rows.length > built.pageLimit,
+        };
+    }));
+}
+/**
+ * One entity's ordered interval sequence — `[created_at, ended_at)` spans with
+ * durations. Gaps between consecutive intervals are untracked time and are
+ * deliberately preserved, not filled.
+ */
+async function timelineByFacet(input) {
+    const scope = await resolveScope(input.query ?? {}, false);
+    const effective = { ...input, query: scope.query };
+    const built = (0, aggregate_sql_1.buildTimelineQuery)(effective);
+    const cache = built.nowAnchored ? nowAnchoredCache : pastAnchoredCache;
+    return (await cache.resolve(`tl:${canonical(input)}${scope.cacheSuffix}`, async () => {
+        await (0, facets_1.ensureFacetReady)();
+        const { rows } = await (0, db_1.getPool)().query(built.sql, built.params);
+        return {
+            intervals: rows.slice(0, built.pageLimit).map((r) => toTimelineInterval(r, built)),
+            overflow: rows.length > built.pageLimit,
+        };
+    }));
+}

package/build/services/escalation/client.js

@@ -97,16 +97,24 @@ async function installEscalationCompatView() {
         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:
+    // The indexes long-tail owns build 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();
+    await ensureAppIndex('idx_hmsh_esc_resolved_cover', ENSURE_RESOLVED_COVER_INDEX);
+    await ensureAppIndex('idx_hmsh_esc_ended_at', ENSURE_ENDED_AT_INDEX);
 }
+/** Reports existence + validity so a crash-orphaned INVALID build is rebuilt. */
+const APP_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 = $1 AND n.nspname = 'public'`;
 /**
- * Idempotent, concurrent-boot-safe build of idx_hmsh_esc_resolved_cover.
+ * Idempotent, concurrent-boot-safe build of one app-layer index.
  *
  * A crashed CONCURRENTLY build leaves an INVALID index behind, and
  * `CREATE INDEX CONCURRENTLY IF NOT EXISTS` would then skip it forever — so
@@ -114,20 +122,20 @@ async function installEscalationCompatView() {
  * 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() {
+async function ensureAppIndex(name, ddl) {
     const pool = (0, db_1.getPool)();
     try {
-        const { rows } = await pool.query(RESOLVED_COVER_INDEX_STATE);
+        const { rows } = await pool.query(APP_INDEX_STATE, [name]);
         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(`DROP INDEX IF EXISTS ${name}`);
         }
-        await pool.query(ENSURE_RESOLVED_COVER_INDEX);
-        logger_1.loggerRegistry.info('[escalation] idx_hmsh_esc_resolved_cover ensured');
+        await pool.query(ddl);
+        logger_1.loggerRegistry.info(`[escalation] ${name} ensured`);
     }
     catch (err) {
-        logger_1.loggerRegistry.warn(`[escalation] resolved-cover index build deferred to next boot: ${err.message}`);
+        logger_1.loggerRegistry.warn(`[escalation] ${name} index build deferred to next boot: ${err.message}`);
     }
 }
 // Migrate legacy `lt_escalations` rows into `hmsh_escalations` (idempotent),
@@ -188,16 +196,38 @@ BEGIN
   END IF;
 END $$;`;
 // `available` mirrors the legacy isEffectivelyClaimed/isAvailable heuristic so
-// existing `SELECT *` consumers are unaffected; the column is additive.
+// existing `SELECT *` consumers are unaffected; the columns are additive.
+//
+// `ended_at` is the instant the row left the live set: resolve stamps
+// resolved_at in its guarded transition; cancel and expire stamp only
+// updated_at in theirs, and no long-tail write path touches a terminal row
+// afterward, so COALESCE(resolved_at, updated_at) is the transition instant
+// for all three terminal statuses. (The SDK's updateEscalation /
+// appendEscalationMilestones carry no status guard, so a post-terminal touch
+// WOULD skew a cancelled/expired end — documented contract, not enforced.)
+// Analytics SQL inlines the equivalent expression rather than reading this
+// column (so non-default liveStatuses compose and the partial index predicate
+// stays provable); the view column serves external and debugging consumers.
+// If the SDK ever ships a physical ended_at column, the SELECT * expansion
+// collides with this alias — remediation is dropping the view-level column
+// and reading the (strictly better) real one.
+//
+// DROP+CREATE (not CREATE OR REPLACE) because the base table's column set
+// moves with SDK migrations: REPLACE re-expands SELECT * and errors the
+// moment a new base column lands before the computed aliases. The swap runs
+// inside the install transaction, so readers see the old view or the new
+// one, never a gap.
 const CREATE_COMPAT_VIEW = `
-CREATE OR REPLACE VIEW public.lt_escalations AS
+DROP VIEW IF EXISTS public.lt_escalations;
+CREATE VIEW public.lt_escalations AS
   SELECT *,
-    (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()) AS available
+    (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()) AS available,
+    (CASE WHEN status <> 'pending' THEN COALESCE(resolved_at, updated_at) END) AS ended_at
   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:
+// the created/resolved windows). Long-tail keeps exactly TWO app-layer indexes:
 //
 //   idx_hmsh_esc_resolved_cover (role, resolved_at DESC, claimed_at, created_at)
 //     WHERE status = 'resolved'
@@ -206,6 +236,15 @@ CREATE OR REPLACE VIEW public.lt_escalations AS
 //     trailing claimed_at/created_at feed PERCENTILE_CONT(resolved_at -
 //     claimed_at) and (claimed_at - created_at) from the index.
 //
+//   idx_hmsh_esc_ended_at ((COALESCE(resolved_at, updated_at)))
+//     WHERE status <> 'pending'
+//     Serves the analytics interval scans (aggregate-sql.ts): dwell and
+//     past-membership need "terminal rows whose end instant is after the
+//     window/asOf" — without this, every such query scans all terminal
+//     history, growing without bound. Write cost is the cheapest possible:
+//     inserts are 'pending' (excluded by the predicate), so exactly one
+//     index write occurs per row, at its terminal transition.
+//
 // 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.
@@ -218,15 +257,12 @@ 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'`;
+// ── The app-layer indexes (built via ensureAppIndex) ────────────────────────
 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'`;
+const ENSURE_ENDED_AT_INDEX = `\
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_hmsh_esc_ended_at
+  ON public.hmsh_escalations ((COALESCE(resolved_at, updated_at)))
+  WHERE status <> 'pending'`;

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

@@ -22,6 +22,10 @@ exports.FACET_KEY = /^[a-zA-Z0-9_]+$/;
 function metaExpr(key, numeric = false) {
     return numeric ? `(metadata->>'${key}')::numeric` : `(metadata->>'${key}')`;
 }
+/** Escape LIKE wildcards so a prefix VALUE is matched literally. */
+function escapeLikePrefix(value) {
+    return value.replace(/[\\%_]/g, (c) => `\\${c}`);
+}
 /**
  * Build the WHERE clause for a faceted query, pushing bound params into `params`.
  * Every value is parameterized; only validated column names / metadata keys and
@@ -51,10 +55,23 @@ function buildFacetWhere(q, params, opts = {}) {
         params.push(JSON.stringify(q.facets));
         clauses.push(`metadata @> $${params.length}::jsonb`); // GIN-served
     }
+    if (q.anyOf && q.anyOf.length) {
+        params.push(q.anyOf.map((a) => JSON.stringify(a)));
+        clauses.push(`metadata @> ANY($${params.length}::jsonb[])`); // GIN-served OR
+    }
     if (q.block && q.block.length) {
         params.push(q.block.map((b) => JSON.stringify(b)));
         clauses.push(`NOT (metadata @> ANY($${params.length}::jsonb[]))`);
     }
+    // Case-insensitive prefix on facet VALUES — the locate affordance. No
+    // dedicated index by design: the predicate composes into scans the rest of
+    // the filter already bounds (the live set, or an analytics window).
+    for (const [key, value] of Object.entries(q.prefix ?? {})) {
+        if (!exports.FACET_KEY.test(key) || typeof value !== 'string' || !value)
+            continue;
+        params.push(`${escapeLikePrefix(value)}%`);
+        clauses.push(`${metaExpr(key)} ILIKE $${params.length}`);
+    }
     for (const r of q.range ?? []) {
         if (!exports.FACET_KEY.test(r.facet) || !RANGE_OPS.has(r.op))
             continue;

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

@@ -5,3 +5,5 @@ export * from './queries';
 export * from './resolver-validation';
 export { ensureEscalationCompatView } from './client';
 export { ensureFacetReady, searchByFacets, searchGroups, countByFacets, claimGroups, claimByFacets, } from './facets';
+export { aggregateByFacets, timelineByFacet, resolveEntitySystem, resetAnalyticsCaches, } from './aggregates';
+export { AnalyticsInputError } from './aggregate-validate';

package/build/services/escalation/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = void 0;
+exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./crud"), exports);
 __exportStar(require("./bulk"), exports);
@@ -29,3 +29,10 @@ Object.defineProperty(exports, "searchGroups", { enumerable: true, get: function
 Object.defineProperty(exports, "countByFacets", { enumerable: true, get: function () { return facets_1.countByFacets; } });
 Object.defineProperty(exports, "claimGroups", { enumerable: true, get: function () { return facets_1.claimGroups; } });
 Object.defineProperty(exports, "claimByFacets", { enumerable: true, get: function () { return facets_1.claimByFacets; } });
+var aggregates_1 = require("./aggregates");
+Object.defineProperty(exports, "aggregateByFacets", { enumerable: true, get: function () { return aggregates_1.aggregateByFacets; } });
+Object.defineProperty(exports, "timelineByFacet", { enumerable: true, get: function () { return aggregates_1.timelineByFacet; } });
+Object.defineProperty(exports, "resolveEntitySystem", { enumerable: true, get: function () { return aggregates_1.resolveEntitySystem; } });
+Object.defineProperty(exports, "resetAnalyticsCaches", { enumerable: true, get: function () { return aggregates_1.resetAnalyticsCaches; } });
+var aggregate_validate_1 = require("./aggregate-validate");
+Object.defineProperty(exports, "AnalyticsInputError", { enumerable: true, get: function () { return aggregate_validate_1.AnalyticsInputError; } });

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

@@ -12,3 +12,21 @@ export declare class TtlCache<T> {
     resolve(key: string, compute: () => Promise<T>): Promise<T>;
     clear(): void;
 }
+/**
+ * TtlCache with an LRU bound — for key spaces the caller doesn't control.
+ *
+ * The analytics caches key by a canonical stringify of the whole query input,
+ * so distinct keys are unbounded; the expired-entry sweep alone can't bound
+ * memory the way it does for TtlCache's small role-set × period key space.
+ * Same single-flight and reject-evict semantics; a hit refreshes recency
+ * (Map delete+set, the enforcement-cache pattern), and inserting past
+ * `maxEntries` evicts the least-recently-used entry.
+ */
+export declare class BoundedTtlCache<T> {
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly store;
+    constructor(ttlMs: number, maxEntries: number);
+    resolve(key: string, compute: () => Promise<T>): Promise<T>;
+    clear(): void;
+}

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

@@ -12,7 +12,7 @@
 // container drift within the TTL is acceptable. No cross-node coordination.
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TtlCache = void 0;
+exports.BoundedTtlCache = exports.TtlCache = void 0;
 class TtlCache {
     constructor(ttlMs) {
         this.ttlMs = ttlMs;
@@ -51,3 +51,49 @@ class TtlCache {
     }
 }
 exports.TtlCache = TtlCache;
+/**
+ * TtlCache with an LRU bound — for key spaces the caller doesn't control.
+ *
+ * The analytics caches key by a canonical stringify of the whole query input,
+ * so distinct keys are unbounded; the expired-entry sweep alone can't bound
+ * memory the way it does for TtlCache's small role-set × period key space.
+ * Same single-flight and reject-evict semantics; a hit refreshes recency
+ * (Map delete+set, the enforcement-cache pattern), and inserting past
+ * `maxEntries` evicts the least-recently-used entry.
+ */
+class BoundedTtlCache {
+    constructor(ttlMs, maxEntries) {
+        this.ttlMs = ttlMs;
+        this.maxEntries = maxEntries;
+        this.store = new Map();
+    }
+    async resolve(key, compute) {
+        const hit = this.store.get(key);
+        if (hit && Date.now() - hit.at < this.ttlMs) {
+            this.store.delete(key); // refresh recency
+            this.store.set(key, hit);
+            return hit.value;
+        }
+        for (const [k, entry] of this.store) {
+            if (Date.now() - entry.at >= this.ttlMs)
+                this.store.delete(k);
+        }
+        while (this.store.size >= this.maxEntries) {
+            const oldest = this.store.keys().next().value;
+            this.store.delete(oldest);
+        }
+        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.BoundedTtlCache = BoundedTtlCache;

package/build/services/escalation/queries.js

@@ -17,6 +17,7 @@ const facet_sql_1 = require("./facet-sql");
 const types_1 = require("./types");
 const sql_1 = require("./sql");
 const metrics_cache_1 = require("./metrics-cache");
+const aggregates_1 = require("./aggregates");
 /**
  * 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.
@@ -380,6 +381,7 @@ const stationPeriodCache = new metrics_cache_1.TtlCache(STATION_PERIOD_CACHE_TTL
 function invalidateEscalationAggregates() {
     stationPeriodCache.clear();
     escalationStatsCache.clear();
+    (0, aggregates_1.clearNowAnchoredAnalyticsCache)();
 }
 /** Test hook: drop cached period metrics AND escalation stats so tests observe fresh rows. */
 function resetStationMetricsCache() {

package/build/services/iam/acting-identity.d.ts

@@ -0,0 +1,16 @@
+import type { LTApiAuth } from '../../types/sdk';
+/** The acting-auth resolution result: an auth to act as, or the loud reason not to. */
+export type ActingAuthResult = {
+    ok: true;
+    auth: LTApiAuth;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Exchange a supplied acting grant for the person it names. A supplied token
+ * that fails — wrong label, expired, exhausted, or a vanished user — is a
+ * terminal error, never a silent fall-back to the session identity: that
+ * would misattribute whatever follows.
+ */
+export declare function resolveActingAuth(actingToken: string): Promise<ActingAuthResult>;

package/build/services/iam/acting-identity.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveActingAuth = resolveActingAuth;
+const userService = __importStar(require("../user"));
+const ephemeral_1 = require("./ephemeral");
+const types_1 = require("../../types");
+/**
+ * Exchange a supplied acting grant for the person it names. A supplied token
+ * that fails — wrong label, expired, exhausted, or a vanished user — is a
+ * terminal error, never a silent fall-back to the session identity: that
+ * would misattribute whatever follows.
+ */
+async function resolveActingAuth(actingToken) {
+    const parsed = (0, ephemeral_1.parseEphemeralToken)(actingToken);
+    if (!parsed || parsed.label !== types_1.ACTING_IDENTITY_LABEL) {
+        return { ok: false, error: 'actingToken is not an acting-identity grant' };
+    }
+    const userId = await (0, ephemeral_1.exchangeEphemeralToken)(actingToken);
+    if (!userId) {
+        return { ok: false, error: 'acting identity expired — scan your badge again' };
+    }
+    const user = await userService.getUser(userId);
+    if (!user || user.status !== 'active') {
+        return { ok: false, error: 'acting identity is no longer an active user' };
+    }
+    return { ok: true, auth: { userId: user.id } };
+}

package/build/services/role/index.js

@@ -150,6 +150,8 @@ async function updateRoleMetadata(role, input) {
         provided('default_pins'), input.default_pins != null ? JSON.stringify(input.default_pins) : null,
         provided('enforce_schema'), input.enforce_schema ?? null,
         provided('ops_home_default'), input.ops_home_default ?? null,
+        provided('entity_facet'), input.entity_facet ?? null,
+        provided('entity_state_source'), input.entity_state_source ?? null,
     ]);
     if (!rows[0])
         return null;

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

@@ -50,8 +50,16 @@ export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
  * ops_home_default ($35 = provided sentinel, $36 = value) is single-holder:
  * setting it true clears the flag on every other role in the same statement
  * (the home_clear CTE touches only OTHER rows, so the two UPDATEs never meet).
+ *
+ * entity_facet ($37 = provided sentinel, $38 = value) is unversioned config:
+ * the metadata key naming the entity that moves through this role (powers the
+ * analytics surfaces — entity counts, per-entity dwell, timelines).
+ *
+ * entity_state_source ($39 = provided sentinel, $40 = value) is unversioned
+ * config: 'role' | 'subtype' — how this role names its contribution to the
+ * entity's state space (the station itself, or its subtypes).
  */
-export declare const UPDATE_ROLE_METADATA = "\n  WITH home_clear AS (\n    UPDATE lt_roles SET ops_home_default = false\n    WHERE $35::boolean AND COALESCE($36::boolean, false) AND role <> $1 AND ops_home_default\n  ), 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      list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,\n      default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,\n      enforce_schema  = CASE WHEN $33::boolean THEN COALESCE($34::boolean, false)     ELSE enforce_schema  END,\n      ops_home_default = CASE WHEN $35::boolean THEN COALESCE($36::boolean, false)    ELSE ops_home_default 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      current_list_schema_version = CASE\n        WHEN $29::boolean AND $30::jsonb IS DISTINCT FROM list_schema\n        THEN COALESCE(current_list_schema_version, 0) + 1\n        ELSE current_list_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, ops_home_default, parent_role, sla_minutes, target_per_hour, worker_count,\n      priority_threshold_minutes, priority_facet,\n      current_schema_version, list_schema, current_list_schema_version,\n      default_pins, enforce_schema\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  ), list_snapshot AS (\n    INSERT INTO lt_role_list_schemas (role, version, list_schema, change_summary)\n    SELECT role, current_list_schema_version, list_schema, $26\n    FROM updated\n    WHERE $29::boolean AND current_list_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 UPDATE_ROLE_METADATA = "\n  WITH home_clear AS (\n    UPDATE lt_roles SET ops_home_default = false\n    WHERE $35::boolean AND COALESCE($36::boolean, false) AND role <> $1 AND ops_home_default\n  ), 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      entity_facet    = CASE WHEN $37::boolean THEN $38                               ELSE entity_facet    END,\n      entity_state_source\n                      = CASE WHEN $39::boolean THEN COALESCE($40, 'role')             ELSE entity_state_source END,\n      list_schema     = CASE WHEN $29::boolean THEN $30::jsonb                        ELSE list_schema     END,\n      default_pins    = CASE WHEN $31::boolean THEN $32::jsonb                        ELSE default_pins    END,\n      enforce_schema  = CASE WHEN $33::boolean THEN COALESCE($34::boolean, false)     ELSE enforce_schema  END,\n      ops_home_default = CASE WHEN $35::boolean THEN COALESCE($36::boolean, false)    ELSE ops_home_default 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      current_list_schema_version = CASE\n        WHEN $29::boolean AND $30::jsonb IS DISTINCT FROM list_schema\n        THEN COALESCE(current_list_schema_version, 0) + 1\n        ELSE current_list_schema_version END\n    WHERE role = $1\n    RETURNING\n      role, title, description, form_schema, metadata_schema, properties,\n      ops_visible, ops_home_default, parent_role, sla_minutes, target_per_hour, worker_count,\n      priority_threshold_minutes, priority_facet, entity_facet, entity_state_source,\n      current_schema_version, list_schema, current_list_schema_version,\n      default_pins, enforce_schema\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  ), list_snapshot AS (\n    INSERT INTO lt_role_list_schemas (role, version, list_schema, change_summary)\n    SELECT role, current_list_schema_version, list_schema, $26\n    FROM updated\n    WHERE $29::boolean AND current_list_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";
 /**
  * The set of roles with server-side resolver validation turned on. Small and
@@ -75,7 +83,7 @@ export declare const GET_ROLE_LIST_SCHEMA_VERSION = "\n  SELECT s.role, s.versio
  * never versioned its list schema still answers, with version NULL).
  */
 export declare const GET_ROLE_LIST_SCHEMA_CURRENT = "\n  SELECT r.role, r.current_list_schema_version AS version, r.list_schema,\n         s.change_summary, s.created_at,\n         r.current_list_schema_version AS latest_version\n  FROM lt_roles r\n  LEFT JOIN lt_role_list_schemas s\n    ON s.role = r.role AND s.version = r.current_list_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.ops_home_default,\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    r.list_schema,\n    r.current_list_schema_version,\n    r.default_pins,\n    r.enforce_schema,\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.ops_home_default,\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.entity_facet,\n    r.entity_state_source,\n    r.current_schema_version,\n    r.list_schema,\n    r.current_list_schema_version,\n    r.default_pins,\n    r.enforce_schema,\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";