@hotmeshio/long-tail 0.23.1 → 0.24.0

package/build/services/auth/oauth-server/store.js

@@ -0,0 +1,151 @@
+"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.isClientId = exports.REFRESH_REUSE_GRACE_SECONDS = void 0;
+exports.createSecret = createSecret;
+exports.hashSecret = hashSecret;
+exports.pkceChallenge = pkceChallenge;
+exports.registerClient = registerClient;
+exports.getClient = getClient;
+exports.issueAuthorizationCode = issueAuthorizationCode;
+exports.exchangeAuthorizationCode = exchangeAuthorizationCode;
+exports.rotateRefreshToken = rotateRefreshToken;
+exports.getLiveGrant = getLiveGrant;
+exports.revokeByRefreshToken = revokeByRefreshToken;
+exports.revokeGrant = revokeGrant;
+exports.listGrants = listGrants;
+const crypto = __importStar(require("crypto"));
+const db_1 = require("../../../lib/db");
+const uuid_1 = require("../../../lib/uuid");
+const sql_1 = require("./sql");
+/** A refresh token reused within this many seconds is treated as a client retry. */
+exports.REFRESH_REUSE_GRACE_SECONDS = 10;
+/** A new random secret: 32 bytes, base64url. */
+function createSecret() {
+    return crypto.randomBytes(32).toString('base64url');
+}
+/** SHA-256 of a secret. Codes and refresh tokens are stored only as hashes. */
+function hashSecret(secret) {
+    return crypto.createHash('sha256').update(secret).digest('hex');
+}
+/** The PKCE S256 challenge for a code verifier (RFC 7636). */
+function pkceChallenge(verifier) {
+    return crypto.createHash('sha256').update(verifier).digest('base64url');
+}
+async function registerClient(input) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.INSERT_CLIENT, [
+        `ltc_${createSecret()}`, input.clientName ?? null, input.redirectUris,
+    ]);
+    return rows[0];
+}
+/** A client id as registerClient issues it; anything else names no client and never reaches SQL. */
+const CLIENT_ID = /^ltc_[A-Za-z0-9_-]{43}$/;
+const isClientId = (value) => CLIENT_ID.test(value);
+exports.isClientId = isClientId;
+async function getClient(clientId) {
+    if (!(0, exports.isClientId)(clientId))
+        return null;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_CLIENT, [clientId]);
+    return rows[0] ?? null;
+}
+/** Record the person's consent as a grant and return a one-time code for it. */
+async function issueAuthorizationCode(input) {
+    if (!(0, uuid_1.isUuid)(input.userId))
+        throw new Error('issueAuthorizationCode: userId must be a UUID');
+    const code = createSecret();
+    const { rows } = await (0, db_1.getPool)().query(sql_1.ISSUE_CODE, [
+        input.userId, input.clientId, input.policy, input.scope,
+        hashSecret(code), input.redirectUri, input.codeChallenge, input.resource ?? null, input.ttlSeconds,
+    ]);
+    return { code, grantId: rows[0].grant_id };
+}
+/**
+ * Exchange a code for the grant and its first refresh token. Null when the
+ * code is unknown, used, expired, for another client or redirect URI, fails
+ * PKCE, or its grant or owner is no longer active.
+ */
+async function exchangeAuthorizationCode(input) {
+    const refreshToken = createSecret();
+    const { rows } = await (0, db_1.getPool)().query(sql_1.EXCHANGE_CODE, [
+        hashSecret(input.code), input.clientId, input.redirectUri, pkceChallenge(input.codeVerifier),
+        hashSecret(refreshToken), input.refreshTtlSeconds,
+    ]);
+    if (!rows[0])
+        return null;
+    const { resource, ...snapshot } = rows[0];
+    return { snapshot, resource, refreshToken };
+}
+/**
+ * Rotate a refresh token for the client that holds it. Null when it is
+ * unknown, used, expired, another client's, or its grant or owner is no
+ * longer active. A used token presented again outside the
+ * grace window revokes its grant, and `revoked` reports it.
+ */
+async function rotateRefreshToken(input) {
+    const pool = (0, db_1.getPool)();
+    const next = createSecret();
+    const oldHash = hashSecret(input.refreshToken);
+    const { rows } = await pool.query(sql_1.ROTATE_REFRESH_TOKEN, [oldHash, hashSecret(next), input.refreshTtlSeconds, input.clientId]);
+    if (rows[0])
+        return { snapshot: rows[0], refreshToken: next };
+    const reuse = await pool.query(sql_1.REVOKE_ON_REFRESH_REUSE, [oldHash, exports.REFRESH_REUSE_GRACE_SECONDS]);
+    return { snapshot: null, revoked: reuse.rows[0] ?? null };
+}
+/** The live grant an access token names; null when it is revoked, its owner inactive, or it is another user's. */
+async function getLiveGrant(grantId, userId) {
+    if (!(0, uuid_1.isUuid)(grantId) || !(0, uuid_1.isUuid)(userId))
+        return null;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.GET_LIVE_GRANT, [grantId, userId]);
+    return rows[0] ?? null;
+}
+/** Revoke the grant behind a refresh token presented by its own client (RFC 7009). */
+async function revokeByRefreshToken(refreshToken, clientId) {
+    const { rows } = await (0, db_1.getPool)().query(sql_1.REVOKE_BY_REFRESH_TOKEN, [hashSecret(refreshToken), clientId]);
+    return rows[0] ?? null;
+}
+/** Revoke a grant; with `userId`, only when it belongs to that user. */
+async function revokeGrant(grantId, userId) {
+    if (!(0, uuid_1.isUuid)(grantId) || (userId !== undefined && !(0, uuid_1.isUuid)(userId)))
+        return null;
+    const { rows } = await (0, db_1.getPool)().query(sql_1.REVOKE_GRANT, [grantId, userId ?? null]);
+    return rows[0] ?? null;
+}
+/** The person's live grants that a client has put to use. */
+async function listGrants(userId) {
+    if (!(0, uuid_1.isUuid)(userId))
+        return [];
+    const { rows } = await (0, db_1.getPool)().query(sql_1.LIST_GRANTS, [userId]);
+    return rows;
+}

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

