@hotmeshio/long-tail 0.10.13 → 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/escalation/resolver-validation.d.ts

@@ -23,6 +23,6 @@ export interface ResolverSchemaViolationReport {
  * surface's task fallback); by default the row's own envelope column is used.
  * It is only invoked when the role actually enforces.
  */
-export declare function checkResolverPayload(escalation: ResolvableEscalationRow, resolverPayload: Record<string, any>, loadEnvelope?: () => Promise<Record<string, any>>): Promise<ResolverSchemaViolationReport | null>;
+export declare function checkResolverPayload(escalation: ResolvableEscalationRow, resolverPayload: Record<string, any>, loadEnvelope?: () => Promise<Record<string, any>>, resolvingUserId?: string): Promise<ResolverSchemaViolationReport | null>;
 /** The canonical 422 body for a violation report (types/validation.ts). */
 export declare function toValidationErrorBody(report: ResolverSchemaViolationReport): LTValidationErrorBody;

package/build/services/escalation/resolver-validation.js

@@ -22,6 +22,7 @@ exports.toValidationErrorBody = toValidationErrorBody;
  * the gate passes.
  */
 const form_validation_1 = require("../../shared/form-validation");
+const submit_guard_1 = require("./submit-guard");
 const enforcement_cache_1 = require("../role/enforcement-cache");
 const escalation_1 = require("../../types/escalation");
 const validation_1 = require("../../types/validation");
@@ -54,7 +55,7 @@ function pinnedVersionOf(metadata) {
  * surface's task fallback); by default the row's own envelope column is used.
  * It is only invoked when the role actually enforces.
  */
-async function checkResolverPayload(escalation, resolverPayload, loadEnvelope) {
+async function checkResolverPayload(escalation, resolverPayload, loadEnvelope, resolvingUserId) {
     const role = escalation.role;
     if (!role)
         return null;
@@ -72,15 +73,21 @@ async function checkResolverPayload(escalation, resolverPayload, loadEnvelope) {
     const envelope = loadEnvelope
         ? await loadEnvelope()
         : parseJsonOrNull(escalation.envelope) ?? {};
-    const violations = (0, form_validation_1.validateResolverPayload)(schema, resolverPayload, {
+    const ctx = {
         escalation: escalation,
         metadata,
         envelope,
         payload: parseJsonOrNull(escalation.escalation_payload),
-    });
-    if (violations.length === 0)
+    };
+    const violations = (0, form_validation_1.validateResolverPayload)(schema, resolverPayload, ctx);
+    // The query precondition (x-lt-submit-guard): reject while the embedded query
+    // still returns rows. Enforced on the same enforce_schema opt-in as the field
+    // contract, so a raw-API resolve honors the gate the dashboard shows.
+    const guardViolation = await (0, submit_guard_1.checkSubmitGuard)(schema, ctx, resolvingUserId);
+    const allViolations = guardViolation ? [...violations, guardViolation] : violations;
+    if (allViolations.length === 0)
         return null;
-    return { role, schemaVersion: pin, violations };
+    return { role, schemaVersion: pin, violations: allViolations };
 }
 /** The canonical 422 body for a violation report (types/validation.ts). */
 function toValidationErrorBody(report) {

package/build/services/escalation/submit-guard.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Server-side enforcement of the `x-lt-submit-guard` query precondition — the
+ * API-first counterpart of the dashboard's `useSubmitGuard`. Before an
+ * escalation resolves, if its form schema declares a submit guard, the same
+ * embedded query runs and the resolve is REJECTED while it still returns rows.
+ *
+ * Isomorphism with the dashboard is exact: the guard reuses `resolveScopedQuery`
+ * (the mapping the escalation-list embed uses) and runs it through
+ * `searchEscalationsFaceted` — the same faceted query the list API composes.
+ *
+ * Two deliberate rules:
+ *  - The count is taken with `global: true`, bypassing the resolver's read
+ *    scope, so a role that cannot SEE the children can never falsely clear the
+ *    gate. Only a real, empty result count clears it (the "403 ≠ empty" rule).
+ *  - A guard whose scope cannot be evaluated (e.g. `assigned:'me'` on a surface
+ *    with no resolving user, like an MCP resolve) is skipped here; the consuming
+ *    workflow's own verification remains the durable backstop.
+ */
+import { type ShowIfContext } from '../../shared/form-validation';
+import type { LTFieldViolation } from '../../types/validation';
+/** The synthetic violation field for a guard rejection — not a form field. */
+export declare const SUBMIT_GUARD_VIOLATION_FIELD = "_submitGuard";
+/**
+ * Returns a violation when the escalation's submit guard still matches rows, or
+ * null when there is no guard, its scope is inert, or the query is confirmed
+ * empty. The context carries the escalation domains the query facets and the
+ * message interpolate against.
+ */
+export declare function checkSubmitGuard(schema: Record<string, any> | null | undefined, ctx: ShowIfContext, resolvingUserId: string | undefined): Promise<LTFieldViolation | null>;

package/build/services/escalation/submit-guard.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBMIT_GUARD_VIOLATION_FIELD = void 0;
+exports.checkSubmitGuard = checkSubmitGuard;
+/**
+ * Server-side enforcement of the `x-lt-submit-guard` query precondition — the
+ * API-first counterpart of the dashboard's `useSubmitGuard`. Before an
+ * escalation resolves, if its form schema declares a submit guard, the same
+ * embedded query runs and the resolve is REJECTED while it still returns rows.
+ *
+ * Isomorphism with the dashboard is exact: the guard reuses `resolveScopedQuery`
+ * (the mapping the escalation-list embed uses) and runs it through
+ * `searchEscalationsFaceted` — the same faceted query the list API composes.
+ *
+ * Two deliberate rules:
+ *  - The count is taken with `global: true`, bypassing the resolver's read
+ *    scope, so a role that cannot SEE the children can never falsely clear the
+ *    gate. Only a real, empty result count clears it (the "403 ≠ empty" rule).
+ *  - A guard whose scope cannot be evaluated (e.g. `assigned:'me'` on a surface
+ *    with no resolving user, like an MCP resolve) is skipped here; the consuming
+ *    workflow's own verification remains the durable backstop.
+ */
+const form_validation_1 = require("../../shared/form-validation");
+const queries_1 = require("./queries");
+/** The synthetic violation field for a guard rejection — not a form field. */
+exports.SUBMIT_GUARD_VIOLATION_FIELD = '_submitGuard';
+/**
+ * Returns a violation when the escalation's submit guard still matches rows, or
+ * null when there is no guard, its scope is inert, or the query is confirmed
+ * empty. The context carries the escalation domains the query facets and the
+ * message interpolate against.
+ */
+async function checkSubmitGuard(schema, ctx, resolvingUserId) {
+    const guard = (0, form_validation_1.readSubmitGuard)(schema);
+    if (!guard || guard.mustBeEmpty === false)
+        return null;
+    const scoped = (0, form_validation_1.resolveScopedQuery)(guard.query, ctx, resolvingUserId);
+    if (!scoped.enabled)
+        return null;
+    const { total } = await (0, queries_1.searchEscalationsFaceted)({
+        global: true,
+        facet: {
+            role: scoped.role,
+            status: scoped.status,
+            available: scoped.available,
+            facets: scoped.facets,
+        },
+        assigned_to: scoped.assigned_to,
+        limit: 1,
+        offset: 0,
+    });
+    if (total <= 0)
+        return null;
+    const template = guard.message ?? form_validation_1.SUBMIT_GUARD_DEFAULT_MESSAGE;
+    const message = (0, form_validation_1.interpolateHelp)(template.replace(/\{\{count\}\}/g, String(total)), ctx);
+    return { field: exports.SUBMIT_GUARD_VIOLATION_FIELD, message };
+}

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>;