@hotmeshio/long-tail 0.5.12 → 0.6.2

package/build/services/mcp/server-tools.js

@@ -54,14 +54,20 @@ const getAvailableWorkSchema = zod_1.z.object({
     role: zod_1.z.string().describe('Role to filter by'),
     limit: zod_1.z.number().optional().default(10).describe('Max results to return'),
 });
+/** Outcome facets merged onto the row on resolve — see the field describe(). */
+const outcomeMetadata = zod_1.z.record(zod_1.z.any()).optional().describe('Outcome facets to merge into the escalation\'s metadata on resolve — the durable, ' +
+    'queryable record of what happened (disposition, reviewer, timing). Distinct from ' +
+    'payload, which resumes the waiting workflow and is not indexed.');
 const claimAndResolveSchema = zod_1.z.object({
     escalation_id: zod_1.z.string().describe('The escalation ID to claim and resolve'),
     resolver_id: zod_1.z.string().describe('Identifier for who/what is resolving'),
     payload: zod_1.z.record(zod_1.z.any()).describe('Resolution payload data'),
+    metadata: outcomeMetadata,
 });
 const resolveEscalationSchema = zod_1.z.object({
     escalation_id: zod_1.z.string().describe('The escalation ID to resolve'),
     payload: zod_1.z.record(zod_1.z.any()).describe('Resolution payload data'),
+    metadata: outcomeMetadata,
 });
 const escalateAndWaitSchema = zod_1.z.object({
     role: zod_1.z.string().describe('Target role for the escalation (e.g., "reviewer")'),
@@ -176,7 +182,7 @@ function registerHumanQueueTools(server) {
     // ── claim_and_resolve ───────────────────────────────────────────────
     server.registerTool('claim_and_resolve', {
         title: 'Claim and Resolve',
-        description: 'Claim an escalation and immediately resolve it with a payload. Atomic operation.',
+        description: 'Claim an escalation and immediately resolve it with a payload. Atomic operation. Optionally pass `metadata` to record the outcome (disposition, timing) onto the row for the audit trail.',
         inputSchema: claimAndResolveSchema,
     }, async (args) => {
         const claimed = await escalationService.claimEscalation(args.escalation_id, args.resolver_id, 5);
@@ -189,7 +195,7 @@ function registerHumanQueueTools(server) {
                 isError: true,
             };
         }
-        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload);
+        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload, args.metadata);
         if (!resolved) {
             return {
                 content: [{
@@ -213,10 +219,10 @@ function registerHumanQueueTools(server) {
     // ── resolve_escalation ──────────────────────────────────────────────
     server.registerTool('resolve_escalation', {
         title: 'Resolve Escalation',
-        description: 'Resolve an already-claimed escalation with a payload. Use when the claim happened externally (e.g. via API).',
+        description: 'Resolve an already-claimed escalation with a payload. Use when the claim happened externally (e.g. via API). Optionally pass `metadata` to record the outcome (disposition, timing) onto the row for the audit trail.',
         inputSchema: resolveEscalationSchema,
     }, async (args) => {
-        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload);
+        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload, args.metadata);
         if (!resolved) {
             return {
                 content: [{

package/build/services/orchestrator/condition.js

@@ -87,11 +87,15 @@ async function conditionLT(signalId, escalation) {
             taskQueue: LT_ACTIVITY_QUEUE,
             retry: { maximumAttempts: 3 },
         });
-        // Strip $escalation_id before passing as resolver payload
-        const { $escalation_id: _, ...resolverPayload } = raw;
+        // Strip the injected control keys ($escalation_id, $escalation_metadata) before the
+        // payload is returned to the caller. The outcome patch ($escalation_metadata, set by
+        // the resolve orchestrator's signal paths) rides INTO the single atomic resolve below
+        // so it merges in the same guarded UPDATE — never a separate write.
+        const { $escalation_id: _id, $escalation_metadata: metadata, ...resolverPayload } = raw;
         await ltResolveEscalation({
             escalationId,
             resolverPayload: resolverPayload,
+            metadata: metadata,
         });
         return resolverPayload;
     }

package/build/services/role/index.js

@@ -34,9 +34,8 @@ async function getAllEscalationChains() {
  */
 async function addEscalationChain(sourceRole, targetRole) {
     const pool = (0, db_1.getPool)();
-    await pool.query(sql_1.ENSURE_ROLE_EXISTS, [sourceRole]);
-    await pool.query(sql_1.ENSURE_ROLE_EXISTS, [targetRole]);
-    await pool.query(sql_1.INSERT_ESCALATION_CHAIN, [sourceRole, targetRole]);
+    // One atomic statement: ensure both role FK targets + insert the chain link.
+    await pool.query(sql_1.ADD_ESCALATION_CHAIN, [sourceRole, targetRole]);
 }
 /**
  * Remove a single escalation chain entry.

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

@@ -1,6 +1,14 @@
 export declare const GET_ESCALATION_TARGETS = "\n  SELECT target_role\n  FROM lt_config_role_escalations\n  WHERE source_role = $1\n  ORDER BY target_role";
 export declare const GET_ALL_ESCALATION_CHAINS = "\n  SELECT source_role, target_role\n  FROM lt_config_role_escalations\n  ORDER BY source_role, target_role";
 export declare const INSERT_ESCALATION_CHAIN = "\n  INSERT INTO lt_config_role_escalations (source_role, target_role)\n  VALUES ($1, $2)\n  ON CONFLICT DO NOTHING";
+/**
+ * Add an escalation chain in ONE atomic statement: ensure both role FK targets
+ * exist, then insert the source→target link. Postgres checks the chain's FK to
+ * lt_roles at statement end (after the sibling ensure CTEs run), so brand-new
+ * roles are valid targets. Replaces the former ensure+ensure+insert three-call
+ * saga, which had no transaction guarding the writes together.
+ */
+export declare const ADD_ESCALATION_CHAIN = "\n  WITH ensured_source AS (\n    INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING\n  ), ensured_target AS (\n    INSERT INTO lt_roles (role) VALUES ($2) ON CONFLICT DO NOTHING\n  )\n  INSERT INTO lt_config_role_escalations (source_role, target_role)\n  VALUES ($1, $2)\n  ON CONFLICT DO NOTHING";
 export declare const DELETE_ESCALATION_CHAIN = "\n  DELETE FROM lt_config_role_escalations\n  WHERE source_role = $1 AND target_role = $2";
 export declare const DELETE_ESCALATION_CHAINS_BY_SOURCE = "\n  DELETE FROM lt_config_role_escalations\n  WHERE source_role = $1";
 export declare const CHECK_ESCALATION_CHAIN_EXISTS = "\n  SELECT 1\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 AND target_role = $2";

package/build/services/role/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Escalation chain queries ───────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
+exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
 exports.GET_ESCALATION_TARGETS = `
   SELECT target_role
   FROM lt_config_role_escalations
@@ -15,6 +15,22 @@ exports.INSERT_ESCALATION_CHAIN = `
   INSERT INTO lt_config_role_escalations (source_role, target_role)
   VALUES ($1, $2)
   ON CONFLICT DO NOTHING`;
+/**
+ * Add an escalation chain in ONE atomic statement: ensure both role FK targets
+ * exist, then insert the source→target link. Postgres checks the chain's FK to
+ * lt_roles at statement end (after the sibling ensure CTEs run), so brand-new
+ * roles are valid targets. Replaces the former ensure+ensure+insert three-call
+ * saga, which had no transaction guarding the writes together.
+ */
+exports.ADD_ESCALATION_CHAIN = `
+  WITH ensured_source AS (
+    INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING
+  ), ensured_target AS (
+    INSERT INTO lt_roles (role) VALUES ($2) ON CONFLICT DO NOTHING
+  )
+  INSERT INTO lt_config_role_escalations (source_role, target_role)
+  VALUES ($1, $2)
+  ON CONFLICT DO NOTHING`;
 exports.DELETE_ESCALATION_CHAIN = `
   DELETE FROM lt_config_role_escalations
   WHERE source_role = $1 AND target_role = $2`;

package/build/services/task/crud.js

@@ -31,17 +31,25 @@ async function createTask(input) {
         input.executing_as || null,
         input.status || null,
     ]);
-    const task = rows[0];
-    (0, publish_1.publishTaskEvent)({
-        type: 'task.created',
-        source: 'service',
-        workflowId: task.workflow_id || '',
-        workflowName: task.workflow_type || '',
-        taskQueue: task.task_queue || '',
-        taskId: task.id,
-        originId: task.origin_id || undefined,
-        status: task.status || 'pending',
-    });
+    // ON CONFLICT (workflow_id) makes this idempotent: a retried proxyActivity or
+    // re-driven saga re-targets the same row. `_inserted` (xmax = 0) is true only
+    // when this call actually inserted, so the created event fires exactly once.
+    const row = rows[0];
+    const inserted = row._inserted === true;
+    delete row._inserted;
+    const task = row;
+    if (inserted) {
+        (0, publish_1.publishTaskEvent)({
+            type: 'task.created',
+            source: 'service',
+            workflowId: task.workflow_id || '',
+            workflowName: task.workflow_type || '',
+            taskQueue: task.task_queue || '',
+            taskId: task.id,
+            originId: task.origin_id || undefined,
+            status: task.status || 'pending',
+        });
+    }
     return task;
 }
 async function updateTask(id, input) {
@@ -70,7 +78,7 @@ async function updateTask(id, input) {
         values.push(JSON.stringify(input.milestones));
     }
     values.push(id);
-    const { rows } = await pool.query(`UPDATE lt_tasks SET ${sets.join(', ')} WHERE id = $${idx} RETURNING *`, values);
+    const { rows } = await pool.query((0, sql_1.updateTaskById)(sets.join(', '), idx), values);
     const task = rows[0];
     // Publish status-driven events from the single write path
     if (input.status && task) {
@@ -148,8 +156,8 @@ async function listTasks(filters) {
     const limit = filters.limit || 50;
     const offset = filters.offset || 0;
     const [countResult, dataResult] = await Promise.all([
-        pool.query(`SELECT COUNT(*) FROM lt_tasks ${where}`, values),
-        pool.query(`SELECT * FROM lt_tasks ${where} ORDER BY created_at DESC LIMIT $${idx++} OFFSET $${idx++}`, [...values, limit, offset]),
+        pool.query((0, sql_1.listTasksCount)(where), values),
+        pool.query((0, sql_1.listTasksData)(where, idx++, idx++), [...values, limit, offset]),
     ]);
     return {
         tasks: dataResult.rows,

package/build/services/task/process.js

@@ -44,27 +44,9 @@ async function listProcesses(filters) {
         having = `HAVING COUNT(*) > COUNT(*) FILTER (WHERE status = 'completed')
               AND COUNT(*) FILTER (WHERE status = 'needs_intervention') = 0`;
     }
-    // Count query — wrap in subquery because of HAVING
-    const countSql = having
-        ? `SELECT COUNT(*) FROM (
-         SELECT origin_id FROM lt_tasks ${where}
-         GROUP BY origin_id ${having}
-       ) sub`
-        : `SELECT COUNT(DISTINCT origin_id) FROM lt_tasks ${where}`;
-    const dataSql = `SELECT
-       origin_id,
-       COUNT(*)::int AS task_count,
-       COUNT(*) FILTER (WHERE status = 'completed')::int AS completed,
-       COUNT(*) FILTER (WHERE status = 'needs_intervention')::int AS escalated,
-       array_agg(DISTINCT workflow_type) AS workflow_types,
-       MIN(created_at) AS started_at,
-       MAX(COALESCE(completed_at, created_at)) AS last_activity
-     FROM lt_tasks
-     ${where}
-     GROUP BY origin_id
-     ${having}
-     ORDER BY MAX(created_at) DESC
-     LIMIT $${idx++} OFFSET $${idx++}`;
+    // Count wraps the grouped set in a subquery when a status HAVING filter is present.
+    const countSql = (0, sql_1.listProcessesCount)(where, having);
+    const dataSql = (0, sql_1.listProcessesData)(where, having, idx++, idx++);
     const dataParams = [...filterParams, limit, offset];
     const [countResult, dataResult] = await Promise.all([
         pool.query(countSql, filterParams),

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

@@ -1,8 +1,19 @@
-export declare const CREATE_TASK = "\n  INSERT INTO lt_tasks\n    (workflow_id, workflow_type, lt_type, task_queue, signal_id,\n     parent_workflow_id, origin_id, parent_id, envelope, metadata, priority,\n     trace_id, span_id, initiated_by, principal_type, executing_as, status)\n  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, COALESCE($17, 'pending'))\n  RETURNING *";
+export declare const CREATE_TASK = "\n  INSERT INTO lt_tasks\n    (workflow_id, workflow_type, lt_type, task_queue, signal_id,\n     parent_workflow_id, origin_id, parent_id, envelope, metadata, priority,\n     trace_id, span_id, initiated_by, principal_type, executing_as, status)\n  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, COALESCE($17, 'pending'))\n  ON CONFLICT (workflow_id) DO UPDATE SET workflow_id = lt_tasks.workflow_id\n  RETURNING *, (xmax = 0) AS _inserted";
 export declare const APPEND_MILESTONES = "\n  UPDATE lt_tasks\n  SET milestones = milestones || $1::jsonb\n  WHERE id = $2\n  RETURNING *";
 export declare const GET_TASK = "SELECT * FROM lt_tasks WHERE id = $1";
 export declare const GET_TASK_BY_SIGNAL_ID = "SELECT * FROM lt_tasks WHERE signal_id = $1";
 export declare const GET_TASK_BY_WORKFLOW_ID = "SELECT * FROM lt_tasks WHERE workflow_id = $1 ORDER BY created_at DESC LIMIT 1";
+/**
+ * Build the partial-update statement for updateTask. The caller assembles the
+ * `SET` clause from whichever fields are present (each as a `$n` placeholder) and
+ * passes the placeholder index of the trailing `id` bind. One guarded UPDATE by
+ * primary key — no read-then-write.
+ */
+export declare function updateTaskById(setClause: string, idIdx: number): string;
+/** Count query for listTasks. `where` is the caller-built `WHERE …` clause (or ''). */
+export declare function listTasksCount(where: string): string;
+/** Page query for listTasks. limit/offset placeholder indices follow the filter binds. */
+export declare function listTasksData(where: string, limitIdx: number, offsetIdx: number): string;
 export declare const RESOLVE_TASK_BY_WORKFLOW_ID = "SELECT workflow_type, task_queue FROM lt_tasks WHERE workflow_id = $1 ORDER BY created_at DESC LIMIT 1";
 export declare const RESOLVE_CONFIG_TASK_QUEUE = "SELECT task_queue FROM lt_config_workflows WHERE workflow_type = $1";
 /**
@@ -12,6 +23,18 @@ export declare const RESOLVE_CONFIG_TASK_QUEUE = "SELECT task_queue FROM lt_conf
  */
 export declare const RESOLVE_JOB_ENTITY: (appId: string) => string;
 export declare const GET_PROCESS_TASKS = "SELECT * FROM lt_tasks WHERE origin_id = $1 ORDER BY created_at ASC";
+/**
+ * Count query for listProcesses. `where` restricts which origin_ids are in scope;
+ * `having` (empty string when no status filter) aggregates per-origin counts, so the
+ * count must wrap the grouped set in a subquery. Both fragments carry only `$n` binds.
+ */
+export declare function listProcessesCount(where: string, having: string): string;
+/**
+ * Page query for listProcesses — one row per origin_id with rolled-up task counts,
+ * workflow types, and activity window. limit/offset placeholder indices follow the
+ * filter binds.
+ */
+export declare function listProcessesData(where: string, having: string, limitIdx: number, offsetIdx: number): string;
 /**
  * Build the process-stats totals CTE query for a given interval.
  * The interval value MUST come from the VALID_PERIODS whitelist.

package/build/services/task/sql.js

@@ -4,16 +4,29 @@
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GET_PROCESS_TASKS = exports.RESOLVE_JOB_ENTITY = exports.RESOLVE_CONFIG_TASK_QUEUE = exports.RESOLVE_TASK_BY_WORKFLOW_ID = exports.GET_TASK_BY_WORKFLOW_ID = exports.GET_TASK_BY_SIGNAL_ID = exports.GET_TASK = exports.APPEND_MILESTONES = exports.CREATE_TASK = void 0;
+exports.updateTaskById = updateTaskById;
+exports.listTasksCount = listTasksCount;
+exports.listTasksData = listTasksData;
+exports.listProcessesCount = listProcessesCount;
+exports.listProcessesData = listProcessesData;
 exports.processStatsTotals = processStatsTotals;
 exports.processStatsByType = processStatsByType;
 // ---- crud.ts queries ------------------------------------------------------
+// A task is 1:1 with its workflow_id. ON CONFLICT (workflow_id) makes createTask
+// idempotent under proxyActivity retry (maximumAttempts: 3) and re-driven sagas:
+// a retry re-targets the SAME row instead of inserting a duplicate. The no-op
+// DO UPDATE is required so RETURNING yields the existing row on conflict; the
+// `(xmax = 0)` flag tells the caller whether this call actually inserted (so the
+// `task.created` event fires exactly once). Requires the unique index from
+// migration 012.
 exports.CREATE_TASK = `
   INSERT INTO lt_tasks
     (workflow_id, workflow_type, lt_type, task_queue, signal_id,
      parent_workflow_id, origin_id, parent_id, envelope, metadata, priority,
      trace_id, span_id, initiated_by, principal_type, executing_as, status)
   VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, COALESCE($17, 'pending'))
-  RETURNING *`;
+  ON CONFLICT (workflow_id) DO UPDATE SET workflow_id = lt_tasks.workflow_id
+  RETURNING *, (xmax = 0) AS _inserted`;
 exports.APPEND_MILESTONES = `
   UPDATE lt_tasks
   SET milestones = milestones || $1::jsonb
@@ -22,6 +35,23 @@ exports.APPEND_MILESTONES = `
 exports.GET_TASK = `SELECT * FROM lt_tasks WHERE id = $1`;
 exports.GET_TASK_BY_SIGNAL_ID = `SELECT * FROM lt_tasks WHERE signal_id = $1`;
 exports.GET_TASK_BY_WORKFLOW_ID = `SELECT * FROM lt_tasks WHERE workflow_id = $1 ORDER BY created_at DESC LIMIT 1`;
+/**
+ * Build the partial-update statement for updateTask. The caller assembles the
+ * `SET` clause from whichever fields are present (each as a `$n` placeholder) and
+ * passes the placeholder index of the trailing `id` bind. One guarded UPDATE by
+ * primary key — no read-then-write.
+ */
+function updateTaskById(setClause, idIdx) {
+    return `UPDATE lt_tasks SET ${setClause} WHERE id = $${idIdx} RETURNING *`;
+}
+/** Count query for listTasks. `where` is the caller-built `WHERE …` clause (or ''). */
+function listTasksCount(where) {
+    return `SELECT COUNT(*) FROM lt_tasks ${where}`;
+}
+/** Page query for listTasks. limit/offset placeholder indices follow the filter binds. */
+function listTasksData(where, limitIdx, offsetIdx) {
+    return `SELECT * FROM lt_tasks ${where} ORDER BY created_at DESC LIMIT $${limitIdx} OFFSET $${offsetIdx}`;
+}
 // ---- resolve.ts queries ---------------------------------------------------
 exports.RESOLVE_TASK_BY_WORKFLOW_ID = `SELECT workflow_type, task_queue FROM lt_tasks WHERE workflow_id = $1 ORDER BY created_at DESC LIMIT 1`;
 exports.RESOLVE_CONFIG_TASK_QUEUE = `SELECT task_queue FROM lt_config_workflows WHERE workflow_type = $1`;
@@ -34,6 +64,40 @@ const RESOLVE_JOB_ENTITY = (appId) => `SELECT entity FROM "${appId}".jobs WHERE
 exports.RESOLVE_JOB_ENTITY = RESOLVE_JOB_ENTITY;
 // ---- process.ts queries ---------------------------------------------------
 exports.GET_PROCESS_TASKS = `SELECT * FROM lt_tasks WHERE origin_id = $1 ORDER BY created_at ASC`;
+/**
+ * Count query for listProcesses. `where` restricts which origin_ids are in scope;
+ * `having` (empty string when no status filter) aggregates per-origin counts, so the
+ * count must wrap the grouped set in a subquery. Both fragments carry only `$n` binds.
+ */
+function listProcessesCount(where, having) {
+    return having
+        ? `SELECT COUNT(*) FROM (
+         SELECT origin_id FROM lt_tasks ${where}
+         GROUP BY origin_id ${having}
+       ) sub`
+        : `SELECT COUNT(DISTINCT origin_id) FROM lt_tasks ${where}`;
+}
+/**
+ * Page query for listProcesses — one row per origin_id with rolled-up task counts,
+ * workflow types, and activity window. limit/offset placeholder indices follow the
+ * filter binds.
+ */
+function listProcessesData(where, having, limitIdx, offsetIdx) {
+    return `SELECT
+       origin_id,
+       COUNT(*)::int AS task_count,
+       COUNT(*) FILTER (WHERE status = 'completed')::int AS completed,
+       COUNT(*) FILTER (WHERE status = 'needs_intervention')::int AS escalated,
+       array_agg(DISTINCT workflow_type) AS workflow_types,
+       MIN(created_at) AS started_at,
+       MAX(COALESCE(completed_at, created_at)) AS last_activity
+     FROM lt_tasks
+     ${where}
+     GROUP BY origin_id
+     ${having}
+     ORDER BY MAX(created_at) DESC
+     LIMIT $${limitIdx} OFFSET $${offsetIdx}`;
+}
 /**
  * Build the process-stats totals CTE query for a given interval.
  * The interval value MUST come from the VALID_PERIODS whitelist.

package/build/services/user/crud.d.ts

@@ -11,6 +11,7 @@ export declare function listUsers(filters: {
     role?: string;
     roleType?: LTRoleType;
     status?: LTUserStatus;
+    search?: string;
     limit?: number;
     offset?: number;
 }): Promise<{

package/build/services/user/crud.js

@@ -14,6 +14,7 @@ exports.listUsers = listUsers;
 const bcryptjs_1 = __importDefault(require("bcryptjs"));
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
+const scope_1 = require("./scope");
 // ─── Private helpers (exported for internal use by auth.ts) ──────────────────
 async function attachRoles(user) {
     const pool = (0, db_1.getPool)();
@@ -29,7 +30,13 @@ async function attachRolesToMany(users) {
     const roleMap = new Map();
     for (const row of rows) {
         const list = roleMap.get(row.user_id) || [];
-        list.push({ role: row.role, type: row.type, created_at: row.created_at });
+        list.push({
+            role: row.role,
+            type: row.type,
+            read_scope: row.read_scope,
+            write_scope: row.write_scope,
+            created_at: row.created_at,
+        });
         roleMap.set(row.user_id, list);
     }
     return users.map((u) => ({ ...u, roles: roleMap.get(u.id) || [] }));
@@ -40,7 +47,16 @@ async function createUser(input) {
     const passwordHash = input.password
         ? await bcryptjs_1.default.hash(input.password, 10)
         : null;
-    const { rows } = await pool.query(sql_1.INSERT_USER, [
+    // One atomic statement creates the user, ensures the role FK targets, and links
+    // the assignments — no partial-roles window, no per-role N+1. Roles + their
+    // effective scope travel as parallel text[] arrays. admin/superadmin normalize
+    // to ('all','all'); members store the requested scope.
+    const roleNames = (input.roles || []).map((r) => r.role);
+    const roleTypes = (input.roles || []).map((r) => r.type);
+    const effScopes = (input.roles || []).map((r) => (0, scope_1.effectiveScope)(r.type, r.read_scope ?? scope_1.DEFAULT_READ_SCOPE, r.write_scope ?? scope_1.DEFAULT_WRITE_SCOPE));
+    const roleReadScopes = effScopes.map((e) => e.read);
+    const roleWriteScopes = effScopes.map((e) => e.write);
+    const { rows } = await pool.query(sql_1.CREATE_USER_WITH_ROLES, [
         input.external_id,
         input.email || null,
         input.display_name || null,
@@ -49,16 +65,12 @@ async function createUser(input) {
         passwordHash,
         input.oauth_provider || null,
         input.oauth_provider_id || null,
+        roleNames,
+        roleTypes,
+        roleReadScopes,
+        roleWriteScopes,
     ]);
-    const user = rows[0];
-    if (input.roles && input.roles.length > 0) {
-        for (const r of input.roles) {
-            // Ensure the role exists in lt_roles (FK constraint)
-            await pool.query(sql_1.ENSURE_ROLE_EXISTS, [r.role]);
-            await pool.query(sql_1.INSERT_USER_ROLE_IGNORE, [user.id, r.role, r.type]);
-        }
-    }
-    return attachRoles(user);
+    return attachRoles(rows[0]);
 }
 async function getUser(id) {
     const pool = (0, db_1.getPool)();
@@ -140,6 +152,12 @@ async function listUsers(filters) {
         conditions.push(`u.status = $${idx++}`);
         values.push(filters.status);
     }
+    if (filters.search) {
+        // Server-side free-text over the user's display fields — one term, one param.
+        const i = idx++;
+        conditions.push(`(u.display_name ILIKE '%' || $${i} || '%' OR u.email ILIKE '%' || $${i} || '%' OR u.external_id ILIKE '%' || $${i} || '%')`);
+        values.push(filters.search);
+    }
     const join = needsJoin ? 'INNER JOIN lt_user_roles r ON r.user_id = u.id' : '';
     const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
     const limit = filters.limit || 50;

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

@@ -1,6 +1,7 @@
 export { CreateUserInput, UpdateUserInput, VALID_ROLE_TYPES } from './types';
 export { createUser, getUser, getUserByExternalId, getUserByEmail, updateUser, deleteUser, listUsers, } from './crud';
 export { isValidRoleType, addUserRole, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
-export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin } from './rbac';
+export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin, getRoleScope, getRoleWriteScope } from './rbac';
+export { READ_SCOPES, WRITE_SCOPES, DEFAULT_READ_SCOPE, DEFAULT_WRITE_SCOPE, isValidReadScope, isValidWriteScope, isValidScopePair, effectiveScope, } from './scope';
 export { verifyPassword } from './auth';
 export { seedAdmin } from './seed-admin';

package/build/services/user/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.seedAdmin = exports.verifyPassword = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
+exports.seedAdmin = exports.verifyPassword = exports.effectiveScope = exports.isValidScopePair = exports.isValidWriteScope = exports.isValidReadScope = exports.DEFAULT_WRITE_SCOPE = exports.DEFAULT_READ_SCOPE = exports.WRITE_SCOPES = exports.READ_SCOPES = exports.getRoleWriteScope = exports.getRoleScope = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "VALID_ROLE_TYPES", { enumerable: true, get: function () { return types_1.VALID_ROLE_TYPES; } });
 var crud_1 = require("./crud");
@@ -24,6 +24,17 @@ Object.defineProperty(exports, "isGroupAdmin", { enumerable: true, get: function
 Object.defineProperty(exports, "canManageRole", { enumerable: true, get: function () { return rbac_1.canManageRole; } });
 Object.defineProperty(exports, "hasGlobalEscalationAccess", { enumerable: true, get: function () { return rbac_1.hasGlobalEscalationAccess; } });
 Object.defineProperty(exports, "hasRolesAsAdmin", { enumerable: true, get: function () { return rbac_1.hasRolesAsAdmin; } });
+Object.defineProperty(exports, "getRoleScope", { enumerable: true, get: function () { return rbac_1.getRoleScope; } });
+Object.defineProperty(exports, "getRoleWriteScope", { enumerable: true, get: function () { return rbac_1.getRoleWriteScope; } });
+var scope_1 = require("./scope");
+Object.defineProperty(exports, "READ_SCOPES", { enumerable: true, get: function () { return scope_1.READ_SCOPES; } });
+Object.defineProperty(exports, "WRITE_SCOPES", { enumerable: true, get: function () { return scope_1.WRITE_SCOPES; } });
+Object.defineProperty(exports, "DEFAULT_READ_SCOPE", { enumerable: true, get: function () { return scope_1.DEFAULT_READ_SCOPE; } });
+Object.defineProperty(exports, "DEFAULT_WRITE_SCOPE", { enumerable: true, get: function () { return scope_1.DEFAULT_WRITE_SCOPE; } });
+Object.defineProperty(exports, "isValidReadScope", { enumerable: true, get: function () { return scope_1.isValidReadScope; } });
+Object.defineProperty(exports, "isValidWriteScope", { enumerable: true, get: function () { return scope_1.isValidWriteScope; } });
+Object.defineProperty(exports, "isValidScopePair", { enumerable: true, get: function () { return scope_1.isValidScopePair; } });
+Object.defineProperty(exports, "effectiveScope", { enumerable: true, get: function () { return scope_1.effectiveScope; } });
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "verifyPassword", { enumerable: true, get: function () { return auth_1.verifyPassword; } });
 var seed_admin_1 = require("./seed-admin");

package/build/services/user/rbac.d.ts

@@ -1,3 +1,4 @@
+import type { LTReadScope, LTWriteScope } from '../../types';
 /**
  * Is the user a superadmin? (global — can manage all users and roles)
  */
@@ -24,6 +25,23 @@ export declare function canManageRole(actorId: string, role: string): Promise<bo
  * all roles, and can perform bulk actions.
  */
 export declare function hasGlobalEscalationAccess(userId: string): Promise<boolean>;
+/**
+ * Resolve the user's effective scope for a single role — the breadth at which
+ * they may SEARCH (read) and ACT (write). One indexed PK lookup on lt_user_roles.
+ * Returns `null` when the user is not a member of the role.
+ *
+ * The management tier (admin/superadmin) short-circuits both axes to `'all'` via
+ * effectiveScope. Callers that already hold global access should skip this.
+ */
+export declare function getRoleScope(userId: string, role: string): Promise<{
+    read: LTReadScope;
+    write: LTWriteScope;
+} | null>;
+/**
+ * Effective WRITE scope for a role: `'all'` (act on any item), `'self'` (only
+ * items assigned to the user), or `'none'` (read-only, or not a member).
+ */
+export declare function getRoleWriteScope(userId: string, role: string): Promise<LTWriteScope>;
 /**
  * Batch check: does the user have admin type for ALL specified roles?
  * Single query — replaces the N+1 loop in checkBulkPermission.

package/build/services/user/rbac.js

@@ -4,9 +4,12 @@ exports.isSuperAdmin = isSuperAdmin;
 exports.isGroupAdmin = isGroupAdmin;
 exports.canManageRole = canManageRole;
 exports.hasGlobalEscalationAccess = hasGlobalEscalationAccess;
+exports.getRoleScope = getRoleScope;
+exports.getRoleWriteScope = getRoleWriteScope;
 exports.hasRolesAsAdmin = hasRolesAsAdmin;
 const db_1 = require("../../lib/db");
 const roles_1 = require("./roles");
+const scope_1 = require("./scope");
 const sql_1 = require("./sql");
 // ─── RBAC helpers ─────────────────────────────────────────────────────────────
 /**
@@ -48,6 +51,30 @@ async function hasGlobalEscalationAccess(userId) {
     const roles = await (0, roles_1.getUserRoles)(userId);
     return roles.some((r) => r.role === 'admin' && r.type === 'admin');
 }
+/**
+ * Resolve the user's effective scope for a single role — the breadth at which
+ * they may SEARCH (read) and ACT (write). One indexed PK lookup on lt_user_roles.
+ * Returns `null` when the user is not a member of the role.
+ *
+ * The management tier (admin/superadmin) short-circuits both axes to `'all'` via
+ * effectiveScope. Callers that already hold global access should skip this.
+ */
+async function getRoleScope(userId, role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLE_SCOPE, [userId, role]);
+    if (rows.length === 0)
+        return null;
+    const { type, read_scope, write_scope } = rows[0];
+    return (0, scope_1.effectiveScope)(type, read_scope, write_scope);
+}
+/**
+ * Effective WRITE scope for a role: `'all'` (act on any item), `'self'` (only
+ * items assigned to the user), or `'none'` (read-only, or not a member).
+ */
+async function getRoleWriteScope(userId, role) {
+    const scope = await getRoleScope(userId, role);
+    return scope ? scope.write : 'none';
+}
 /**
  * Batch check: does the user have admin type for ALL specified roles?
  * Single query — replaces the N+1 loop in checkBulkPermission.

package/build/services/user/roles.d.ts

@@ -1,6 +1,11 @@
-import type { LTUserRole, LTRoleType } from '../../types';
+import type { LTReadScope, LTRoleType, LTUserRole, LTWriteScope } from '../../types';
 export declare function isValidRoleType(type: string): type is LTRoleType;
-export declare function addUserRole(userId: string, role: string, type: LTRoleType): Promise<LTUserRole>;
+/** Optional work-surface scope for a membership. Defaults to ('all','all') = full worker. */
+export interface RoleScopeInput {
+    read_scope?: LTReadScope;
+    write_scope?: LTWriteScope;
+}
+export declare function addUserRole(userId: string, role: string, type: LTRoleType, scope?: RoleScopeInput): Promise<LTUserRole>;
 export declare function removeUserRole(userId: string, role: string): Promise<boolean>;
 export declare function getUserRoles(userId: string): Promise<LTUserRole[]>;
 export declare function hasRole(userId: string, role: string): Promise<boolean>;

package/build/services/user/roles.js

@@ -8,17 +8,33 @@ exports.hasRole = hasRole;
 exports.hasRoleType = hasRoleType;
 const db_1 = require("../../lib/db");
 const sql_1 = require("./sql");
+const scope_1 = require("./scope");
 const types_1 = require("./types");
 // ─── Role management ──────────────────────────────────────────────────────────
 function isValidRoleType(type) {
     return types_1.VALID_ROLE_TYPES.includes(type);
 }
-async function addUserRole(userId, role, type) {
+async function addUserRole(userId, role, type, scope) {
+    // admin/superadmin always store ('all','all'); members store the requested scope.
+    const eff = (0, scope_1.effectiveScope)(type, scope?.read_scope ?? scope_1.DEFAULT_READ_SCOPE, scope?.write_scope ?? scope_1.DEFAULT_WRITE_SCOPE);
     const pool = (0, db_1.getPool)();
-    // Ensure the role exists in lt_roles (FK constraint)
-    await pool.query(sql_1.ENSURE_ROLE_EXISTS, [role]);
-    const { rows } = await pool.query(sql_1.UPSERT_USER_ROLE, [userId, role, type]);
-    return rows[0];
+    // Ensure-role (FK target) and the scoped user-role upsert commit together so a
+    // failure between them cannot leave the FK target without its assignment.
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query(sql_1.ENSURE_ROLE_EXISTS, [role]);
+        const { rows } = await client.query(sql_1.UPSERT_USER_ROLE, [userId, role, type, eff.read, eff.write]);
+        await client.query('COMMIT');
+        return rows[0];
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        client.release();
+    }
 }
 async function removeUserRole(userId, role) {
     const pool = (0, db_1.getPool)();

package/build/services/user/scope.d.ts

@@ -0,0 +1,22 @@
+import type { LTReadScope, LTRoleType, LTWriteScope } from '../../types';
+export declare const READ_SCOPES: LTReadScope[];
+export declare const WRITE_SCOPES: LTWriteScope[];
+/** Defaults preserve legacy `member` behavior (full role worker). */
+export declare const DEFAULT_READ_SCOPE: LTReadScope;
+export declare const DEFAULT_WRITE_SCOPE: LTWriteScope;
+export declare function isValidReadScope(scope: string): scope is LTReadScope;
+export declare function isValidWriteScope(scope: string): scope is LTWriteScope;
+/**
+ * Is (read, write) a valid point in the lattice? Enforces write ⊆ read:
+ * write='all' requires read='all'. (write='self'/'none' allowed under read='self'.)
+ */
+export declare function isValidScopePair(read: LTReadScope, write: LTWriteScope): boolean;
+/**
+ * Resolve the scope a membership actually grants. The management tier
+ * (admin/superadmin) short-circuits both axes to `all` — those users always
+ * search and act on the whole role queue regardless of stored scope columns.
+ */
+export declare function effectiveScope(type: LTRoleType, read: LTReadScope, write: LTWriteScope): {
+    read: LTReadScope;
+    write: LTWriteScope;
+};