npm - @hotmeshio/long-tail - Versions diffs - 0.23.1 → 0.23.2 - Mend

@hotmeshio/long-tail 0.23.1 → 0.23.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (277) hide show

package/build/scripts/consolidation-sim.js ADDED Viewed

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * 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)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+const DESTINATIONS = Number(process.env.DESTINATIONS || 2);
+const ORDERS = Number(process.env.ORDERS || 8);
+const EXPRESS_PCT = Number(process.env.EXPRESS_PCT || 25);
+const STEP_MS = Number(process.env.STEP_MS || 600);
+const KEEP = process.env.KEEP === '1';
+const USERNAME = process.env.LT_USERNAME || 'superadmin';
+const PASSWORD = process.env.LT_PASSWORD || 'l0ngt@1l';
+const ROLES = { PREP: 'order-prep', CHECK: 'order-check', STAGE: 'order-stage', BIN: 'consolidate' };
+const RUN = Date.now().toString(36).slice(-4).toUpperCase();
+const DESTINATION_NAMES = ['north', 'south', 'east', 'west', 'central', 'harbor'];
+let token = '';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function api(method, path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    const data = text ? JSON.parse(text) : {};
+    if (!res.ok)
+        throw new Error(`${method} ${path} → ${res.status}: ${data.error ?? text}`);
+    return data;
+}
+/** The pending row for one order at one role, polled until the workflow parks it. */
+async function rowFor(role, facets) {
+    const q = new URLSearchParams({ role, status: 'pending', limit: '1', facets: JSON.stringify(facets) });
+    for (let i = 0; i < 100; i++) {
+        const { escalations } = await api('GET', `/api/escalations?${q}`);
+        if (escalations[0])
+            return escalations[0];
+        await sleep(200);
+    }
+    throw new Error(`no pending ${role} row for ${JSON.stringify(facets)}`);
+}
+async function openBins(destinations) {
+    const bins = [];
+    for (const [i, destination] of destinations.entries()) {
+        const binKey = `T${i + 1}-${RUN}`;
+        const lanes = i === 0 ? ['standard', 'express'] : [undefined];
+        for (const lane of lanes) {
+            await api('POST', '/api/workflows/consolidationBin/invoke', { data: { binKey, destination, lane, max: 20, timeout: '8h' } });
+            const row = await rowFor(ROLES.BIN, { binKey, ...(lane ? { lane } : {}) });
+            bins.push({ id: row.id, destination, lane });
+            console.log(`[bin] ${binKey}${lane ? ` (${lane})` : ''} → ${destination}`);
+        }
+    }
+    return bins;
+}
+async function startOrders(destinations) {
+    const orders = [];
+    for (let i = 0; i < ORDERS; i++) {
+        const order = {
+            orderId: `O${RUN}-${String(i + 1).padStart(2, '0')}`,
+            destination: destinations[i % destinations.length],
+            serviceLevel: Math.random() * 100 < EXPRESS_PCT ? 'express' : 'standard',
+        };
+        await api('POST', '/api/workflows/consolidationOrder/invoke', { data: order });
+        orders.push(order);
+        console.log(`[order] ${order.orderId} → ${order.destination} (${order.serviceLevel})`);
+    }
+    return orders;
+}
+async function finish(role, order) {
+    const row = await rowFor(role, { orderId: order.orderId });
+    await api('POST', `/api/escalations/${row.id}/resolve`, { resolverPayload: { ok: true } });
+    console.log(`[${role}] ${order.orderId} done`);
+    await sleep(STEP_MS);
+}
+async function place(order, bins) {
+    const bin = bins.find((b) => b.destination === order.destination && (!b.lane || b.lane === order.serviceLevel));
+    const member = await rowFor(ROLES.STAGE, { orderId: order.orderId });
+    await api('POST', `/api/escalations/${bin.id}/accumulate`, {
+        itemKey: order.orderId, payload: { weight: 1 }, reciprocal: { id: member.id },
+    });
+    console.log(`[place] ${order.orderId} → ${bin.destination}${bin.lane ? ` (${bin.lane})` : ''}`);
+    await sleep(STEP_MS);
+}
+async function main() {
+    const auth = await api('POST', '/api/auth/login', { username: USERNAME, password: PASSWORD });
+    token = auth.token;
+    const destinations = DESTINATION_NAMES.slice(0, Math.max(1, Math.min(DESTINATIONS, DESTINATION_NAMES.length)))
+        .map((d) => `${d}-${RUN}`);
+    // 1. Open the tubs, then start the orders at the first station.
+    const bins = await openBins(destinations);
+    const orders = await startOrders(destinations);
+    // 2. Walk the orders. Mid-flight (KEEP=1): a quarter stays at prep, a
+    //    quarter at check, a quarter staged, the rest placed.
+    const quarter = Math.ceil(orders.length / 4);
+    for (const [i, order] of orders.entries()) {
+        if (KEEP && i < quarter)
+            continue;
+        await finish(ROLES.PREP, order);
+        if (KEEP && i < quarter * 2)
+            continue;
+        await finish(ROLES.CHECK, order);
+        if (KEEP && i < quarter * 3)
+            continue;
+        await place(order, bins);
+    }
+    // 3. A mis-placed order comes back out: the bin's count drops by one.
+    const placed = KEEP ? orders.slice(quarter * 3) : orders;
+    const last = placed[placed.length - 1];
+    if (last) {
+        const bin = bins.find((b) => b.destination === last.destination && (!b.lane || b.lane === last.serviceLevel));
+        await api('POST', `/api/escalations/${bin.id}/remove-item`, { itemKey: last.orderId });
+        console.log(`[remove] ${last.orderId} out of ${bin.destination}`);
+    }
+    console.log(`\nDone (run ${RUN}). Open the Consolidate list: ${BASE_URL}/escalations/available?role=${ROLES.BIN}`);
+}
+main().catch((err) => {
+    console.error(`[consolidation-sim] ${err.message}`);
+    process.exit(1);
+});

