@hotmeshio/long-tail 0.10.13 → 0.11.0

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

@@ -0,0 +1,253 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Analytics SQL — grouped/temporal builders over the escalation queue. Every
+// escalation is one open interval [created_at, ended_at): ended_at is the
+// instant the row left the live set (COALESCE(resolved_at, updated_at) for
+// terminal rows — resolve stamps resolved_at, cancel/expire stamp updated_at
+// in the same guarded transition). The three read modes are projections of
+// that interval: membership at an instant, dwell over a window, and the
+// per-entity timeline.
+//
+// Composition rules, same as facet-sql.ts: every value is parameterized;
+// only validated column names / facet keys and the closed status whitelist
+// are interpolated. Statuses inline as literals (never parameters) so the
+// planner can prove the idx_hmsh_esc_ended_at partial predicate
+// (status <> 'pending') from `status NOT IN ('pending', ...)`, and the
+// terminal-interval branch is written explicitly (not COALESCE-folded) so it
+// can BitmapOr with the pending stats index instead of scanning history.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsInputError = void 0;
+exports.buildAggregateQuery = buildAggregateQuery;
+exports.buildTimelineQuery = buildTimelineQuery;
+const facet_sql_1 = require("./facet-sql");
+const aggregate_validate_1 = require("./aggregate-validate");
+const types_1 = require("../../types");
+var aggregate_validate_2 = require("./aggregate-validate");
+Object.defineProperty(exports, "AnalyticsInputError", { enumerable: true, get: function () { return aggregate_validate_2.AnalyticsInputError; } });
+/** SQL string literal — values come from our own lt_roles rows, escaped anyway. */
+function sqlLiteral(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/**
+ * The derived state label: roles sourcing states from their subtypes
+ * contribute COALESCE(subtype, role); everyone else IS their state.
+ */
+function stateExpr(sources) {
+    const subtypeRoles = Object.keys(sources).filter((r) => sources[r] === 'subtype').sort();
+    if (subtypeRoles.length === 0)
+        return 'role';
+    return `CASE WHEN role IN (${subtypeRoles.map(sqlLiteral).join(', ')}) THEN COALESCE(subtype, role) ELSE role END`;
+}
+/** Validated statuses as an inline literal list, e.g. `'pending', 'resolved'`. */
+function statusLiterals(statuses) {
+    return statuses.map((s) => `'${s}'`).join(', ');
+}
+/** The projected-facet output alias; the key is FACET_KEY-validated. */
+function facetAlias(key) {
+    return `"facet_${key}"`;
+}
+/** The instant a row left the live set; NULL while live. */
+function endedAtExpr(liveList) {
+    return `CASE WHEN status NOT IN (${liveList}) THEN COALESCE(resolved_at, updated_at) END`;
+}
+/**
+ * Interval-overlap predicate: the row was open at some point after `fromParam`
+ * (live rows are open now; terminal rows ended after it). Branch-explicit so
+ * each side has an index (stats_pending / ended_at partial).
+ */
+function overlapsAfter(liveList, fromParam) {
+    return `(status IN (${liveList}) OR (status NOT IN (${liveList}) AND COALESCE(resolved_at, updated_at) > ${fromParam}))`;
+}
+/** ORDER BY over the RESULT groups: measure aliases and grouped keys only. */
+function buildAggregateOrder(orderBy, measureKind, columns, facets, stateGrouped = false) {
+    if (!orderBy || !orderBy.length)
+        return 'sample_count DESC';
+    const parts = [];
+    for (const o of orderBy) {
+        const dir = o.direction === 'desc' ? 'DESC' : 'ASC';
+        if (o.field === 'state' && stateGrouped) {
+            parts.push(`state_label ${dir}`);
+        }
+        else if (o.field === 'count') {
+            if (measureKind !== 'membership') {
+                throw new aggregate_validate_1.AnalyticsInputError('orderBy "count" applies to membership; use "dwellSeconds" for dwell');
+            }
+            parts.push(`"count" ${dir}`);
+        }
+        else if (o.field === 'dwellSeconds') {
+            if (measureKind !== 'dwell') {
+                throw new aggregate_validate_1.AnalyticsInputError('orderBy "dwellSeconds" applies to dwell; use "count" for membership');
+            }
+            parts.push(`dwell_seconds ${dir}`);
+        }
+        else if (o.field === 'sampleCount') {
+            parts.push(`sample_count ${dir}`);
+        }
+        else if (columns.includes(o.field)) {
+            parts.push(`${o.field} ${dir}`);
+        }
+        else if (facets.includes(o.field)) {
+            parts.push(`${facetAlias(o.field)} ${dir} NULLS LAST`);
+        }
+        else {
+            throw new aggregate_validate_1.AnalyticsInputError(`orderBy field "${o.field}" is not a measure (count, dwellSeconds, sampleCount) or a grouped key`);
+        }
+    }
+    return parts.join(', ');
+}
+/**
+ * Build the grouped aggregate (membership or dwell) as one parameterized
+ * query. `query.entity` must be RESOLVED by the caller before building
+ * (aggregates.ts turns it into roles + opts.stateSources); the builder
+ * rejects an unresolved entity so it can never be silently ignored.
+ */
+function buildAggregateQuery(input, opts = {}) {
+    const query = (0, aggregate_validate_1.requireCleanFilter)(input.query);
+    if (query.entity !== undefined) {
+        throw new aggregate_validate_1.AnalyticsInputError('query.entity must be resolved to roles before building SQL');
+    }
+    const { columns, facets, state } = (0, aggregate_validate_1.resolveGroupBy)(input.groupBy);
+    if (state && input.states !== undefined) {
+        throw new aggregate_validate_1.AnalyticsInputError('groupBy.state and states[] are two labeling mechanisms — use one: state derives labels from the roles\' entity_state_source');
+    }
+    if (state && !opts.stateSources) {
+        throw new aggregate_validate_1.AnalyticsInputError('groupBy.state requires a role scope — set query.entity (the derived system) or query.role/roles');
+    }
+    (0, aggregate_validate_1.validateStates)(input.states, columns, facets);
+    const live = (0, aggregate_validate_1.resolveLiveStatuses)(input.liveStatuses);
+    const liveList = statusLiterals(live);
+    const { pageLimit, offset } = (0, aggregate_validate_1.resolvePage)(input.limit, input.offset);
+    const measure = input.measure;
+    if (measure?.kind !== 'membership' && measure?.kind !== 'dwell') {
+        throw new aggregate_validate_1.AnalyticsInputError('measure.kind must be "membership" or "dwell"');
+    }
+    const params = [];
+    const where = (0, facet_sql_1.buildFacetWhere)(query, params);
+    const order = buildAggregateOrder(input.orderBy, measure.kind, columns, facets, state);
+    const groupSelect = [];
+    const groupKeys = [];
+    if (state) {
+        groupSelect.push(`${stateExpr(opts.stateSources)} AS state_label`);
+        groupKeys.push('state_label');
+    }
+    for (const c of columns) {
+        groupSelect.push(c);
+        groupKeys.push(c);
+    }
+    for (const key of facets) {
+        groupSelect.push(`(metadata->>'${key}') AS ${facetAlias(key)}`);
+        groupKeys.push(facetAlias(key));
+    }
+    const groupBySql = groupKeys.length ? `GROUP BY ${groupKeys.join(', ')}\n` : '';
+    if (measure.kind === 'membership') {
+        const asOf = (0, aggregate_validate_1.resolveAsOf)(measure.asOf);
+        if (input.distinctBy !== undefined)
+            (0, aggregate_validate_1.requireFacetKey)(input.distinctBy, 'distinctBy');
+        const countExpr = input.distinctBy
+            ? `count(DISTINCT (metadata->>'${input.distinctBy}'))::int`
+            : `count(*)::int`;
+        let intervalPred;
+        if (asOf === null) {
+            // Now-anchored: the live set IS the membership — same shape and index
+            // (stats_pending) as the Pace Board's live counts.
+            intervalPred = `status IN (${liveList})`;
+        }
+        else {
+            params.push(asOf.toISOString());
+            const t = `$${params.length}::timestamptz`;
+            intervalPred = `created_at <= ${t}\n  AND ${overlapsAfter(liveList, t)}`;
+        }
+        params.push(pageLimit + 1, offset);
+        const sql = `SELECT ${[...groupSelect, `${countExpr} AS "count"`, 'count(*)::int AS sample_count'].join(',\n       ')}
+FROM public.lt_escalations
+WHERE ${where}
+  AND ${intervalPred}
+${groupBySql}ORDER BY ${order}
+LIMIT $${params.length - 1} OFFSET $${params.length}`;
+        return { sql, params, pageLimit, columns, facets, stateGrouped: state, measureKind: 'membership', nowAnchored: asOf === null };
+    }
+    // Dwell: clip each overlapping interval to the window, sum open-seconds.
+    if (input.distinctBy !== undefined) {
+        throw new aggregate_validate_1.AnalyticsInputError('distinctBy is a membership concept — for per-entity dwell, put the entity facet in groupBy.facets');
+    }
+    const win = (0, aggregate_validate_1.resolveWindow)(measure.window, 'measure.window');
+    if (!win)
+        throw new aggregate_validate_1.AnalyticsInputError('measure.window is required for dwell');
+    params.push(win.from.toISOString());
+    const fromP = `$${params.length}::timestamptz`;
+    params.push(win.to.toISOString());
+    const toP = `$${params.length}::timestamptz`;
+    const spanSelect = [
+        ...groupSelect,
+        `GREATEST(created_at, ${fromP}) AS s`,
+        // Open rows clamp to now, not to the window end: a caller may round the
+        // window end into the near future (cache-key stability), and an open row
+        // must not accrue seconds that haven't elapsed.
+        `LEAST(COALESCE(${endedAtExpr(liveList)}, LEAST(NOW(), ${toP})), ${toP}) AS e`,
+    ];
+    params.push(pageLimit + 1, offset);
+    const sql = `WITH span AS (
+  SELECT ${spanSelect.join(',\n         ')}
+  FROM public.lt_escalations
+  WHERE ${where}
+    AND created_at < ${toP}
+    AND ${overlapsAfter(liveList, fromP)}
+)
+SELECT ${[...groupKeys, 'SUM(EXTRACT(EPOCH FROM (e - s)))::float8 AS dwell_seconds', 'count(*)::int AS sample_count'].join(',\n       ')}
+FROM span
+${groupBySql}ORDER BY ${order}
+LIMIT $${params.length - 1} OFFSET $${params.length}`;
+    return { sql, params, pageLimit, columns, facets, stateGrouped: state, measureKind: 'dwell', nowAnchored: win.nowAnchored };
+}
+/** Build the single-entity interval sequence, created_at-ordered, gaps preserved. */
+function buildTimelineQuery(input) {
+    (0, aggregate_validate_1.requireFacetKey)(input?.facet?.key, 'facet.key');
+    if (typeof input.facet.value !== 'string' || input.facet.value.length === 0) {
+        throw new aggregate_validate_1.AnalyticsInputError('facet.value must be a non-empty string (entity facets are matched as JSON strings)');
+    }
+    const query = (0, aggregate_validate_1.requireCleanFilter)(input.query);
+    if (query.entity !== undefined) {
+        throw new aggregate_validate_1.AnalyticsInputError('query.entity must be resolved to roles before building SQL');
+    }
+    // select.columns narrows which columns the mapper surfaces; omitted = all.
+    const { columns, facets } = (0, aggregate_validate_1.resolveGroupBy)({
+        columns: input.select?.columns ?? [...types_1.GROUPABLE_COLUMNS],
+        facets: input.select?.facets,
+    });
+    const live = (0, aggregate_validate_1.resolveLiveStatuses)(input.liveStatuses);
+    const liveList = statusLiterals(live);
+    const win = (0, aggregate_validate_1.resolveWindow)(input.window);
+    const { order, before } = (0, aggregate_validate_1.resolveTimelinePage)(input.order, input.before);
+    const { pageLimit } = (0, aggregate_validate_1.resolvePage)(input.limit, undefined);
+    // GIN-served entity match; buildFacetWhere composes any extra filter after it.
+    const params = [JSON.stringify({ [input.facet.key]: input.facet.value })];
+    const clauses = [`metadata @> $1::jsonb`, (0, facet_sql_1.buildFacetWhere)(query, params)];
+    let clampEnd = 'NOW()';
+    if (win) {
+        params.push(win.from.toISOString());
+        const fromP = `$${params.length}::timestamptz`;
+        params.push(win.to.toISOString());
+        const toP = `$${params.length}::timestamptz`;
+        clauses.push(`created_at < ${toP}`, overlapsAfter(liveList, fromP));
+        clampEnd = `LEAST(NOW(), ${toP})`;
+    }
+    // The "load earlier" cursor: strictly-older intervals than the oldest the
+    // client already holds. One entity's rows are few; the sort is trivial.
+    if (before) {
+        params.push(before.toISOString());
+        clauses.push(`created_at < $${params.length}::timestamptz`);
+    }
+    const ended = endedAtExpr(liveList);
+    const facetSelect = facets.map((key) => `(metadata->>'${key}') AS ${facetAlias(key)}`);
+    params.push(pageLimit + 1);
+    const sql = `SELECT ${['role', 'subtype', 'status', ...facetSelect].join(', ')},
+       created_at AS started_at,
+       ${ended} AS ended_at,
+       EXTRACT(EPOCH FROM (COALESCE(${ended}, ${clampEnd}) - created_at))::float8 AS duration_seconds
+FROM public.lt_escalations
+WHERE ${clauses.join('\n  AND ')}
+ORDER BY created_at ${order === 'desc' ? 'DESC' : 'ASC'}
+LIMIT $${params.length}`;
+    return { sql, params, pageLimit, columns, facets, nowAnchored: !win || win.nowAnchored };
+}

package/build/services/escalation/aggregate-validate.d.ts

@@ -0,0 +1,57 @@
+import type { AnalyticsWindow, FacetGroupBy, FacetQuery, GroupableColumn, StateMatch } from '../../types';
+/** A caller-input problem — mapped to HTTP 400 by the api layer. */
+export declare class AnalyticsInputError extends Error {
+    readonly status = 400;
+    constructor(message: string);
+}
+export declare function requireFacetKey(key: string, label: string): string;
+/**
+ * The statuses the caller considers live, validated against the closed status
+ * set. Values are later inlined as SQL literals, so this whitelist is also the
+ * injection boundary.
+ */
+export declare function resolveLiveStatuses(liveStatuses?: string[]): string[];
+/**
+ * The analytics filter accepts the WHAT of a FacetQuery (role/roles or entity,
+ * facets, block, range, exists) and rejects everything that describes liveness
+ * or row paging — those are derived from the measure and the group page
+ * instead. `entity` is validated here and RESOLVED by the service (to the
+ * roles declaring it) before any SQL is built.
+ */
+export declare function requireCleanFilter(query: (FacetQuery & {
+    entity?: string;
+}) | undefined, label?: string): FacetQuery & {
+    entity?: string;
+};
+/** Timeline paging direction; `before` is a strict created_at upper bound. */
+export declare function resolveTimelinePage(order: 'asc' | 'desc' | undefined, before: Date | string | undefined): {
+    order: 'asc' | 'desc';
+    before: Date | null;
+};
+export declare function toInstant(value: Date | string, label: string): Date;
+/** Half-open [from, to): ordered, and bounded by LT_ANALYTICS_MAX_WINDOW_DAYS. */
+export declare function resolveWindow(window: AnalyticsWindow | undefined, label?: string): {
+    from: Date;
+    to: Date;
+    nowAnchored: boolean;
+} | null;
+/** Membership anchor: null = now (the cheap live-set path); a past instant otherwise. */
+export declare function resolveAsOf(asOf: Date | string | undefined): Date | null;
+export declare function resolveGroupBy(groupBy: FacetGroupBy | undefined): {
+    columns: GroupableColumn[];
+    facets: string[];
+    state: boolean;
+};
+/**
+ * A state label that references a group key the query never produces can never
+ * match — that is a caller bug, so it throws rather than silently never labeling.
+ */
+export declare function validateStates(states: Array<{
+    name: string;
+    match: StateMatch;
+}> | undefined, columns: GroupableColumn[], facets: string[]): void;
+/** Result-group paging, hard-capped at LT_ANALYTICS_MAX_GROUPS. */
+export declare function resolvePage(limit?: number, offset?: number): {
+    pageLimit: number;
+    offset: number;
+};

package/build/services/escalation/aggregate-validate.js

@@ -0,0 +1,218 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Analytics input validation — every constraint checked loudly up front so the
+// SQL builders (aggregate-sql.ts) compose only proven-safe pieces. Unlike the
+// legacy row paths (buildFacetWhere silently drops malformed range/exists
+// entries), the analytics surface rejects: a filter the caller believes is
+// applied but isn't would silently change what an aggregate MEANS.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsInputError = void 0;
+exports.requireFacetKey = requireFacetKey;
+exports.resolveLiveStatuses = resolveLiveStatuses;
+exports.requireCleanFilter = requireCleanFilter;
+exports.resolveTimelinePage = resolveTimelinePage;
+exports.toInstant = toInstant;
+exports.resolveWindow = resolveWindow;
+exports.resolveAsOf = resolveAsOf;
+exports.resolveGroupBy = resolveGroupBy;
+exports.validateStates = validateStates;
+exports.resolvePage = resolvePage;
+const config_1 = require("../../modules/config");
+const facet_sql_1 = require("./facet-sql");
+const types_1 = require("../../types");
+/** A caller-input problem — mapped to HTTP 400 by the api layer. */
+class AnalyticsInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.status = 400;
+        this.name = 'AnalyticsInputError';
+    }
+}
+exports.AnalyticsInputError = AnalyticsInputError;
+const VALID_STATUSES = new Set(['pending', 'resolved', 'cancelled', 'expired']);
+const RANGE_OPS = new Set(['<', '<=', '>', '>=', '=']);
+/** Clock-skew tolerance when rejecting a future asOf. */
+const FUTURE_SKEW_MS = 5_000;
+/** anyOf targets an explicit entity set (a table page) — never an unbounded list. */
+const MAX_ANY_OF = 200;
+function requireFacetKey(key, label) {
+    if (typeof key !== 'string' || !facet_sql_1.FACET_KEY.test(key)) {
+        throw new AnalyticsInputError(`${label} "${key}" is not a valid facet key (letters, digits, underscore only)`);
+    }
+    return key;
+}
+/**
+ * The statuses the caller considers live, validated against the closed status
+ * set. Values are later inlined as SQL literals, so this whitelist is also the
+ * injection boundary.
+ */
+function resolveLiveStatuses(liveStatuses) {
+    const list = liveStatuses ?? ['pending'];
+    if (!Array.isArray(list) || list.length === 0) {
+        throw new AnalyticsInputError('liveStatuses must be a non-empty array when provided');
+    }
+    const out = [];
+    for (const s of list) {
+        if (!VALID_STATUSES.has(s)) {
+            throw new AnalyticsInputError(`liveStatuses contains unknown status "${s}" (valid: ${[...VALID_STATUSES].join(', ')})`);
+        }
+        if (!out.includes(s))
+            out.push(s);
+    }
+    return out;
+}
+/**
+ * The analytics filter accepts the WHAT of a FacetQuery (role/roles or entity,
+ * facets, block, range, exists) and rejects everything that describes liveness
+ * or row paging — those are derived from the measure and the group page
+ * instead. `entity` is validated here and RESOLVED by the service (to the
+ * roles declaring it) before any SQL is built.
+ */
+function requireCleanFilter(query, label = 'query') {
+    const q = query ?? {};
+    if (q.entity !== undefined) {
+        requireFacetKey(q.entity, `${label}.entity`);
+        if (q.role !== undefined || q.roles !== undefined) {
+            throw new AnalyticsInputError(`${label}.entity and ${label}.role/roles are two scoping mechanisms — use one: entity derives the roles from their entity_facet declarations`);
+        }
+    }
+    for (const field of ['status', 'available', 'jeopardy']) {
+        if (q[field] !== undefined) {
+            throw new AnalyticsInputError(`${label}.${field} is not accepted in analytics — liveness derives from the interval; use liveStatuses and the measure anchor`);
+        }
+    }
+    for (const field of ['orderBy', 'limit', 'offset']) {
+        if (q[field] !== undefined) {
+            throw new AnalyticsInputError(`${label}.${field} is not accepted in analytics — order and paginate the result groups with the top-level orderBy/limit/offset`);
+        }
+    }
+    for (const r of q.range ?? []) {
+        requireFacetKey(r?.facet, `${label}.range facet`);
+        if (!RANGE_OPS.has(r?.op)) {
+            throw new AnalyticsInputError(`${label}.range op "${r?.op}" is not one of < <= > >= =`);
+        }
+    }
+    for (const key of q.exists ?? []) {
+        requireFacetKey(key, `${label}.exists key`);
+    }
+    for (const [key, value] of Object.entries(q.prefix ?? {})) {
+        requireFacetKey(key, `${label}.prefix key`);
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new AnalyticsInputError(`${label}.prefix["${key}"] must be a non-empty string`);
+        }
+    }
+    if (q.anyOf !== undefined) {
+        if (!Array.isArray(q.anyOf) || q.anyOf.length === 0) {
+            throw new AnalyticsInputError(`${label}.anyOf must be a non-empty array of facet sets`);
+        }
+        if (q.anyOf.length > MAX_ANY_OF) {
+            throw new AnalyticsInputError(`${label}.anyOf holds ${q.anyOf.length} entries; the maximum is ${MAX_ANY_OF} — page the target set`);
+        }
+        for (const entry of q.anyOf) {
+            if (!entry || typeof entry !== 'object' || Object.keys(entry).length === 0) {
+                throw new AnalyticsInputError(`${label}.anyOf entries must be non-empty facet objects`);
+            }
+            for (const key of Object.keys(entry))
+                requireFacetKey(key, `${label}.anyOf key`);
+        }
+    }
+    return q;
+}
+/** Timeline paging direction; `before` is a strict created_at upper bound. */
+function resolveTimelinePage(order, before) {
+    if (order !== undefined && order !== 'asc' && order !== 'desc') {
+        throw new AnalyticsInputError('order must be "asc" or "desc"');
+    }
+    return {
+        order: order ?? 'asc',
+        before: before === undefined ? null : toInstant(before, 'before'),
+    };
+}
+function toInstant(value, label) {
+    const d = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(d.getTime())) {
+        throw new AnalyticsInputError(`${label} is not a parseable instant: "${value}"`);
+    }
+    return d;
+}
+/** Half-open [from, to): ordered, and bounded by LT_ANALYTICS_MAX_WINDOW_DAYS. */
+function resolveWindow(window, label = 'window') {
+    if (!window)
+        return null;
+    const from = toInstant(window.from, `${label}.from`);
+    const to = toInstant(window.to, `${label}.to`);
+    if (from.getTime() >= to.getTime()) {
+        throw new AnalyticsInputError(`${label} is empty: from must be before to`);
+    }
+    const spanDays = (to.getTime() - from.getTime()) / 86_400_000;
+    if (spanDays > config_1.config.LT_ANALYTICS_MAX_WINDOW_DAYS) {
+        throw new AnalyticsInputError(`${label} spans ${spanDays.toFixed(1)} days; the maximum is ${config_1.config.LT_ANALYTICS_MAX_WINDOW_DAYS} (LT_ANALYTICS_MAX_WINDOW_DAYS)`);
+    }
+    return { from, to, nowAnchored: to.getTime() >= Date.now() };
+}
+/** Membership anchor: null = now (the cheap live-set path); a past instant otherwise. */
+function resolveAsOf(asOf) {
+    if (asOf === undefined)
+        return null;
+    const d = toInstant(asOf, 'measure.asOf');
+    if (d.getTime() > Date.now() + FUTURE_SKEW_MS) {
+        throw new AnalyticsInputError('measure.asOf is in the future — membership can only be reconstructed for past instants');
+    }
+    return d;
+}
+function resolveGroupBy(groupBy) {
+    const columns = [];
+    for (const c of groupBy?.columns ?? []) {
+        if (!types_1.GROUPABLE_COLUMNS.includes(c)) {
+            throw new AnalyticsInputError(`groupBy.columns contains "${c}" (valid: ${types_1.GROUPABLE_COLUMNS.join(', ')})`);
+        }
+        if (!columns.includes(c))
+            columns.push(c);
+    }
+    const facets = [];
+    for (const key of groupBy?.facets ?? []) {
+        requireFacetKey(key, 'groupBy.facets key');
+        if (!facets.includes(key))
+            facets.push(key);
+    }
+    return { columns, facets, state: groupBy?.state === true };
+}
+/**
+ * A state label that references a group key the query never produces can never
+ * match — that is a caller bug, so it throws rather than silently never labeling.
+ */
+function validateStates(states, columns, facets) {
+    for (const s of states ?? []) {
+        if (!s?.name)
+            throw new AnalyticsInputError('states entries require a name');
+        const m = s.match ?? {};
+        if ((m.role !== undefined || m.roles !== undefined) && !columns.includes('role')) {
+            throw new AnalyticsInputError(`state "${s.name}" matches on role, but groupBy.columns does not include "role"`);
+        }
+        if (m.subtype !== undefined && !columns.includes('subtype')) {
+            throw new AnalyticsInputError(`state "${s.name}" matches on subtype, but groupBy.columns does not include "subtype"`);
+        }
+        for (const key of Object.keys(m.facets ?? {})) {
+            if (!facets.includes(key)) {
+                throw new AnalyticsInputError(`state "${s.name}" matches on facet "${key}", but groupBy.facets does not include it`);
+            }
+        }
+        for (const key of m.exists ?? []) {
+            if (!facets.includes(key)) {
+                throw new AnalyticsInputError(`state "${s.name}" requires facet "${key}", but groupBy.facets does not include it`);
+            }
+        }
+    }
+}
+/** Result-group paging, hard-capped at LT_ANALYTICS_MAX_GROUPS. */
+function resolvePage(limit, offset) {
+    const cap = config_1.config.LT_ANALYTICS_MAX_GROUPS;
+    if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
+        throw new AnalyticsInputError('limit must be a positive integer');
+    }
+    if (offset !== undefined && (!Number.isInteger(offset) || offset < 0)) {
+        throw new AnalyticsInputError('offset must be a non-negative integer');
+    }
+    return { pageLimit: Math.min(limit ?? cap, cap), offset: offset ?? 0 };
+}

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

@@ -0,0 +1,26 @@
+import type { AggregateByFacetsInput, AggregateByFacetsResult, TimelineByFacetInput, TimelineByFacetResult } from '../../types';
+/** Called on every escalation write (via invalidateEscalationAggregates). */
+export declare function clearNowAnchoredAnalyticsCache(): void;
+/** Test hook: drop BOTH analytics caches. */
+export declare function resetAnalyticsCaches(): void;
+/**
+ * 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.
+ */
+export declare function resolveEntitySystem(entityKey: string): Promise<Array<{
+    role: string;
+    source: 'role' | 'subtype';
+}>>;
+/**
+ * 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.
+ */
+export declare function aggregateByFacets(input: AggregateByFacetsInput): Promise<AggregateByFacetsResult>;
+/**
+ * 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.
+ */
+export declare function timelineByFacet(input: TimelineByFacetInput): Promise<TimelineByFacetResult>;