@@ -3,6 +3,7 @@ export declare const GET_BOT_KEYS_BY_USER = "\n  SELECT id, name, user_id, key_h
 export declare const GET_ALL_ACTIVE_BOT_KEYS = "\n  SELECT id, name, user_id, key_hash, scopes\n  FROM lt_bot_api_keys\n  WHERE (expires_at IS NULL OR expires_at > NOW())";
 export declare const UPDATE_BOT_KEY_LAST_USED = "\n  UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1";
 export declare const DELETE_BOT_KEY = "\n  DELETE FROM lt_bot_api_keys WHERE id = $1";
+export declare const GET_BOT_KEY_OWNER = "\n  SELECT user_id FROM lt_bot_api_keys WHERE id = $1";
 export declare const LIST_BOT_KEYS_BY_USER = "\n  SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at\n  FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at";
 export declare const INSERT_SERVICE_TOKEN = "\n  INSERT INTO lt_service_tokens (name, token_hash, server_id, scopes, expires_at)\n  VALUES ($1, $2, $3, $4, $5) RETURNING id";
 export declare const GET_ALL_ACTIVE_SERVICE_TOKENS = "\n  SELECT id, name, token_hash FROM lt_service_tokens\n  WHERE (expires_at IS NULL OR expires_at > NOW())";

package/build/services/auth/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ── Bot API key queries ─────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LIST_SERVICE_TOKENS_BY_SERVER = exports.DELETE_SERVICE_TOKEN = exports.UPDATE_SERVICE_TOKEN_LAST_USED = exports.GET_ALL_ACTIVE_SERVICE_TOKENS = exports.INSERT_SERVICE_TOKEN = exports.LIST_BOT_KEYS_BY_USER = exports.DELETE_BOT_KEY = exports.UPDATE_BOT_KEY_LAST_USED = exports.GET_ALL_ACTIVE_BOT_KEYS = exports.GET_BOT_KEYS_BY_USER = exports.INSERT_BOT_KEY = void 0;
+exports.LIST_SERVICE_TOKENS_BY_SERVER = exports.DELETE_SERVICE_TOKEN = exports.UPDATE_SERVICE_TOKEN_LAST_USED = exports.GET_ALL_ACTIVE_SERVICE_TOKENS = exports.INSERT_SERVICE_TOKEN = exports.LIST_BOT_KEYS_BY_USER = exports.GET_BOT_KEY_OWNER = exports.DELETE_BOT_KEY = exports.UPDATE_BOT_KEY_LAST_USED = exports.GET_ALL_ACTIVE_BOT_KEYS = exports.GET_BOT_KEYS_BY_USER = exports.INSERT_BOT_KEY = void 0;
 exports.INSERT_BOT_KEY = `
   INSERT INTO lt_bot_api_keys (name, user_id, key_hash, scopes, expires_at)
   VALUES ($1, $2, $3, $4, $5) RETURNING id`;
@@ -18,6 +18,8 @@ exports.UPDATE_BOT_KEY_LAST_USED = `
   UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1`;
 exports.DELETE_BOT_KEY = `
   DELETE FROM lt_bot_api_keys WHERE id = $1`;
+exports.GET_BOT_KEY_OWNER = `
+  SELECT user_id FROM lt_bot_api_keys WHERE id = $1`;
 exports.LIST_BOT_KEYS_BY_USER = `
   SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at
   FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at`;

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

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

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

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

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

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

@@ -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 ')}
@@ -287,8 +278,13 @@ async function listDistinctTypes() {
  * and an out-of-scope role yields an empty result, not someone else's rows.
  */
 function narrowRoleWithinScope(role, visibleRoles) {
-    if (!role || !visibleRoles)
-        return { role, roles: visibleRoles, empty: false };
+    if (!visibleRoles)
+        return { role, roles: undefined, empty: false };
+    // An empty scope sees nothing; the SDK would read an empty list as no filter.
+    if (visibleRoles.length === 0)
+        return { empty: true };
+    if (!role)
+        return { roles: visibleRoles, empty: false };
     if (!visibleRoles.includes(role))
         return { empty: true };
     return { role, roles: undefined, empty: false };

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

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

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

@@ -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 {};