@hotmeshio/long-tail 0.5.12 → 0.6.2

package/build/services/escalation/facets.js

@@ -0,0 +1,218 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Faceted escalation access — a rich search/claim interface over the queue so a
+// consuming app can implement routing *strategies* against the data facets
+// (metadata, priority, …). The platform supplies the surface; the policy
+// (capability, priority, capacity packing, the loop) is the app's (see examples/).
+//
+// The dispatcher pattern: pull a *page* of complete orders (page size = how many
+// printers/consumers are free), then distribute one order per consumer. Reads go
+// through the `public.lt_escalations` view; atomic claims run on
+// `public.hmsh_escalations` with FOR UPDATE SKIP LOCKED, so many dispatchers run
+// without contention. An order is a set of escalations sharing `origin_id`; its
+// unit count lives in a metadata facet (default `orderSize`) the app saves, so a
+// group is claimed all-or-nothing only when complete.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureFacetReady = ensureFacetReady;
+exports.searchByFacets = searchByFacets;
+exports.searchGroups = searchGroups;
+exports.countByFacets = countByFacets;
+exports.claimGroups = claimGroups;
+exports.claimByFacets = claimByFacets;
+const db_1 = require("../../lib/db");
+const client_1 = require("./client");
+const map_1 = require("./map");
+const facet_sql_1 = require("./facet-sql");
+const DEFAULT_LIMIT = 50;
+const DEFAULT_CLAIM_MINUTES = 30;
+const DEFAULT_SIZE_FACET = 'orderSize';
+/** Extra candidates fetched per claim so contention skips still fill the page. */
+const CANDIDATE_OVERSCAN = 4;
+let ready = null;
+/** Ensure the compat view + the origin_id index exist before the first query. */
+function ensureFacetReady() {
+    if (!ready) {
+        ready = (async () => {
+            await (0, client_1.ensureEscalationCompatView)(); // hmsh_escalations + lt_escalations view
+            await (0, db_1.getPool)().query(facet_sql_1.ENSURE_ORIGIN_INDEX);
+        })();
+    }
+    return ready;
+}
+// ── Reads ────────────────────────────────────────────────────────────────────
+/** Item-level faceted search — filter/sort over top-level columns and metadata facets. */
+async function searchByFacets(query) {
+    await ensureFacetReady();
+    const pool = (0, db_1.getPool)();
+    const params = [];
+    const where = (0, facet_sql_1.buildFacetWhere)(query, params);
+    const order = (0, facet_sql_1.buildFacetOrder)(query.orderBy);
+    const limit = query.limit ?? DEFAULT_LIMIT;
+    const offset = query.offset ?? 0;
+    const [rows, count] = await Promise.all([
+        pool.query(`SELECT * FROM public.lt_escalations WHERE ${where} ORDER BY ${order} LIMIT $${params.length + 1} OFFSET $${params.length + 2}`, [...params, limit, offset]),
+        pool.query(`SELECT count(*)::int AS total FROM public.lt_escalations WHERE ${where}`, params),
+    ]);
+    return { escalations: (0, map_1.toEscalationRecords)(rows.rows), total: count.rows[0]?.total ?? 0 };
+}
+/**
+ * Order-level view of the pond — what a batched dispatcher reads to page by
+ * capacity. Each row is an order (origin) with its unit count, availability and
+ * completeness, so the app grabs only as many orders as it has free consumers.
+ */
+async function searchGroups(query, opts = {}) {
+    await ensureFacetReady();
+    const sizeFacet = opts.sizeFacet ?? DEFAULT_SIZE_FACET;
+    const params = [sizeFacet]; // $1 = metadata key holding the unit count
+    const where = (0, facet_sql_1.buildFacetWhere)(query, params);
+    const groupOrder = (0, facet_sql_1.buildGroupOrder)(query.orderBy);
+    const limit = opts.limit ?? DEFAULT_LIMIT;
+    const offset = opts.offset ?? 0;
+    const { rows } = await (0, db_1.getPool)().query(`SELECT origin_id,
+            count(*)::int                                   AS member_count,
+            max((metadata->>$1)::int)                       AS order_size,
+            bool_and(assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()) AS available,
+            (max((metadata->>$1)::int) IS NULL OR count(*) >= max((metadata->>$1)::int)) AS complete,
+            min(priority)::int                              AS min_priority,
+            min(created_at)                                 AS created_at
+     FROM public.lt_escalations
+     WHERE origin_id IS NOT NULL AND ${where}
+     GROUP BY origin_id
+     ORDER BY ${groupOrder}
+     LIMIT $${params.length + 1} OFFSET $${params.length + 2}`, [...params, limit, offset]);
+    return rows.map((r) => ({
+        originId: r.origin_id,
+        memberCount: r.member_count,
+        orderSize: r.order_size ?? null,
+        available: r.available,
+        complete: r.complete,
+        minPriority: r.min_priority,
+        createdAt: r.created_at,
+    }));
+}
+/** Aggregate count — capacity / in-flight soft-limit checks. */
+async function countByFacets(query) {
+    await ensureFacetReady();
+    const params = [];
+    const where = (0, facet_sql_1.buildFacetWhere)(query, params);
+    const { rows } = await (0, db_1.getPool)().query(`SELECT count(*)::int AS n FROM public.lt_escalations WHERE ${where}`, params);
+    return rows[0]?.n ?? 0;
+}
+// ── Claim ────────────────────────────────────────────────────────────────────
+/** Lock + completeness-check + claim one order inside an open transaction. */
+async function tryClaimGroup(client, originId, consumer, durationMinutes, sizeFacet) {
+    const locked = await client.query(`SELECT id, (metadata->>$2)::int AS order_size,
+            (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()) AS avail
+     FROM public.hmsh_escalations
+     WHERE origin_id = $1 AND status = 'pending'
+     FOR UPDATE SKIP LOCKED`, [originId, sizeFacet]);
+    const members = locked.rows;
+    const declared = members.reduce((m, r) => Math.max(m, r.order_size ?? 0), 0);
+    const expected = declared > 0 ? declared : members.length;
+    const allAvailable = members.length > 0 && members.every((r) => r.avail);
+    if (members.length !== expected || !allAvailable)
+        return null; // contended / incomplete
+    const claimed = await client.query(`UPDATE public.hmsh_escalations e
+     SET assigned_to = $2, assigned_until = NOW() + make_interval(mins => $3),
+         claim_expires_at = NOW() + make_interval(mins => $3),
+         claimed_at = COALESCE(e.claimed_at, NOW()), updated_at = NOW()
+     WHERE e.origin_id = $1 AND e.status = 'pending' RETURNING e.*`, [originId, consumer, durationMinutes]);
+    return { originId, members: (0, map_1.toEscalationRecords)(claimed.rows) };
+}
+/**
+ * Pull a *page* of complete orders — the dispatcher primitive. Claims up to
+ * `limit` eligible orders (each all-or-nothing) in rank order, skipping any a
+ * competing dispatcher holds. Page `limit` = how many consumers/printers are
+ * free, so a dependent grabs exactly as much as it can distribute. `limit=1`
+ * claims a single order.
+ */
+async function claimGroups(query, consumer, opts = {}) {
+    await ensureFacetReady();
+    const limit = Math.max(1, opts.limit ?? 1);
+    const durationMinutes = opts.durationMinutes ?? DEFAULT_CLAIM_MINUTES;
+    const sizeFacet = opts.sizeFacet ?? DEFAULT_SIZE_FACET;
+    const pool = (0, db_1.getPool)();
+    const client = await pool.connect();
+    try {
+        const params = [sizeFacet];
+        const where = (0, facet_sql_1.buildFacetWhere)({ ...query, status: query.status ?? 'pending' }, params);
+        const groupOrder = (0, facet_sql_1.buildGroupOrder)(query.orderBy);
+        const cands = await client.query(`SELECT origin_id FROM public.hmsh_escalations
+       WHERE origin_id IS NOT NULL AND ${where}
+       GROUP BY origin_id
+       HAVING bool_and(assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW())
+          AND count(*) = COALESCE(max((metadata->>$1)::int), count(*))
+       ORDER BY ${groupOrder}
+       LIMIT ${limit * CANDIDATE_OVERSCAN}`, params);
+        await client.query('BEGIN');
+        const claimed = [];
+        for (const { origin_id: originId } of cands.rows) {
+            if (claimed.length >= limit)
+                break;
+            const group = await tryClaimGroup(client, originId, consumer, durationMinutes, sizeFacet);
+            if (group)
+                claimed.push(group);
+        }
+        await client.query('COMMIT');
+        return claimed;
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => { });
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Batch-claim *individual* escalations matching a facet query — the single-row
+ * sibling of `claimGroups`. Locks up to `limit` available rows in rank order with
+ * `FOR UPDATE SKIP LOCKED`, so concurrent claimers take disjoint sets without
+ * contention. With `allOrNone`, the claim commits only when the full `limit` was
+ * acquired (otherwise it rolls back and returns `[]`) — the all-or-none lock a
+ * dispatcher wants over a counted set it anticipated. Returns the claimed records.
+ */
+async function claimByFacets(query, consumer, opts = {}) {
+    await ensureFacetReady();
+    const limit = Math.max(1, opts.limit ?? 1);
+    const durationMinutes = opts.durationMinutes ?? DEFAULT_CLAIM_MINUTES;
+    const pool = (0, db_1.getPool)();
+    const client = await pool.connect();
+    try {
+        const params = [];
+        const where = (0, facet_sql_1.buildFacetWhere)({ ...query, available: true, status: query.status ?? 'pending' }, params);
+        const order = (0, facet_sql_1.buildFacetOrder)(query.orderBy);
+        const consumerIdx = params.length + 1;
+        const durationIdx = params.length + 2;
+        // One atomic statement: a FOR UPDATE SKIP LOCKED CTE picks the rank-ordered
+        // page, the UPDATE claims exactly those rows. RETURNING count = rows acquired.
+        await client.query('BEGIN');
+        const claimed = await client.query(`WITH locked AS (
+         SELECT id FROM public.hmsh_escalations
+         WHERE ${where}
+         ORDER BY ${order}
+         LIMIT ${limit}
+         FOR UPDATE SKIP LOCKED
+       )
+       UPDATE public.hmsh_escalations e
+       SET assigned_to = $${consumerIdx}, assigned_until = NOW() + make_interval(mins => $${durationIdx}),
+           claim_expires_at = NOW() + make_interval(mins => $${durationIdx}),
+           claimed_at = COALESCE(e.claimed_at, NOW()), updated_at = NOW()
+       FROM locked WHERE e.id = locked.id
+       RETURNING e.*`, [...params, consumer, durationMinutes]);
+        if (claimed.rows.length === 0 || (opts.allOrNone && claimed.rows.length < limit)) {
+            await client.query('ROLLBACK'); // all-or-none unmet, or nothing eligible
+            return [];
+        }
+        await client.query('COMMIT');
+        return (0, map_1.toEscalationRecords)(claimed.rows);
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => { });
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}

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

@@ -3,3 +3,4 @@ export * from './crud';
 export * from './bulk';
 export * from './queries';
 export { ensureEscalationCompatView } from './client';
+export { ensureFacetReady, searchByFacets, searchGroups, countByFacets, claimGroups, claimByFacets, } from './facets';

package/build/services/escalation/index.js

@@ -14,10 +14,17 @@ 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.ensureEscalationCompatView = void 0;
+exports.claimByFacets = exports.claimGroups = exports.countByFacets = exports.searchGroups = exports.searchByFacets = exports.ensureFacetReady = exports.ensureEscalationCompatView = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./crud"), exports);
 __exportStar(require("./bulk"), exports);
 __exportStar(require("./queries"), exports);
 var client_1 = require("./client");
 Object.defineProperty(exports, "ensureEscalationCompatView", { enumerable: true, get: function () { return client_1.ensureEscalationCompatView; } });
+var facets_1 = require("./facets");
+Object.defineProperty(exports, "ensureFacetReady", { enumerable: true, get: function () { return facets_1.ensureFacetReady; } });
+Object.defineProperty(exports, "searchByFacets", { enumerable: true, get: function () { return facets_1.searchByFacets; } });
+Object.defineProperty(exports, "searchGroups", { enumerable: true, get: function () { return facets_1.searchGroups; } });
+Object.defineProperty(exports, "countByFacets", { enumerable: true, get: function () { return facets_1.countByFacets; } });
+Object.defineProperty(exports, "claimGroups", { enumerable: true, get: function () { return facets_1.claimGroups; } });
+Object.defineProperty(exports, "claimByFacets", { enumerable: true, get: function () { return facets_1.claimByFacets; } });

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

@@ -1,5 +1,45 @@
 import type { LTEscalationRecord, LTEscalationStatus } from '../../types';
 import type { EscalationStats } 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 free-text, 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: {
+    global?: boolean;
+    visibleRoles?: string[];
+    selfRoles?: string[];
+    meUserId?: string;
+    facet: FacetQuery;
+    type?: string;
+    subtype?: string;
+    priority?: number;
+    assigned_to?: string;
+    search?: string;
+    limit: number;
+    offset: number;
+}): Promise<{
+    escalations: LTEscalationRecord[];
+    total: number;
+}>;
+/**
+ * Distinct top-level metadata facet KEYS visible to the caller — feeds the faceted
+ * UI's key autocomplete so it only ever offers facets that ACTUALLY exist in the
+ * caller's rows (a key in metadata, not description text). Role-scoped with the same
+ * predicate as the list; only object-typed metadata is unpacked (`jsonb_object_keys`).
+ */
+export declare function listFacetKeys(opts: {
+    global?: boolean;
+    visibleRoles?: string[];
+    selfRoles?: string[];
+    meUserId?: string;
+}): Promise<string[]>;
 export declare function getEscalationStats(visibleRoles?: string[], period?: string): Promise<EscalationStats>;
 export declare function listDistinctTypes(): Promise<string[]>;
 export declare function listEscalations(filters: {
@@ -13,9 +53,12 @@ export declare function listEscalations(filters: {
     limit?: number;
     offset?: number;
     visibleRoles?: string[];
+    selfRoles?: string[];
+    meUserId?: string;
     sort_by?: string;
     order?: string;
     search?: string;
+    metadata?: Record<string, any>;
 }): Promise<{
     escalations: LTEscalationRecord[];
     total: number;
@@ -31,6 +74,8 @@ export declare function listAvailableEscalations(filters: {
     limit?: number;
     offset?: number;
     visibleRoles?: string[];
+    selfRoles?: string[];
+    meUserId?: string;
     sort_by?: string;
     order?: string;
     search?: string;

package/build/services/escalation/queries.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchEscalationsFaceted = searchEscalationsFaceted;
+exports.listFacetKeys = listFacetKeys;
 exports.getEscalationStats = getEscalationStats;
 exports.listDistinctTypes = listDistinctTypes;
 exports.listEscalations = listEscalations;
@@ -7,6 +9,7 @@ exports.listAvailableEscalations = listAvailableEscalations;
 const db_1 = require("../../lib/db");
 const client_1 = require("./client");
 const map_1 = require("./map");
+const facet_sql_1 = require("./facet-sql");
 const types_1 = require("./types");
 const sql_1 = require("./sql");
 /**
@@ -44,7 +47,8 @@ async function searchEscalations(params) {
     const pool = (0, db_1.getPool)();
     // Coerce empty strings to NULL so an absent filter (e.g. assigned_to='') does
     // not become `column = ''` and match zero rows. Mirrors the SDK path's
-    // `if (filters.x)` truthiness guards.
+    // `if (filters.x)` truthiness guards. An empty search term means "no free-text
+    // filter" — this path also serves scoped (self-role) listing with no search.
     const filterArgs = [
         params.status || null,
         params.role || null,
@@ -54,7 +58,10 @@ async function searchEscalations(params) {
         params.priority ?? null,
         params.assigned_to || null,
         params.available ?? null,
-        params.search,
+        params.search || null,
+        params.selfRoles && params.selfRoles.length ? params.selfRoles : null,
+        params.meUserId || null,
+        params.metadata ? JSON.stringify(params.metadata) : null,
     ];
     const orderBy = buildSearchOrderBy(params.sort_by, params.order);
     const [rows, countRows] = await Promise.all([
@@ -66,6 +73,87 @@ 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 free-text, 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 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}))`);
+    }
+    // 2. Faceted predicate (role/roles/status/available/facets/block/range/exists).
+    const facetClause = (0, facet_sql_1.buildFacetWhere)(opts.facet, params);
+    if (facetClause !== 'TRUE')
+        clauses.push(facetClause);
+    // 3. Extra top-level filters not expressed by FacetQuery.
+    if (opts.type)
+        clauses.push(`type = $${params.push(opts.type)}`);
+    if (opts.subtype)
+        clauses.push(`subtype = $${params.push(opts.subtype)}`);
+    if (opts.priority != null)
+        clauses.push(`priority = $${params.push(opts.priority)}`);
+    if (opts.assigned_to)
+        clauses.push(`assigned_to = $${params.push(opts.assigned_to)}`);
+    // 4. Free-text (same fields as the list search path).
+    if (opts.search) {
+        const i = params.push(opts.search);
+        clauses.push(`(description ILIKE '%' || $${i} || '%' OR type ILIKE '%' || $${i} || '%'
+        OR subtype ILIKE '%' || $${i} || '%' OR role ILIKE '%' || $${i} || '%'
+        OR workflow_id ILIKE '%' || $${i} || '%' OR origin_id ILIKE '%' || $${i} || '%'
+        OR id::text ILIKE '%' || $${i} || '%' OR metadata::text ILIKE '%' || $${i} || '%')`);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join('\n  AND ')}` : '';
+    const orderBy = (0, facet_sql_1.buildFacetOrder)(opts.facet.orderBy);
+    const countParams = [...params];
+    const li = params.push(opts.limit);
+    const oi = params.push(opts.offset);
+    const [rows, countRows] = await Promise.all([
+        pool.query(`SELECT * FROM public.lt_escalations ${where} ORDER BY ${orderBy} LIMIT $${li} OFFSET $${oi}`, params),
+        pool.query(`SELECT COUNT(*)::int AS total FROM public.lt_escalations ${where}`, countParams),
+    ]);
+    return { escalations: (0, map_1.toEscalationRecords)(rows.rows), total: countRows.rows[0]?.total ?? 0 };
+}
+/**
+ * Distinct top-level metadata facet KEYS visible to the caller — feeds the faceted
+ * UI's key autocomplete so it only ever offers facets that ACTUALLY exist in the
+ * caller's rows (a key in metadata, not description text). Role-scoped with the same
+ * predicate as the list; only object-typed metadata is unpacked (`jsonb_object_keys`).
+ */
+async function listFacetKeys(opts) {
+    await (0, client_1.ensureEscalationCompatView)();
+    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 { rows } = await pool.query(`SELECT DISTINCT jsonb_object_keys(metadata) AS key
+       FROM public.lt_escalations
+      WHERE ${clauses.join('\n        AND ')}
+      ORDER BY key`, params);
+    return rows.map((r) => r.key);
+}
 async function getEscalationStats(visibleRoles, period) {
     const client = await (0, client_1.escalations)();
     return client.stats({
@@ -80,18 +168,25 @@ async function listDistinctTypes() {
 async function listEscalations(filters) {
     // Active claim semantics: assigned_to-active and `claimed` both mean "held now".
     const heldNow = !!(filters.assigned_to || filters.claimed);
-    // Free-text search → server-side SQL path (the SDK list() has no free-text).
-    if (filters.search) {
+    const hasSelfScope = !!(filters.selfRoles && filters.selfRoles.length);
+    // Free-text search OR read_self scoping → server-side SQL path. The SDK list()
+    // has no free-text and cannot express the (role ∈ selfRoles AND assigned_to=me)
+    // self-scope branch, so both route through the raw-SQL search query (which also
+    // serves metadata-containment for findByMetadata's self-scope callers).
+    if (filters.search || hasSelfScope) {
         return searchEscalations({
             status: filters.status,
             role: filters.role,
             roles: filters.visibleRoles,
+            selfRoles: filters.selfRoles,
+            meUserId: filters.meUserId,
             type: filters.type,
             subtype: filters.subtype,
             priority: filters.priority,
             assigned_to: filters.assigned_to,
             available: heldNow ? false : undefined,
             search: filters.search,
+            metadata: filters.metadata,
             limit: filters.limit ?? 50,
             offset: filters.offset ?? 0,
             sort_by: filters.sort_by,
@@ -112,6 +207,8 @@ async function listEscalations(filters) {
         where.assignedTo = filters.assigned_to;
     if (heldNow)
         where.available = false;
+    if (filters.metadata)
+        where.metadata = filters.metadata;
     const [rows, total] = await Promise.all([
         client.list({
             ...where,
@@ -127,12 +224,16 @@ async function listEscalations(filters) {
  * List available escalations: pending AND (unassigned OR expired claim).
  */
 async function listAvailableEscalations(filters) {
-    // Free-text search → server-side SQL path (available = pending + no active claim).
-    if (filters.search) {
+    const hasSelfScope = !!(filters.selfRoles && filters.selfRoles.length);
+    // Free-text search OR read_self scoping → server-side SQL path
+    // (available = pending + no active claim).
+    if (filters.search || hasSelfScope) {
         return searchEscalations({
             status: 'pending',
             role: filters.role,
             roles: filters.visibleRoles,
+            selfRoles: filters.selfRoles,
+            meUserId: filters.meUserId,
             type: filters.type,
             subtype: filters.subtype,
             priority: filters.priority,

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

@@ -8,8 +8,8 @@
  * table. Clears both `assigned_until` and `claim_expires_at`.
  */
 export declare const RELEASE_EXPIRED_CLAIMS = "UPDATE public.hmsh_escalations\nSET assigned_to = NULL,\n    assigned_until = NULL,\n    claimed_at = NULL,\n    claim_expires_at = NULL,\n    updated_at = NOW()\nWHERE status = 'pending'\n  AND assigned_to IS NOT NULL\n  AND assigned_until <= NOW()";
-/** Count matching the search WHERE (params $1–$9). */
-export declare const COUNT_SEARCH_ESCALATIONS = "SELECT COUNT(*)::int AS total\n  FROM public.lt_escalations\n  WHERE ($1::text IS NULL OR status = $1)\n    AND ($2::text IS NULL OR role = $2)\n    AND ($3::text[] IS NULL OR role = ANY($3))\n    AND ($4::text IS NULL OR type = $4)\n    AND ($5::text IS NULL OR subtype = $5)\n    AND ($6::int IS NULL OR priority = $6)\n    AND ($7::text IS NULL OR assigned_to = $7)\n    AND ($8::boolean IS NULL OR available = $8)\n    AND ($9::text IS NULL OR (\n          description ILIKE '%' || $9 || '%'\n       OR type ILIKE '%' || $9 || '%'\n       OR subtype ILIKE '%' || $9 || '%'\n       OR role ILIKE '%' || $9 || '%'\n       OR workflow_id ILIKE '%' || $9 || '%'\n       OR origin_id ILIKE '%' || $9 || '%'\n       OR id::text ILIKE '%' || $9 || '%'\n       OR metadata::text ILIKE '%' || $9 || '%'\n    ))";
+/** Count matching the search WHERE (params $1–$12). */
+export declare const COUNT_SEARCH_ESCALATIONS = "SELECT COUNT(*)::int AS total\n  FROM public.lt_escalations\n  WHERE ($1::text IS NULL OR status = $1)\n    AND ($2::text IS NULL OR role = $2)\n    AND (\n         ($3::text[] IS NULL AND $10::text[] IS NULL)\n      OR ($3::text[] IS NOT NULL AND role = ANY($3))\n      OR ($10::text[] IS NOT NULL AND role = ANY($10) AND assigned_to = $11)\n    )\n    AND ($4::text IS NULL OR type = $4)\n    AND ($5::text IS NULL OR subtype = $5)\n    AND ($6::int IS NULL OR priority = $6)\n    AND ($7::text IS NULL OR assigned_to = $7)\n    AND ($8::boolean IS NULL OR available = $8)\n    AND ($12::jsonb IS NULL OR metadata @> $12)\n    AND ($9::text IS NULL OR (\n          description ILIKE '%' || $9 || '%'\n       OR type ILIKE '%' || $9 || '%'\n       OR subtype ILIKE '%' || $9 || '%'\n       OR role ILIKE '%' || $9 || '%'\n       OR workflow_id ILIKE '%' || $9 || '%'\n       OR origin_id ILIKE '%' || $9 || '%'\n       OR id::text ILIKE '%' || $9 || '%'\n       OR metadata::text ILIKE '%' || $9 || '%'\n    ))";
 /**
  * Build the search SELECT. `orderBy` is composed from a whitelist by the caller
  * (never raw user input), so it is safe to interpolate; everything else is bound.
@@ -35,6 +35,12 @@ export declare function searchEscalationsQuery(orderBy: string): string;
  * The `resolved` CTE still skips signal_id rows — the workflow resolves durably.
  *
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
- * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
+ * $4 = metadata patch (jsonb, nullable), $5 = write_all roles (text[], null = global /
+ * no filter), $6 = write_self roles (text[], nullable).
+ *
+ * Write-scope is folded into the same FOR UPDATE statement (no TOCTOU): the row
+ * is resolvable if the caller has global access ($5 NULL), or the row's role is in
+ * their write_all set, or the row's role is in their write_self set AND it is
+ * already assigned to them ($2). assigned_to is indexed, so the self-branch scales.
  */
-export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND target.signal_key IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE public.hmsh_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n    AND (claimed.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.signal_key AS signal_key,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  (target.assigned_to IS NOT NULL\n    AND target.assigned_until IS NOT NULL\n    AND target.assigned_until > NOW()) AS signal_already_claimed,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";
+export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (\n         $5::text[] IS NULL\n      OR role = ANY($5)\n      OR (role = ANY($6::text[]) AND assigned_to = $2)\n    )\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND target.signal_key IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE public.hmsh_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n    AND (claimed.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.signal_key AS signal_key,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  (target.assigned_to IS NOT NULL\n    AND target.assigned_until IS NOT NULL\n    AND target.assigned_until > NOW()) AS signal_already_claimed,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";

package/build/services/escalation/sql.js

@@ -47,20 +47,38 @@ WHERE status = 'pending'
  * `metadata::text ILIKE` scans the JSONB as text (the GIN index is containment-only
  * and cannot serve ILIKE) — bounded in practice by the other filters and the page.
  *
- * $1 status, $2 role, $3 roles (text[] visibleRoles), $4 type, $5 subtype,
- * $6 priority, $7 assigned_to, $8 available (bool), $9 search.
- * The list query adds $10 limit, $11 offset.
+ * Role-scope visibility ($3 allRoles, $10 selfRoles, $11 meUserId):
+ *   - global access  → $3 NULL and $10 NULL → no role filter (sees everything)
+ *   - read_all roles → row.role ∈ $3
+ *   - read_self roles → row.role ∈ $10 AND row.assigned_to = $11 (only the user's own)
+ * The branches union, so a user with mixed scope (read_all on some roles, read_self
+ * on others) is filtered correctly in one pass. `assigned_to` is indexed
+ * (idx_lt_escalations_assigned), so the self-branch is index-served at scale.
+ *
+ * $1 status, $2 role, $3 allRoles (text[]), $4 type, $5 subtype, $6 priority,
+ * $7 assigned_to, $8 available (bool), $9 search, $10 selfRoles (text[]),
+ * $11 meUserId, $12 metadata (jsonb containment, GIN-served). The list query
+ * adds $13 limit, $14 offset.
+ *
+ * `metadata @> $12` is exact JSONB containment (the GIN index serves it) — this is
+ * how findByMetadata routes through the scoped query so its role-scope filter and
+ * count run in SQL (no client-side filtering), the same as free-text/self-scope.
  */
 const SEARCH_ESCALATIONS_WHERE = `\
   FROM public.lt_escalations
   WHERE ($1::text IS NULL OR status = $1)
     AND ($2::text IS NULL OR role = $2)
-    AND ($3::text[] IS NULL OR role = ANY($3))
+    AND (
+         ($3::text[] IS NULL AND $10::text[] IS NULL)
+      OR ($3::text[] IS NOT NULL AND role = ANY($3))
+      OR ($10::text[] IS NOT NULL AND role = ANY($10) AND assigned_to = $11)
+    )
     AND ($4::text IS NULL OR type = $4)
     AND ($5::text IS NULL OR subtype = $5)
     AND ($6::int IS NULL OR priority = $6)
     AND ($7::text IS NULL OR assigned_to = $7)
     AND ($8::boolean IS NULL OR available = $8)
+    AND ($12::jsonb IS NULL OR metadata @> $12)
     AND ($9::text IS NULL OR (
           description ILIKE '%' || $9 || '%'
        OR type ILIKE '%' || $9 || '%'
@@ -71,14 +89,14 @@ const SEARCH_ESCALATIONS_WHERE = `\
        OR id::text ILIKE '%' || $9 || '%'
        OR metadata::text ILIKE '%' || $9 || '%'
     ))`;
-/** Count matching the search WHERE (params $1–$9). */
+/** Count matching the search WHERE (params $1–$12). */
 exports.COUNT_SEARCH_ESCALATIONS = `SELECT COUNT(*)::int AS total\n${SEARCH_ESCALATIONS_WHERE}`;
 /**
  * Build the search SELECT. `orderBy` is composed from a whitelist by the caller
  * (never raw user input), so it is safe to interpolate; everything else is bound.
  */
 function searchEscalationsQuery(orderBy) {
-    return `SELECT *\n${SEARCH_ESCALATIONS_WHERE}\n  ORDER BY ${orderBy}\n  LIMIT $10 OFFSET $11`;
+    return `SELECT *\n${SEARCH_ESCALATIONS_WHERE}\n  ORDER BY ${orderBy}\n  LIMIT $13 OFFSET $14`;
 }
 /**
  * Atomic resolve by metadata with signal guard.
@@ -100,7 +118,13 @@ function searchEscalationsQuery(orderBy) {
  * The `resolved` CTE still skips signal_id rows — the workflow resolves durably.
  *
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
- * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
+ * $4 = metadata patch (jsonb, nullable), $5 = write_all roles (text[], null = global /
+ * no filter), $6 = write_self roles (text[], nullable).
+ *
+ * Write-scope is folded into the same FOR UPDATE statement (no TOCTOU): the row
+ * is resolvable if the caller has global access ($5 NULL), or the row's role is in
+ * their write_all set, or the row's role is in their write_self set AND it is
+ * already assigned to them ($2). assigned_to is indexed, so the self-branch scales.
  */
 exports.RESOLVE_BY_METADATA_ATOMIC = `\
 WITH target AS MATERIALIZED (
@@ -108,7 +132,11 @@ WITH target AS MATERIALIZED (
   FROM public.hmsh_escalations
   WHERE metadata @> $1::jsonb
     AND status = 'pending'
-    AND ($5::text[] IS NULL OR role = ANY($5))
+    AND (
+         $5::text[] IS NULL
+      OR role = ANY($5)
+      OR (role = ANY($6::text[]) AND assigned_to = $2)
+    )
   ORDER BY priority ASC, created_at ASC
   LIMIT 1
   FOR UPDATE

package/build/services/interceptor/activities/escalation.d.ts

@@ -8,6 +8,8 @@
 export declare function ltResolveEscalation(input: {
     escalationId: string;
     resolverPayload: Record<string, any>;
+    /** Outcome patch merged into the row inside the same atomic resolve (see resolveEscalation). */
+    metadata?: Record<string, any>;
 }): Promise<void>;
 /**
  * Claim an escalation to a specific user. Used for auto-assignment

package/build/services/interceptor/activities/escalation.js

@@ -47,7 +47,7 @@ const logger_1 = require("../../../lib/logger");
  * retries this activity.
  */
 async function ltResolveEscalation(input) {
-    const result = await escalationService.resolveEscalation(input.escalationId, input.resolverPayload);
+    const result = await escalationService.resolveEscalation(input.escalationId, input.resolverPayload, input.metadata);
     if (!result) {
         logger_1.loggerRegistry.warn(`[ltResolveEscalation] Escalation ${input.escalationId} already resolved or not found`);
     }

package/build/services/interceptor/lifecycle.js

@@ -53,9 +53,13 @@ async function resolveReRun(activities, envelope, existingTask, wf, taskQueue) {
     const escalationId = envelope?.lt?.escalationId;
     const isRealEscalation = isReRun && escalationId && !escalationId.startsWith('auto-triage-');
     if (isRealEscalation) {
+        // Thread the outcome patch carried on the re-run envelope so it merges into the
+        // prior escalation's metadata inside this SAME atomic resolve — never a separate
+        // write. (resolve orchestrator Path E sets envelope.lt.escalationMetadata.)
         await activities.ltResolveEscalation({
             escalationId: escalationId,
             resolverPayload: envelope.resolver,
+            metadata: envelope.lt?.escalationMetadata,
         });
         // escalation.resolved event published by service layer (services/escalation/crud.ts)
     }