package/build/sdk/index.d.ts CHANGED Viewed

@@ -291,6 +291,18 @@ export declare function createClient(options?: LTClientOptions): {
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         aggregateByFacets: (input: import("..").AggregateByFacetsInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         timelineByFacet: (input: import("..").TimelineByFacetInput, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        getRelated: (input: {
+            role: string;
+            ids: string[];
+            version?: number;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        getRelatedRows: (input: {
+            role: string;
+            id: string;
+            set: string;
+            version?: number;
+            limit?: number;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
     };
     workflows: {
         invoke: (input: {

package/build/sdk/index.js CHANGED Viewed

@@ -162,6 +162,8 @@ function createClient(options = {}) {
             // Analytics surface (grouped membership/dwell + per-entity timeline), read_all-gated.
             aggregateByFacets: bindAuth(escalationsApi.aggregateByFacets, auth),
             timelineByFacet: bindAuth(escalationsApi.timelineByFacet, auth),
+            getRelated: bindAuth(escalationsApi.getRelatedAggregates, auth),
+            getRelatedRows: bindAuth(escalationsApi.getRelatedRows, auth),
         },
         // ── Workflows ──────────────────────────────────────────────────────────
         workflows: {

package/build/services/escalation/grouped-list.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+import type { LTEscalationRecord } from '../../types';
+import { type ScopedFacetSearch } from './queries';
+/** One page group: the shared facet value (null for a row without it) and its rows. */
+export interface EscalationGroup {
+    key: string | null;
+    ids: string[];
+}
+/**
+ * Scoped faceted search paged by groups of a metadata facet. A page holds
+ * whole groups, so a group never splits across pages; a row without the
+ * facet is a group of one. `total` counts groups.
+ */
+export declare function searchEscalationsGrouped(opts: ScopedFacetSearch & {
+    groupKey: string;
+}): Promise<{
+    escalations: LTEscalationRecord[];
+    total: number;
+    groups: EscalationGroup[];
+}>;

package/build/services/escalation/grouped-list.js ADDED Viewed

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchEscalationsGrouped = searchEscalationsGrouped;
+const db_1 = require("../../lib/db");
+const client_1 = require("./client");
+const facet_sql_1 = require("./facet-sql");
+const map_1 = require("./map");
+const queries_1 = require("./queries");
+const SINGLETON_PREFIX = 'id:';
+/**
+ * Scoped faceted search paged by groups of a metadata facet. A page holds
+ * whole groups, so a group never splits across pages; a row without the
+ * facet is a group of one. `total` counts groups.
+ */
+async function searchEscalationsGrouped(opts) {
+    if (!facet_sql_1.FACET_KEY.test(opts.groupKey))
+        throw new Error(`groupBy must be a metadata key, got "${opts.groupKey}"`);
+    await (0, client_1.ensureEscalationCompatView)();
+    const pool = (0, db_1.getPool)();
+    const groupExpr = `COALESCE(metadata->>'${opts.groupKey}', '${SINGLETON_PREFIX}' || id::text)`;
+    const params = [];
+    const where = (0, queries_1.buildScopedSearchWhere)(opts, params);
+    const countParams = [...params];
+    const li = params.push(opts.limit);
+    const oi = params.push(opts.offset);
+    const [page, count] = await Promise.all([
+        pool.query(`SELECT ${groupExpr} AS g, bool_or(metadata->>'${opts.groupKey}' IS NOT NULL) AS keyed
+       FROM public.lt_escalations ${where}
+       GROUP BY 1 ORDER BY ${(0, facet_sql_1.buildGroupOrder)(opts.facet.orderBy)}, 1
+       LIMIT $${li} OFFSET $${oi}`, params),
+        pool.query(`SELECT count(DISTINCT ${groupExpr})::int AS total FROM public.lt_escalations ${where}`, countParams),
+    ]);
+    const keys = page.rows.map((r) => r.g);
+    const keyed = new Set(page.rows.filter((r) => r.keyed).map((r) => r.g));
+    const total = count.rows[0]?.total ?? 0;
+    if (!keys.length)
+        return { escalations: [], total, groups: [] };
+    const memberParams = [];
+    const memberWhere = (0, queries_1.buildScopedSearchWhere)(opts, memberParams);
+    const ki = memberParams.push(keys);
+    const keyClause = `${groupExpr} = ANY($${ki}::text[])`;
+    const members = await pool.query(`SELECT *, ${groupExpr} AS lt_group FROM public.lt_escalations
+     ${memberWhere ? `${memberWhere} AND ${keyClause}` : `WHERE ${keyClause}`}
+     ORDER BY ${(0, facet_sql_1.buildFacetOrder)(opts.facet.orderBy)}`, memberParams);
+    const byKey = new Map(keys.map((k) => [k, []]));
+    for (const row of members.rows)
+        byKey.get(row.lt_group)?.push(row.id);
+    const groups = keys.map((k) => ({
+        key: keyed.has(k) ? k : null,
+        ids: byKey.get(k) ?? [],
+    }));
+    const escalations = (0, map_1.toEscalationRecords)(members.rows.map(({ lt_group: _g, ...rest }) => rest));
+    return { escalations, total, groups };
+}

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

@@ -10,3 +10,7 @@ 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';
+export { searchEscalationsGrouped } from './grouped-list';
+export type { EscalationGroup } from './grouped-list';
+export { aggregateRelatedItems, listRelatedItems, aggregateRelatedQuery, listRelatedQueryRows, readRelatedHosts, } from './related';
+export type { RelatedQueryHost } from './related';

package/build/services/escalation/index.js CHANGED Viewed

@@ -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.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = exports.claimAssertedByMetadata = void 0;
+exports.readRelatedHosts = exports.listRelatedQueryRows = exports.aggregateRelatedQuery = exports.listRelatedItems = exports.aggregateRelatedItems = exports.searchEscalationsGrouped = exports.AnalyticsInputError = exports.resetAnalyticsCaches = exports.resolveEntitySystem = exports.timelineByFacet = exports.aggregateByFacets = exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = exports.claimAssertedByMetadata = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./crud"), exports);
 var claim_asserted_1 = require("./claim-asserted");
@@ -40,3 +40,11 @@ Object.defineProperty(exports, "resolveEntitySystem", { enumerable: true, get: f
 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; } });
+var grouped_list_1 = require("./grouped-list");
+Object.defineProperty(exports, "searchEscalationsGrouped", { enumerable: true, get: function () { return grouped_list_1.searchEscalationsGrouped; } });
+var related_1 = require("./related");
+Object.defineProperty(exports, "aggregateRelatedItems", { enumerable: true, get: function () { return related_1.aggregateRelatedItems; } });
+Object.defineProperty(exports, "listRelatedItems", { enumerable: true, get: function () { return related_1.listRelatedItems; } });
+Object.defineProperty(exports, "aggregateRelatedQuery", { enumerable: true, get: function () { return related_1.aggregateRelatedQuery; } });
+Object.defineProperty(exports, "listRelatedQueryRows", { enumerable: true, get: function () { return related_1.listRelatedQueryRows; } });
+Object.defineProperty(exports, "readRelatedHosts", { enumerable: true, get: function () { return related_1.readRelatedHosts; } });

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

@@ -1,18 +1,8 @@
 import type { LTEscalationRecord, LTEscalationStatus } from '../../types';
 import type { EscalationStats, StationMetric } from './types';
 import type { FacetQuery } from '../../types';
-/**
- * Scoped faceted search — the HUMAN operations query. Composes the read-scope
- * predicate (global → none; else `role ∈ allRoles OR (role ∈ selfRoles AND
- * assigned_to = me)`) with the full FacetQuery language (`buildFacetWhere`:
- * facets `@>`, block, numeric range, exists, status, available) plus the extra
- * top-level filters (type/subtype/priority/assigned_to) and an exact correlation-id
- * match (id/workflow_id/origin_id), then orders
- * by `buildFacetOrder` (columns + `metadata.<key>`). Every value is bound; the
- * COUNT shares the WHERE so totals stay correct across pages — no client-side
- * filtering. Reads go through the `public.lt_escalations` view.
- */
-export declare function searchEscalationsFaceted(opts: {
+/** The scoped faceted search input, shared by the row and grouped reads. */
+export type ScopedFacetSearch = {
     global?: boolean;
     visibleRoles?: string[];
     selfRoles?: string[];
@@ -25,7 +15,21 @@ export declare function searchEscalationsFaceted(opts: {
     search?: string;
     limit: number;
     offset: number;
-}): Promise<{
+};
+/** The WHERE clause of a scoped faceted search, pushing bound params. */
+export declare function buildScopedSearchWhere(opts: Omit<ScopedFacetSearch, 'limit' | 'offset'>, params: unknown[]): string;
+/**
+ * Scoped faceted search — the HUMAN operations query. Composes the read-scope
+ * predicate (global → none; else `role ∈ allRoles OR (role ∈ selfRoles AND
+ * assigned_to = me)`) with the full FacetQuery language (`buildFacetWhere`:
+ * facets `@>`, block, numeric range, exists, status, available) plus the extra
+ * top-level filters (type/subtype/priority/assigned_to) and an exact correlation-id
+ * match (id/workflow_id/origin_id), then orders
+ * by `buildFacetOrder` (columns + `metadata.<key>`). Every value is bound; the
+ * COUNT shares the WHERE so totals stay correct across pages — no client-side
+ * filtering. Reads go through the `public.lt_escalations` view.
+ */
+export declare function searchEscalationsFaceted(opts: ScopedFacetSearch): Promise<{
     escalations: LTEscalationRecord[];
     total: number;
 }>;

package/build/services/escalation/queries.js CHANGED Viewed

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildScopedSearchWhere = buildScopedSearchWhere;
 exports.searchEscalationsFaceted = searchEscalationsFaceted;
 exports.getEscalationWithFormSchema = getEscalationWithFormSchema;
 exports.listFacetKeys = listFacetKeys;
@@ -15,6 +16,7 @@ const db_1 = require("../../lib/db");
 const client_1 = require("./client");
 const map_1 = require("./map");
 const facet_sql_1 = require("./facet-sql");
+const read_scope_sql_1 = require("./read-scope-sql");
 const types_1 = require("./types");
 const sql_1 = require("./sql");
 const metrics_cache_1 = require("./metrics-cache");
@@ -88,31 +90,13 @@ async function searchEscalations(params) {
         total: countRows.rows[0]?.total ?? 0,
     };
 }
-/**
- * Scoped faceted search — the HUMAN operations query. Composes the read-scope
- * predicate (global → none; else `role ∈ allRoles OR (role ∈ selfRoles AND
- * assigned_to = me)`) with the full FacetQuery language (`buildFacetWhere`:
- * facets `@>`, block, numeric range, exists, status, available) plus the extra
- * top-level filters (type/subtype/priority/assigned_to) and an exact correlation-id
- * match (id/workflow_id/origin_id), then orders
- * by `buildFacetOrder` (columns + `metadata.<key>`). Every value is bound; the
- * COUNT shares the WHERE so totals stay correct across pages — no client-side
- * filtering. Reads go through the `public.lt_escalations` view.
- */
-async function searchEscalationsFaceted(opts) {
-    await (0, client_1.ensureEscalationCompatView)();
-    const pool = (0, db_1.getPool)();
-    const params = [];
+/** The WHERE clause of a scoped faceted search, pushing bound params. */
+function buildScopedSearchWhere(opts, params) {
     const clauses = [];
     // 1. Read-scope predicate (skip entirely for global access).
-    if (!opts.global) {
-        const ai = params.push(opts.visibleRoles?.length ? opts.visibleRoles : null);
-        const si = params.push(opts.selfRoles?.length ? opts.selfRoles : null);
-        const mi = params.push(opts.meUserId || null);
-        clauses.push(`(($${ai}::text[] IS NULL AND $${si}::text[] IS NULL)
-        OR ($${ai}::text[] IS NOT NULL AND role = ANY($${ai}))
-        OR ($${si}::text[] IS NOT NULL AND role = ANY($${si}) AND assigned_to = $${mi}))`);
-    }
+    const scopeClause = (0, read_scope_sql_1.buildReadScopeClause)(opts, params);
+    if (scopeClause)
+        clauses.push(scopeClause);
     // 2. Faceted predicate (role/roles/status/available/facets/block/range/exists).
     const facetClause = (0, facet_sql_1.buildFacetWhere)(opts.facet, params);
     if (facetClause !== 'TRUE')
@@ -135,7 +119,24 @@ async function searchEscalationsFaceted(opts) {
         const u = params.push(asUuidOrNull(opts.search));
         clauses.push(`(origin_id = $${i} OR workflow_id = $${i} OR ($${u}::uuid IS NOT NULL AND id = $${u}::uuid))`);
     }
-    const where = clauses.length ? `WHERE ${clauses.join('\n  AND ')}` : '';
+    return clauses.length ? `WHERE ${clauses.join('\n  AND ')}` : '';
+}
+/**
+ * Scoped faceted search — the HUMAN operations query. Composes the read-scope
+ * predicate (global → none; else `role ∈ allRoles OR (role ∈ selfRoles AND
+ * assigned_to = me)`) with the full FacetQuery language (`buildFacetWhere`:
+ * facets `@>`, block, numeric range, exists, status, available) plus the extra
+ * top-level filters (type/subtype/priority/assigned_to) and an exact correlation-id
+ * match (id/workflow_id/origin_id), then orders
+ * by `buildFacetOrder` (columns + `metadata.<key>`). Every value is bound; the
+ * COUNT shares the WHERE so totals stay correct across pages — no client-side
+ * filtering. Reads go through the `public.lt_escalations` view.
+ */
+async function searchEscalationsFaceted(opts) {
+    await (0, client_1.ensureEscalationCompatView)();
+    const pool = (0, db_1.getPool)();
+    const params = [];
+    const where = buildScopedSearchWhere(opts, params);
     const orderBy = (0, facet_sql_1.buildFacetOrder)(opts.facet.orderBy);
     const countParams = [...params];
     const li = params.push(opts.limit);
@@ -186,14 +187,9 @@ async function listFacetKeys(opts) {
     const pool = (0, db_1.getPool)();
     const params = [];
     const clauses = ["jsonb_typeof(metadata) = 'object'"];
-    if (!opts.global) {
-        const ai = params.push(opts.visibleRoles?.length ? opts.visibleRoles : null);
-        const si = params.push(opts.selfRoles?.length ? opts.selfRoles : null);
-        const mi = params.push(opts.meUserId || null);
-        clauses.push(`(($${ai}::text[] IS NULL AND $${si}::text[] IS NULL)
-        OR ($${ai}::text[] IS NOT NULL AND role = ANY($${ai}))
-        OR ($${si}::text[] IS NOT NULL AND role = ANY($${si}) AND assigned_to = $${mi}))`);
-    }
+    const scopeClause = (0, read_scope_sql_1.buildReadScopeClause)(opts, params);
+    if (scopeClause)
+        clauses.push(scopeClause);
     const { rows } = await pool.query(`SELECT DISTINCT jsonb_object_keys(metadata) AS key
        FROM public.lt_escalations
       WHERE ${clauses.join('\n        AND ')}
@@ -237,14 +233,9 @@ async function listFacetValues(key, opts) {
     const pool = (0, db_1.getPool)();
     const params = [key];
     const clauses = ["jsonb_typeof(metadata) = 'object'", 'metadata ? $1'];
-    if (!opts.global) {
-        const ai = params.push(opts.visibleRoles?.length ? opts.visibleRoles : null);
-        const si = params.push(opts.selfRoles?.length ? opts.selfRoles : null);
-        const mi = params.push(opts.meUserId || null);
-        clauses.push(`(($${ai}::text[] IS NULL AND $${si}::text[] IS NULL)
-        OR ($${ai}::text[] IS NOT NULL AND role = ANY($${ai}))
-        OR ($${si}::text[] IS NOT NULL AND role = ANY($${si}) AND assigned_to = $${mi}))`);
-    }
+    const scopeClause = (0, read_scope_sql_1.buildReadScopeClause)(opts, params);
+    if (scopeClause)
+        clauses.push(scopeClause);
     const { rows } = await pool.query(`SELECT DISTINCT metadata->>$1 AS value
        FROM public.lt_escalations
       WHERE ${clauses.join('\n        AND ')}

package/build/services/escalation/read-scope-sql.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+/** The caller's read scope, as the scoped escalation queries consume it. */
+export interface ReadScopeInput {
+    global?: boolean;
+    visibleRoles?: string[];
+    selfRoles?: string[];
+    meUserId?: string;
+}
+/**
+ * The read-scope predicate: `role ∈ visibleRoles OR (role ∈ selfRoles AND
+ * assigned_to = me)`. Null for global access. `alias` qualifies the columns
+ * when the query joins several escalation rows.
+ */
+export declare function buildReadScopeClause(scope: ReadScopeInput, params: unknown[], alias?: string): string | null;

package/build/services/escalation/read-scope-sql.js ADDED Viewed

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildReadScopeClause = buildReadScopeClause;
+/**
+ * The read-scope predicate: `role ∈ visibleRoles OR (role ∈ selfRoles AND
+ * assigned_to = me)`. Null for global access. `alias` qualifies the columns
+ * when the query joins several escalation rows.
+ */
+function buildReadScopeClause(scope, params, alias) {
+    if (scope.global)
+        return null;
+    const col = (name) => (alias ? `${alias}.${name}` : name);
+    const ai = params.push(scope.visibleRoles?.length ? scope.visibleRoles : null);
+    const si = params.push(scope.selfRoles?.length ? scope.selfRoles : null);
+    const mi = params.push(scope.meUserId || null);
+    return `(($${ai}::text[] IS NULL AND $${si}::text[] IS NULL)
+        OR ($${ai}::text[] IS NOT NULL AND ${col('role')} = ANY($${ai}))
+        OR ($${si}::text[] IS NOT NULL AND ${col('role')} = ANY($${si}) AND ${col('assigned_to')} = $${mi}))`;
+}

package/build/services/escalation/related.d.ts ADDED Viewed

@@ -0,0 +1,58 @@
+import { type RelatedHostAggregate, type RelatedRow } from '../../shared/list-schema';
+import { type ReadScopeInput } from './read-scope-sql';
+/** One host's resolved facet match for a query set. */
+export interface RelatedQueryHost {
+    hostId: string;
+    match: Record<string, unknown>;
+}
+export interface RelatedQueryInput {
+    hosts: RelatedQueryHost[];
+    roles: string[];
+    status: string;
+    scope: ReadScopeInput;
+}
+type Aggregates = Record<string, RelatedHostAggregate>;
+/**
+ * Count each host's items, optionally split by `payload.<path>` or
+ * `reciprocal.metadata.<key>`. A reciprocal split counts only reciprocal rows
+ * the caller can read; the rest are reported as `hidden`. `roles` names the
+ * roles of the readable reciprocal rows, so a list can follow their changes.
+ */
+export declare function aggregateRelatedItems(opts: {
+    hostIds: string[];
+    scope: ReadScopeInput;
+    splitBy?: string;
+}): Promise<{
+    aggregates: Aggregates;
+    roles: string[];
+}>;
+/** One host's items in fill order, each with its reciprocal row when readable. */
+export declare function listRelatedItems(opts: {
+    hostId: string;
+    scope: ReadScopeInput;
+    limit: number;
+}): Promise<{
+    rows: RelatedRow[];
+    total: number;
+}>;
+/**
+ * Count the rows that share each host's facets, grouped by role and an
+ * optional `metadata.<key>` split. The GIN index serves each host's match.
+ */
+export declare function aggregateRelatedQuery(input: RelatedQueryInput & {
+    splitBy?: string;
+}): Promise<Aggregates>;
+/** One host's related rows, in role order then age. */
+export declare function listRelatedQueryRows(input: RelatedQueryInput & {
+    limit: number;
+}): Promise<{
+    rows: RelatedRow[];
+    total: number;
+}>;
+/** Host rows of one role, read under the caller's scope. */
+export declare function readRelatedHosts(opts: {
+    ids: string[];
+    role: string;
+    scope: ReadScopeInput;
+}): Promise<Record<string, unknown>[]>;
+export {};