@hotmeshio/long-tail 0.23.0 → 0.23.2

package/build/api/escalations/index.d.ts

@@ -11,3 +11,4 @@ export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';
 export { searchByFacets, claimGroups, claimByFacets } from './facets';
 export { aggregateByFacets, timelineByFacet } from './analytics';
+export { getRelatedAggregates, getRelatedRows } from './related';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.itemsView = exports.getEscalationItemsBySignalKey = exports.getEscalationItems = exports.removeItemByMetadata = exports.removeItemBySignalKey = exports.removeItem = exports.accumulateItemByMetadata = exports.accumulateItemBySignalKey = exports.accumulateItem = exports.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetValues = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.getRelatedRows = exports.getRelatedAggregates = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.itemsView = exports.getEscalationItemsBySignalKey = exports.getEscalationItems = exports.removeItemByMetadata = exports.removeItemBySignalKey = exports.removeItem = exports.accumulateItemByMetadata = exports.accumulateItemBySignalKey = exports.accumulateItem = exports.resolveBatchItemByMetadata = exports.resolveBatchItemBySignalKey = exports.resolveBatchItem = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkUnassign = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.getEscalationLookups = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetValues = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -61,3 +61,6 @@ Object.defineProperty(exports, "claimByFacets", { enumerable: true, get: functio
 var analytics_1 = require("./analytics");
 Object.defineProperty(exports, "aggregateByFacets", { enumerable: true, get: function () { return analytics_1.aggregateByFacets; } });
 Object.defineProperty(exports, "timelineByFacet", { enumerable: true, get: function () { return analytics_1.timelineByFacet; } });
+var related_1 = require("./related");
+Object.defineProperty(exports, "getRelatedAggregates", { enumerable: true, get: function () { return related_1.getRelatedAggregates; } });
+Object.defineProperty(exports, "getRelatedRows", { enumerable: true, get: function () { return related_1.getRelatedRows; } });

package/build/api/escalations/list.d.ts

@@ -19,6 +19,11 @@ export interface FacetInput {
      * carries the full record.
      */
     include?: string;
+    /**
+     * Page by groups of this metadata key: a page holds whole groups and
+     * `total` counts groups. The response adds `groups: [{ key, ids }]`.
+     */
+    groupBy?: string;
 }
 /**
  * List escalations with optional filters.

package/build/api/escalations/list.js

@@ -43,6 +43,7 @@ exports.getStationMetrics = getStationMetrics;
 const escalationService = __importStar(require("../../services/escalation"));
 const features_1 = require("../../modules/features");
 const helpers_1 = require("./helpers");
+const facet_sql_1 = require("../../services/escalation/facet-sql");
 /** Strip the heavyweight JSON columns from list rows unless asked back. */
 function projectListRows(rows, include) {
     if (include === 'envelope')
@@ -53,6 +54,12 @@ function projectListRows(rows, include) {
 function projectListResult(result, include) {
     return { ...result, escalations: projectListRows(result.escalations, include) };
 }
+/** Run a scoped faceted search, paged by groups when the caller asked. */
+async function runFacetedSearch(search, groupBy) {
+    return groupBy
+        ? escalationService.searchEscalationsGrouped({ ...search, groupKey: groupBy })
+        : escalationService.searchEscalationsFaceted(search);
+}
 /** True when the caller asked for anything the plain list path can't express. */
 function hasFacetQuery(i) {
     return !!(i.facets ||
@@ -62,7 +69,8 @@ function hasFacetQuery(i) {
         i.orderBy?.length ||
         i.roles?.length ||
         i.available != null ||
-        i.jeopardy === true);
+        i.jeopardy === true ||
+        !!i.groupBy);
 }
 /**
  * List escalations with optional filters.
@@ -86,6 +94,9 @@ function hasFacetQuery(i) {
 async function listEscalations(input, auth) {
     try {
         const scope = await (0, helpers_1.getEscalationReadScope)(auth.userId);
+        if (input.groupBy != null && !facet_sql_1.FACET_KEY.test(input.groupBy)) {
+            return { status: 400, error: 'groupBy must be a metadata key (letters, numbers, underscores)' };
+        }
         if (!scope.global && scope.allRoles.length === 0 && scope.selfRoles.length === 0) {
             return { status: 200, data: { escalations: [], total: 0 } };
         }
@@ -93,7 +104,7 @@ async function listEscalations(input, auth) {
         // language (facets/block/range/exists/metadata-sort) IN SQL — the caller's
         // role(s) can only NARROW within their scope, never widen past it.
         if (hasFacetQuery(input)) {
-            const result = await escalationService.searchEscalationsFaceted({
+            const result = await runFacetedSearch({
                 global: scope.global,
                 visibleRoles: scope.global ? undefined : scope.allRoles,
                 selfRoles: scope.global ? undefined : scope.selfRoles,
@@ -117,7 +128,7 @@ async function listEscalations(input, auth) {
                 search: input.search,
                 limit: input.limit ?? 50,
                 offset: input.offset ?? 0,
-            });
+            }, input.groupBy);
             return { status: 200, data: projectListResult(result, input.include) };
         }
         const result = await escalationService.listEscalations({
@@ -164,12 +175,15 @@ async function listEscalations(input, auth) {
 async function listAvailableEscalations(input, auth) {
     try {
         const scope = await (0, helpers_1.getEscalationReadScope)(auth.userId);
+        if (input.groupBy != null && !facet_sql_1.FACET_KEY.test(input.groupBy)) {
+            return { status: 400, error: 'groupBy must be a metadata key (letters, numbers, underscores)' };
+        }
         if (!scope.global && scope.allRoles.length === 0 && scope.selfRoles.length === 0) {
             return { status: 200, data: { escalations: [], total: 0 } };
         }
         // Faceted path — same as listEscalations but pinned to the available pool.
         if (hasFacetQuery(input)) {
-            const result = await escalationService.searchEscalationsFaceted({
+            const result = await runFacetedSearch({
                 global: scope.global,
                 visibleRoles: scope.global ? undefined : scope.allRoles,
                 selfRoles: scope.global ? undefined : scope.selfRoles,
@@ -192,7 +206,7 @@ async function listAvailableEscalations(input, auth) {
                 search: input.search,
                 limit: input.limit ?? 50,
                 offset: input.offset ?? 0,
-            });
+            }, input.groupBy);
             return { status: 200, data: projectListResult(result, input.include) };
         }
         const result = await escalationService.listAvailableEscalations({

package/build/api/escalations/related.d.ts

@@ -0,0 +1,18 @@
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/**
+ * Aggregate every related set the role's list schema declares, for one page
+ * of host rows. One statement per (set, split) pair, whatever the page size.
+ */
+export declare function getRelatedAggregates(input: {
+    role: string;
+    ids: string[];
+    version?: number;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/** One host's rows in one related set, for a row detail section. */
+export declare function getRelatedRows(input: {
+    role: string;
+    id: string;
+    set: string;
+    version?: number;
+    limit?: number;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/related.js

@@ -0,0 +1,205 @@
+"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.getRelatedAggregates = getRelatedAggregates;
+exports.getRelatedRows = getRelatedRows;
+const escalationService = __importStar(require("../../services/escalation"));
+const roleService = __importStar(require("../../services/role"));
+const uuid_1 = require("../../lib/uuid");
+const list_schema_1 = require("../../shared/list-schema");
+const segment_1 = require("../../shared/roles/segment");
+const helpers_1 = require("./helpers");
+const DEFAULT_STATUS = 'pending';
+const NOT_FOUND = 'Role list schema not found';
+/** Gate the host role, then read its declaration from the stored list schema. */
+async function loadDeclaration(role, version, auth) {
+    if (typeof role !== 'string' || !role)
+        return { error: { status: 400, error: 'role is required' } };
+    if (version !== undefined && (!Number.isInteger(version) || version < 1)) {
+        return { error: { status: 400, error: 'version must be a positive integer' } };
+    }
+    const readScope = await (0, helpers_1.getEscalationReadScope)(auth.userId);
+    const readable = readScope.global || readScope.allRoles.includes(role) || readScope.selfRoles.includes(role);
+    if (!readable)
+        return { error: { status: 404, error: NOT_FOUND } };
+    const stored = await roleService.getRoleListSchema(role, version);
+    if (!stored)
+        return { error: { status: 404, error: NOT_FOUND } };
+    let relations;
+    try {
+        relations = (0, list_schema_1.readListSchemaRelations)(stored.list_schema);
+    }
+    catch (err) {
+        return { error: { status: 422, error: `list schema for ${role}: ${err.message}` } };
+    }
+    const scope = {
+        global: readScope.global,
+        visibleRoles: readScope.global ? undefined : readScope.allRoles,
+        selfRoles: readScope.global ? undefined : readScope.selfRoles,
+        meUserId: auth.userId,
+    };
+    return { scope, readScope, relations, version: stored.version };
+}
+async function resolveQueryRoles(query, readScope) {
+    const details = await roleService.listRolesWithDetails();
+    const roles = query.roles ?? (0, segment_1.segmentRoles)(details, query.segment);
+    if (!roles)
+        return `segment "${query.segment}" names no Pace Board sequence`;
+    const titles = new Map(details.map((d) => [d.role, d.title]));
+    const roleLabels = {};
+    for (const r of roles)
+        roleLabels[r] = titles.get(r) || r;
+    const restricted = readScope.global ? [] : roles.filter((r) => !readScope.allRoles.includes(r));
+    return { roles, roleLabels, restricted };
+}
+/** The split paths the declared columns ask of one set ('' when unsplit). */
+function splitsFor(relations, set) {
+    const splits = new Set(relations.columns.filter((c) => c.related === set).map((c) => c.splitBy ?? ''));
+    if (!splits.size)
+        splits.add('');
+    return [...splits];
+}
+/**
+ * Aggregate every related set the role's list schema declares, for one page
+ * of host rows. One statement per (set, split) pair, whatever the page size.
+ */
+async function getRelatedAggregates(input, auth) {
+    try {
+        if (!Array.isArray(input.ids))
+            return { status: 400, error: 'ids must be an array of escalation ids' };
+        if (input.ids.length > list_schema_1.RELATED_LIMITS.MAX_HOSTS) {
+            return { status: 400, error: `ids holds at most ${list_schema_1.RELATED_LIMITS.MAX_HOSTS} rows` };
+        }
+        const loaded = await loadDeclaration(input.role, input.version, auth);
+        if ('error' in loaded)
+            return loaded.error;
+        const { scope, readScope, relations, version } = loaded;
+        const data = { version, sets: {} };
+        const names = Object.keys(relations.sets);
+        const ids = [...new Set(input.ids.filter(uuid_1.isUuid))];
+        if (!names.length || !ids.length)
+            return { status: 200, data };
+        const hosts = await escalationService.readRelatedHosts({ ids, role: input.role, scope });
+        const hostIds = hosts.map((h) => h.id);
+        for (const name of names) {
+            const decl = relations.sets[name];
+            const result = { source: decl.source, aggregates: {} };
+            if (decl.source === list_schema_1.RELATED_SOURCES.ITEMS) {
+                const roles = new Set();
+                for (const splitBy of splitsFor(relations, name)) {
+                    const read = await escalationService.aggregateRelatedItems({
+                        hostIds, scope, splitBy: splitBy || undefined,
+                    });
+                    result.aggregates[splitBy] = read.aggregates;
+                    read.roles.forEach((r) => roles.add(r));
+                }
+                if (roles.size)
+                    result.roles = [...roles].sort();
+            }
+            else {
+                const resolved = await resolveQueryRoles(decl.query, readScope);
+                if (typeof resolved === 'string')
+                    return { status: 400, error: `x-lt-related.${name}: ${resolved}` };
+                Object.assign(result, resolved);
+                const matched = [];
+                const unresolved = [];
+                for (const host of hosts) {
+                    const match = (0, list_schema_1.resolveRelatedFacets)(decl.query.facets ?? {}, (0, list_schema_1.rowTemplateContext)(host), decl.query.narrow);
+                    if (match)
+                        matched.push({ hostId: host.id, match });
+                    else
+                        unresolved.push(host.id);
+                }
+                for (const splitBy of splitsFor(relations, name)) {
+                    const agg = await escalationService.aggregateRelatedQuery({
+                        hosts: matched, roles: resolved.roles, status: decl.query.status ?? DEFAULT_STATUS, scope,
+                        splitBy: splitBy || undefined,
+                    });
+                    for (const id of unresolved)
+                        agg[id] = { count: 0, unresolved: true };
+                    result.aggregates[splitBy] = agg;
+                }
+            }
+            data.sets[name] = result;
+        }
+        return { status: 200, data };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/** One host's rows in one related set, for a row detail section. */
+async function getRelatedRows(input, auth) {
+    try {
+        if (!(0, uuid_1.isUuid)(input.id))
+            return { status: 400, error: 'id must be an escalation id' };
+        if (input.limit !== undefined && (!Number.isInteger(input.limit) || input.limit < 1 || input.limit > list_schema_1.RELATED_LIMITS.ROWS_MAX)) {
+            return { status: 400, error: `limit must be 1..${list_schema_1.RELATED_LIMITS.ROWS_MAX}` };
+        }
+        const loaded = await loadDeclaration(input.role, input.version, auth);
+        if ('error' in loaded)
+            return loaded.error;
+        const { scope, readScope, relations } = loaded;
+        const decl = relations.sets[input.set];
+        if (!decl)
+            return { status: 404, error: `x-lt-related declares no set "${input.set}"` };
+        const [host] = await escalationService.readRelatedHosts({ ids: [input.id], role: input.role, scope });
+        if (!host)
+            return { status: 404, error: 'Escalation not found' };
+        const limit = input.limit ?? list_schema_1.RELATED_LIMITS.ROWS_DEFAULT;
+        if (decl.source === list_schema_1.RELATED_SOURCES.ITEMS) {
+            const { rows, total } = await escalationService.listRelatedItems({ hostId: input.id, scope, limit });
+            const data = { source: decl.source, rows, total };
+            return { status: 200, data };
+        }
+        const resolved = await resolveQueryRoles(decl.query, readScope);
+        if (typeof resolved === 'string')
+            return { status: 400, error: `x-lt-related.${input.set}: ${resolved}` };
+        const match = (0, list_schema_1.resolveRelatedFacets)(decl.query.facets ?? {}, (0, list_schema_1.rowTemplateContext)(host), decl.query.narrow);
+        const { rows, total } = match
+            ? await escalationService.listRelatedQueryRows({
+                hosts: [{ hostId: input.id, match }], roles: resolved.roles,
+                status: decl.query.status ?? DEFAULT_STATUS, scope, limit,
+            })
+            : { rows: [], total: 0 };
+        const data = {
+            source: decl.source, rows, total, restricted: resolved.restricted, roleLabels: resolved.roleLabels,
+        };
+        return { status: 200, data };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/roles.js

@@ -51,6 +51,7 @@ const roleService = __importStar(require("../services/role"));
 const types_1 = require("../services/role/types");
 const badge_grant_1 = require("../services/role/badge-grant");
 const facet_sql_1 = require("../services/escalation/facet-sql");
+const list_schema_1 = require("../shared/list-schema");
 /**
  * List all distinct role names in the system.
  *
@@ -295,6 +296,9 @@ async function updateRole(input) {
         const grantError = (0, badge_grant_1.badgeGrantError)(input.properties?.[types_1.ROLE_PROPERTY_KEYS.BADGE_GRANT]);
         if (grantError)
             return { status: 400, error: grantError };
+        const listSchemaError = input.list_schema != null ? (0, list_schema_1.listSchemaRelationsError)(input.list_schema) : null;
+        if (listSchemaError)
+            return { status: 400, error: `list_schema: ${listSchemaError}` };
         if (input.portals != null && !isPortalList(input.portals)) {
             return {
                 status: 400,

package/build/api/scan-codes/present.js

@@ -45,7 +45,11 @@ function renderFacts(step, ctx, row) {
     if (!step.facts)
         return undefined;
     const tpl = { ...(0, context_1.templateContext)(ctx), item: row.metadata ?? {} };
-    return step.facts.map((fact) => ({ label: fact.label, value: scanCodeService.renderScanCopy(fact.value, tpl) }));
+    return step.facts.map((fact) => ({
+        label: fact.label,
+        value: scanCodeService.renderScanCopy(fact.value.trim(), tpl),
+        ...(fact.format ? { format: fact.format } : {}),
+    }));
 }
 // ── The info-choice outcome — locate → present reality + labeled choices ───
 //

package/build/api/settings.d.ts

@@ -8,6 +8,6 @@ import type { LTApiResult } from '../types/sdk';
  * environment block (long-tail + HotMesh versions, Node env/version).
  *
  * @param req — the incoming HTTP request, used to derive NATS WS URL from headers when proxying
- * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, features, environment } }`
+ * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, features, search, branding, display, environment } }`
  */
 export declare function getSettings(req?: IncomingMessage): Promise<LTApiResult>;

package/build/api/settings.js

@@ -10,6 +10,7 @@ const config_1 = require("../modules/config");
 const features_1 = require("../modules/features");
 const search_1 = require("../modules/search");
 const branding_1 = require("../modules/branding");
+const display_1 = require("../modules/display");
 const version_1 = require("../modules/version");
 const sso_1 = require("../modules/sso");
 const defaults_1 = require("../modules/defaults");
@@ -41,7 +42,7 @@ function resolveNatsWsUrl(adapter, req) {
  * environment block (long-tail + HotMesh versions, Node env/version).
  *
  * @param req — the incoming HTTP request, used to derive NATS WS URL from headers when proxying
- * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, features, environment } }`
+ * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, features, search, branding, display, environment } }`
  */
 async function getSettings(req) {
     try {
@@ -79,6 +80,7 @@ async function getSettings(req) {
                 features: (0, features_1.getFeatureFlags)(),
                 search: (0, search_1.getSearchConfig)(),
                 branding: (0, branding_1.getBranding)(),
+                display: (0, display_1.getDisplay)(),
                 environment: {
                     longTailVersion: version_1.LONG_TAIL_VERSION,
                     hotmeshVersion: version_1.HOTMESH_VERSION,

package/build/modules/display.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deployment display settings surfaced to the dashboard via /api/settings.
+ * `timeZone` (an IANA name, e.g. "America/Chicago") renders every dashboard
+ * date in the deployment's zone; unset, dates render in the browser's zone.
+ */
+export interface LTDisplayConfig {
+    timeZone?: string;
+}
+/** True when the runtime knows the IANA zone name. */
+export declare function isValidTimeZone(zone: string): boolean;
+/** Apply the start config's display block; an unknown zone fails the boot. */
+export declare function configureDisplay(patch?: LTDisplayConfig): void;
+export declare function getDisplay(): {
+    timeZone: string | null;
+};

package/build/modules/display.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidTimeZone = isValidTimeZone;
+exports.configureDisplay = configureDisplay;
+exports.getDisplay = getDisplay;
+let timeZone = null;
+/** True when the runtime knows the IANA zone name. */
+function isValidTimeZone(zone) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Apply the start config's display block; an unknown zone fails the boot. */
+function configureDisplay(patch) {
+    const zone = patch?.timeZone;
+    if (zone !== undefined && (typeof zone !== 'string' || !isValidTimeZone(zone))) {
+        throw new Error(`display.timeZone "${zone}" is not an IANA time zone name`);
+    }
+    timeZone = zone ?? null;
+}
+function getDisplay() {
+    return { timeZone };
+}

package/build/routes/escalations/index.js

@@ -9,6 +9,7 @@ const single_1 = require("./single");
 const resolve_1 = require("./resolve");
 const facets_1 = require("./facets");
 const analytics_1 = require("./analytics");
+const related_1 = require("./related");
 const router = (0, express_1.Router)();
 // Registration order matters: literal paths before parameterized /:id routes.
 // GET /, /available, /types, /stats
@@ -26,6 +27,8 @@ const router = (0, express_1.Router)();
 (0, facets_1.registerFacetRoutes)(router);
 // POST /aggregate-by-facets, /timeline-by-facet
 (0, analytics_1.registerAnalyticsRoutes)(router);
+// POST /related, /related/rows
+(0, related_1.registerRelatedRoutes)(router);
 // PATCH /:id/escalate, GET /by-workflow/:workflowId,
 // GET /:id, POST /:id/claim, POST /:id/release
 (0, single_1.registerSingleRoutes)(router);

package/build/routes/escalations/list.js

@@ -110,6 +110,7 @@ function registerListRoutes(router) {
             available: req.query.available != null ? req.query.available === 'true' : undefined,
             jeopardy: req.query.jeopardy === '1' || req.query.jeopardy === 'true' || undefined,
             include: req.query.include,
+            groupBy: req.query.groupBy || undefined,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
@@ -138,6 +139,7 @@ function registerListRoutes(router) {
             orderBy: jsonParam(req.query.orderBy),
             jeopardy: req.query.jeopardy === '1' || req.query.jeopardy === 'true' || undefined,
             include: req.query.include,
+            groupBy: req.query.groupBy || undefined,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });

package/build/routes/escalations/related.d.ts

@@ -0,0 +1,7 @@
+import type { Router } from 'express';
+/**
+ * Related sets for role list views. The role's stored list schema declares
+ * the sets; the caller names the role, the page's host rows, and the schema
+ * version it rendered. Results are scoped to the caller's read scope.
+ */
+export declare function registerRelatedRoutes(router: Router): void;

package/build/routes/escalations/related.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.registerRelatedRoutes = registerRelatedRoutes;
+const api = __importStar(require("../../api/escalations"));
+/**
+ * Related sets for role list views. The role's stored list schema declares
+ * the sets; the caller names the role, the page's host rows, and the schema
+ * version it rendered. Results are scoped to the caller's read scope.
+ */
+function registerRelatedRoutes(router) {
+    /**
+     * POST /api/escalations/related
+     * Body: { role, ids, version? }
+     */
+    router.post('/related', async (req, res) => {
+        const result = await api.getRelatedAggregates(req.body ?? {}, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+    /**
+     * POST /api/escalations/related/rows
+     * Body: { role, id, set, version?, limit? }
+     */
+    router.post('/related/rows', async (req, res) => {
+        const result = await api.getRelatedRows(req.body ?? {}, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
+}

package/build/scripts/consolidation-sim.d.ts

@@ -0,0 +1,25 @@
+/**
+ * consolidation-sim: drive the consolidation example over HTTP so the
+ * Consolidate list shows a floor in motion.
+ *
+ * Opens a tub per destination (the first tub split into a standard and an
+ * express lane), starts orders with a mix of service levels, then walks
+ * them through the stations (prep, check) and places each in its
+ * destination's bin. With KEEP=1 it stops partway, leaving orders at every
+ * station and some bins partly filled, so the list's Holds and Coming
+ * columns and each row's expansion have something to show.
+ *
+ * Usage:
+ *   npm run consolidation:sim
+ *   DESTINATIONS=3 ORDERS=12 EXPRESS_PCT=30 KEEP=1 npm run consolidation:sim
+ *
+ * Env vars:
+ *   BASE_URL       long-tail API (default http://localhost:3000)
+ *   DESTINATIONS   destinations, one tub each (default 2)
+ *   ORDERS         orders to start (default 8)
+ *   EXPRESS_PCT    percent of orders on the express service (default 25)
+ *   STEP_MS        pause between floor moves (default 600)
+ *   KEEP           1 = stop partway and leave the floor mid-flight (default 0)
+ *   LT_USERNAME / LT_PASSWORD   the dev login (defaults: the seeded admin)
+ */
+export {};