@hotmeshio/long-tail 0.8.4 → 0.9.0

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

@@ -3,7 +3,7 @@ export { listEscalations, listAvailableEscalations, listDistinctTypes, listFacet
 export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './single';
 export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkEscalate, bulkTriage } from './bulk';
-export { resolveEscalation, resolveBySignalKey, resolveByIds } from './resolve';
+export { resolveEscalation, resolveBySignalKey, resolveByIds, resolveAllOrNone } from './resolve';
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';
 export { cancelSingleEscalation, bulkCancel } from './cancel';
 export { searchByFacets, claimGroups, claimByFacets } from './facets';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.claimByFacets = exports.claimGroups = exports.searchByFacets = exports.bulkCancel = exports.cancelSingleEscalation = exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveAllOrNone = exports.resolveByIds = exports.resolveBySignalKey = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getStationMetrics = exports.getEscalationStats = exports.listFacetKeys = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -28,6 +28,7 @@ var resolve_1 = require("./resolve");
 Object.defineProperty(exports, "resolveEscalation", { enumerable: true, get: function () { return resolve_1.resolveEscalation; } });
 Object.defineProperty(exports, "resolveBySignalKey", { enumerable: true, get: function () { return resolve_1.resolveBySignalKey; } });
 Object.defineProperty(exports, "resolveByIds", { enumerable: true, get: function () { return resolve_1.resolveByIds; } });
+Object.defineProperty(exports, "resolveAllOrNone", { enumerable: true, get: function () { return resolve_1.resolveAllOrNone; } });
 var metadata_1 = require("./metadata");
 Object.defineProperty(exports, "findByMetadata", { enumerable: true, get: function () { return metadata_1.findByMetadata; } });
 Object.defineProperty(exports, "claimByMetadata", { enumerable: true, get: function () { return metadata_1.claimByMetadata; } });

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

@@ -44,3 +44,31 @@ export declare function resolveByIds(input: {
     resolverPayload: Record<string, any>;
     metadata?: Record<string, any>;
 }, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Atomic all-or-none bulk resolve with PER-ROW payloads — the gang-handoff
+ * sibling of {@link resolveByIds}. Every listed escalation must be pending and
+ * writable by the caller, or NOTHING resolves. Unlike resolveByIds, rows
+ * backing a live `condition()` waiter are first-class: each is woken with its
+ * own payload inside the single atomic statement (same wake contract as
+ * single resolve).
+ *
+ * RBAC matches resolveByIds: per-item write scope, 404 non-disclosure when any
+ * id is missing or out of scope, nothing resolved. `requireClaimed` adds a
+ * SQL-level assertion that every row is currently assigned to the caller —
+ * for claim-then-resolve flows (a broker resolving its claimed gang), this
+ * closes the window where another principal re-claims a member mid-flight.
+ *
+ * Rows whose resolution requires a non-atomic path (legacy signal routing via
+ * `metadata.signal_id` / `metadata.signal_routing`, which need a separate
+ * workflow signal) block the batch with 409 — bulk-resolving them would strand
+ * their workflows. Re-run/triage rows (workflow_type without any signal shape)
+ * resolve as bookkeeping acknowledgements, matching resolveByIds semantics.
+ */
+export declare function resolveAllOrNone(input: {
+    items: Array<{
+        id: string;
+        resolverPayload: Record<string, any>;
+    }>;
+    metadata?: Record<string, any>;
+    requireClaimed?: boolean;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/resolve.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveEscalation = resolveEscalation;
 exports.resolveBySignalKey = resolveBySignalKey;
 exports.resolveByIds = resolveByIds;
+exports.resolveAllOrNone = resolveAllOrNone;
 const escalationService = __importStar(require("../../services/escalation"));
 const taskService = __importStar(require("../../services/task"));
 const escalation_strategy_1 = require("../../services/escalation-strategy");
@@ -202,6 +203,103 @@ async function resolveByIds(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Atomic all-or-none bulk resolve with PER-ROW payloads — the gang-handoff
+ * sibling of {@link resolveByIds}. Every listed escalation must be pending and
+ * writable by the caller, or NOTHING resolves. Unlike resolveByIds, rows
+ * backing a live `condition()` waiter are first-class: each is woken with its
+ * own payload inside the single atomic statement (same wake contract as
+ * single resolve).
+ *
+ * RBAC matches resolveByIds: per-item write scope, 404 non-disclosure when any
+ * id is missing or out of scope, nothing resolved. `requireClaimed` adds a
+ * SQL-level assertion that every row is currently assigned to the caller —
+ * for claim-then-resolve flows (a broker resolving its claimed gang), this
+ * closes the window where another principal re-claims a member mid-flight.
+ *
+ * Rows whose resolution requires a non-atomic path (legacy signal routing via
+ * `metadata.signal_id` / `metadata.signal_routing`, which need a separate
+ * workflow signal) block the batch with 409 — bulk-resolving them would strand
+ * their workflows. Re-run/triage rows (workflow_type without any signal shape)
+ * resolve as bookkeeping acknowledgements, matching resolveByIds semantics.
+ */
+async function resolveAllOrNone(input, auth) {
+    try {
+        const { items, metadata, requireClaimed } = input;
+        if (!Array.isArray(items) || items.length === 0) {
+            return { status: 400, error: 'items must be a non-empty array' };
+        }
+        if (items.length > defaults_1.ESCALATION_BULK_RESOLVE_MAX) {
+            return { status: 400, error: `items exceeds the maximum of ${defaults_1.ESCALATION_BULK_RESOLVE_MAX}` };
+        }
+        const wellFormed = items.every((i) => i && typeof i.id === 'string' && i.id.length > 0
+            && i.resolverPayload && typeof i.resolverPayload === 'object');
+        if (!wellFormed) {
+            return { status: 400, error: 'every item requires an id and a resolverPayload object' };
+        }
+        const ids = items.map((i) => i.id);
+        if (new Set(ids).size !== ids.length) {
+            return { status: 400, error: 'items must not repeat ids' };
+        }
+        // One indexed read serves every pre-flight gate below (scope, path shape,
+        // redaction schema). Role and signal routing are immutable per escalation,
+        // so none of these checks race the guarded statement that follows — and
+        // row STATE (pending, assignee) is re-asserted inside that statement.
+        const rows = await escalationService.getEscalationsByIds(ids);
+        const rowById = new Map(rows.map((r) => [r.id, r]));
+        // Per-item write scope, same rule as resolveByIds: write_all roles may
+        // resolve any item in the role; write_self only items assigned to the
+        // caller. A missing id or any out-of-scope item → 404 (non-disclosure),
+        // nothing resolved. Global bypasses; the store then reports precise
+        // per-row blockers (including not-found) via the 409 below.
+        const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
+        if (!writeScope.global) {
+            const allSet = new Set(writeScope.allRoles);
+            const selfSet = new Set(writeScope.selfRoles);
+            const writable = (r) => (!!r.role && allSet.has(r.role)) ||
+                (!!r.role && selfSet.has(r.role) && r.assigned_to === auth.userId);
+            if (rows.length !== ids.length || !rows.every(writable)) {
+                return { status: 404, error: 'One or more escalations not found' };
+            }
+        }
+        // Fail loud on rows the atomic statement cannot wake: legacy signal shapes
+        // resume their workflow via a separate handle.signal, so bulk-resolving the
+        // row would mark it settled while the workflow stays parked forever.
+        const unsupported = rows.filter((r) => {
+            const meta = (r.metadata ?? {});
+            return !r.signal_key && (meta.signal_id || meta.signal_routing?.signalId);
+        });
+        if (unsupported.length > 0) {
+            const failed = unsupported.map((r) => ({ id: r.id, reason: 'unsupported-resolution-path' }));
+            // error rides inside data too: routes serialize `data ?? { error }`, and
+            // the 409 body must carry BOTH the message and the blocking ids
+            const error = 'One or more escalations require the single-resolve path (legacy signal routing)';
+            return { status: 409, error, data: { error, failedIds: failed.map((f) => f.id), failed } };
+        }
+        // Per-row password redaction against each row's own form schema — the
+        // payload enters the signal store and the audit record; plaintext never.
+        const serviceItems = await Promise.all(items.map(async (item) => ({
+            id: item.id,
+            resolverPayload: await redactPasswords(item.resolverPayload, rowById.get(item.id)?.metadata?.form_schema),
+        })));
+        const result = await escalationService.resolveEscalationsAllOrNone(serviceItems, metadata, requireClaimed ? auth.userId : undefined);
+        if (!result.ok) {
+            const error = 'One or more escalations blocked the batch; nothing was resolved';
+            return {
+                status: 409,
+                error,
+                data: { error, failedIds: result.failed.map((f) => f.id), failed: result.failed },
+            };
+        }
+        return {
+            status: 200,
+            data: { resolved: result.escalations.length, escalationIds: result.escalations.map((e) => e.id) },
+        };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 // ── Resolution paths ─────────────────────────────────────────────────────
 /** Path A: lightweight conditionLT signal — inject $escalation_id and signal the running workflow. */
 async function resolveViaConditionSignal(escalation, resolverPayload, metadata) {

package/build/api/roles.d.ts

@@ -86,6 +86,8 @@ export declare function updateRole(input: {
     /** The escalation resolve FORM schema (the JIT UI). Fields may carry x-lt-bind. */
     form_schema?: Record<string, any> | null;
     metadata_schema?: Record<string, any> | null;
+    /** The escalation LIST schema — rich formatting for this role's list page. */
+    list_schema?: Record<string, any> | null;
     properties?: Record<string, any> | null;
     ops_visible?: boolean;
     parent_role?: string | null;
@@ -129,6 +131,25 @@ export declare function getRoleSchema(input: {
 export declare function listRoleSchemaVersions(input: {
     role: string;
 }): Promise<LTApiResult>;
+/**
+ * Fetch a role's LIST schema (independent version lineage from the form schema).
+ * With `version`, returns that immutable snapshot — a missing version is a 404.
+ * Without `version`, returns the live (latest) list schema with its version.
+ *
+ * @returns `{ status: 200, data: RoleListSchemaVersion }` on success
+ */
+export declare function getRoleListSchema(input: {
+    role: string;
+    version?: number;
+}): Promise<LTApiResult>;
+/**
+ * List a role's LIST schema version history, newest first.
+ *
+ * @returns `{ status: 200, data: { versions: RoleListSchemaVersionSummary[] } }`
+ */
+export declare function listRoleListSchemaVersions(input: {
+    role: string;
+}): Promise<LTApiResult>;
 /**
  * Delete a role from the system. Requires admin privileges.
  *

package/build/api/roles.js

@@ -44,6 +44,8 @@ exports.replaceEscalationTargets = replaceEscalationTargets;
 exports.updateRole = updateRole;
 exports.getRoleSchema = getRoleSchema;
 exports.listRoleSchemaVersions = listRoleSchemaVersions;
+exports.getRoleListSchema = getRoleListSchema;
+exports.listRoleListSchemaVersions = listRoleListSchemaVersions;
 exports.deleteRole = deleteRole;
 const roleService = __importStar(require("../services/role"));
 const facet_sql_1 = require("../services/escalation/facet-sql");
@@ -244,6 +246,7 @@ async function updateRole(input) {
             description: input.description,
             form_schema: input.form_schema,
             metadata_schema: input.metadata_schema,
+            list_schema: input.list_schema,
             properties: input.properties,
             ops_visible: input.ops_visible,
             parent_role: input.parent_role,
@@ -320,6 +323,53 @@ async function listRoleSchemaVersions(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Fetch a role's LIST schema (independent version lineage from the form schema).
+ * With `version`, returns that immutable snapshot — a missing version is a 404.
+ * Without `version`, returns the live (latest) list schema with its version.
+ *
+ * @returns `{ status: 200, data: RoleListSchemaVersion }` on success
+ */
+async function getRoleListSchema(input) {
+    try {
+        if (!input.role) {
+            return { status: 400, error: 'role is required' };
+        }
+        if (input.version !== undefined && (!Number.isInteger(input.version) || input.version < 1)) {
+            return { status: 400, error: 'version must be a positive integer' };
+        }
+        const schema = await roleService.getRoleListSchema(input.role, input.version);
+        if (!schema) {
+            return {
+                status: 404,
+                error: input.version !== undefined
+                    ? `List schema version ${input.version} not found for role '${input.role}'`
+                    : `Role '${input.role}' not found`,
+            };
+        }
+        return { status: 200, data: schema };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * List a role's LIST schema version history, newest first.
+ *
+ * @returns `{ status: 200, data: { versions: RoleListSchemaVersionSummary[] } }`
+ */
+async function listRoleListSchemaVersions(input) {
+    try {
+        if (!input.role) {
+            return { status: 400, error: 'role is required' };
+        }
+        const versions = await roleService.listRoleListSchemaVersions(input.role);
+        return { status: 200, data: { versions } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 /**
  * Delete a role from the system. Requires admin privileges.
  *

package/build/lib/db/index.js

@@ -8,7 +8,18 @@ const config_1 = require("../../modules/config");
 let pool = null;
 function getPool() {
     if (!pool) {
-        pool = new pg_1.Pool(config_1.postgres_options);
+        pool = new pg_1.Pool({
+            ...config_1.postgres_options,
+            // Long-tail's shared tables live in public. Postgres's default
+            // search_path is `"$user", public`: if any schema shares the connecting
+            // role's name (e.g. a HotMesh app schema named after the DB user), every
+            // unqualified statement — including CREATE TABLE in migrations — silently
+            // resolves there instead of public, forking the data across two schemas.
+            // Pinning the session search_path makes resolution independent of role
+            // and schema naming. HotMesh connections (getConnection) are unaffected:
+            // the engine fully qualifies its app schemas.
+            options: '-c search_path=public',
+        });
     }
     return pool;
 }

package/build/lib/db/migrate.js

@@ -47,7 +47,34 @@ async function migrate() {
     // Uses a dedicated client so the lock is held for the entire sequence.
     const client = await pool.connect();
     try {
+        // Migrations define the shared public tables, so resolution is pinned on
+        // this client even if a future caller wires a pool without the pool-level
+        // search_path option. Without this, a schema named after the DB role
+        // (default search_path `"$user", public`) captures every unqualified
+        // CREATE TABLE below.
+        await client.query('SET search_path TO public');
         await client.query('SELECT pg_advisory_lock(8675309)');
+        // Fail loudly on a pre-existing split: an lt_migrations table in any other
+        // schema means a prior boot ran with `"$user"` shadowing public and forked
+        // the tables. Booting through it would either fork the data further or
+        // re-run every migration against empty public tables while the live rows
+        // sit in the shadow schema. An operator must consolidate first (move the
+        // live lt_* tables to public, archive the stale copies).
+        const drift = await client.query(`
+      SELECT n.nspname
+      FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relname = 'lt_migrations' AND c.relkind = 'r' AND n.nspname <> 'public'
+    `);
+        if (drift.rows.length > 0) {
+            const schemas = drift.rows.map((r) => r.nspname).join(', ');
+            throw new Error(`[migrate] lt_migrations exists in non-public schema(s): ${schemas}. ` +
+                'Long-tail tables must live in the public schema. This usually means the ' +
+                'database user shares a name with another schema, so the default ' +
+                'search_path ("$user", public) captured earlier migrations. Consolidate ' +
+                'the schemas (ALTER TABLE ... SET SCHEMA public for the live lt_* tables, ' +
+                'archive stale public copies) before starting the app.');
+        }
         // ensure migration tracking table
         await client.query(`
       CREATE TABLE IF NOT EXISTS lt_migrations (

package/build/lib/db/schemas/021_role_list_schema.sql

@@ -0,0 +1,27 @@
+-- Migration 021: Role escalations LIST schema
+--
+-- list_schema is the list-page analog of form_schema: it richly formats the
+-- escalation LIST page when the list is scoped to exactly one role that owns a
+-- list_schema (opt-in — absent leaves the engineer table unchanged). Unlike
+-- form_schema it is NOT pinned per-escalation; the list always renders the
+-- role's latest.
+--
+-- It versions INDEPENDENTLY of form_schema / metadata_schema: its own snapshot
+-- table (lt_role_list_schemas) and its own counter (current_list_schema_version),
+-- so editing the list view never advances the resolve form's version. The write
+-- rides the same atomic UPDATE_ROLE_METADATA statement (services/role/sql.ts),
+-- which bumps current_list_schema_version and appends a snapshot only when the
+-- provided list_schema actually differs.
+
+ALTER TABLE lt_roles
+  ADD COLUMN IF NOT EXISTS list_schema JSONB,
+  ADD COLUMN IF NOT EXISTS current_list_schema_version INTEGER;
+
+CREATE TABLE IF NOT EXISTS lt_role_list_schemas (
+  role           TEXT NOT NULL REFERENCES lt_roles(role) ON DELETE CASCADE,
+  version        INTEGER NOT NULL,
+  list_schema    JSONB,
+  change_summary TEXT,
+  created_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (role, version)
+);

package/build/modules/defaults.d.ts

@@ -49,6 +49,8 @@ export declare const QUERY_LIMIT_MAX: number;
 export declare const YAML_LIST_LIMIT: number;
 /** Default page size for YAML workflow version history. */
 export declare const YAML_VERSION_LIMIT: number;
+/** Maximum items per atomic bulk resolve (POST /escalations/resolve-all-or-none). */
+export declare const ESCALATION_BULK_RESOLVE_MAX: number;
 /**
  * Claim duration presets shown in the dashboard (minutes).
  * Override via JSON array, e.g. LT_CLAIM_DURATION_OPTIONS='[15,30,60,480]'

package/build/modules/defaults.js

@@ -9,7 +9,7 @@
  * Grouped by domain so related knobs live together.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.YAML_LINE_WIDTH = exports.STOP_WORDS = exports.CLAIM_DURATION_OPTIONS = exports.YAML_VERSION_LIMIT = exports.YAML_LIST_LIMIT = exports.QUERY_LIMIT_MAX = exports.QUERY_LIMIT_DEFAULT = exports.CONFIG_CACHE_TTL_MS = exports.MCP_TOOL_TIMEOUT_MS = exports.WORKFLOW_SYNC_TIMEOUT_MS = exports.JOB_EXPIRE_SECS = exports.WORKFLOW_EXPIRE_SECS = exports.TOOL_ARG_LIMIT_CAP = exports.TOOL_ROUNDS_MCP_QUERY = exports.TOOL_ROUNDS_TRIAGE = exports.TOOL_RESULT_MAX_CHARS = exports.LLM_MAX_INPUT_CHARS = exports.LLM_MAX_ARRAY_ITEMS = exports.LLM_MAX_TOKENS_VISION = exports.LLM_MAX_TOKENS_JSON = exports.LLM_MAX_TOKENS_DEFAULT = exports.LLM_BASE_URL = exports.LLM_MODEL_SECONDARY = exports.LLM_MODEL_PRIMARY = void 0;
+exports.YAML_LINE_WIDTH = exports.STOP_WORDS = exports.CLAIM_DURATION_OPTIONS = exports.ESCALATION_BULK_RESOLVE_MAX = exports.YAML_VERSION_LIMIT = exports.YAML_LIST_LIMIT = exports.QUERY_LIMIT_MAX = exports.QUERY_LIMIT_DEFAULT = exports.CONFIG_CACHE_TTL_MS = exports.MCP_TOOL_TIMEOUT_MS = exports.WORKFLOW_SYNC_TIMEOUT_MS = exports.JOB_EXPIRE_SECS = exports.WORKFLOW_EXPIRE_SECS = exports.TOOL_ARG_LIMIT_CAP = exports.TOOL_ROUNDS_MCP_QUERY = exports.TOOL_ROUNDS_TRIAGE = exports.TOOL_RESULT_MAX_CHARS = exports.LLM_MAX_INPUT_CHARS = exports.LLM_MAX_ARRAY_ITEMS = exports.LLM_MAX_TOKENS_VISION = exports.LLM_MAX_TOKENS_JSON = exports.LLM_MAX_TOKENS_DEFAULT = exports.LLM_BASE_URL = exports.LLM_MODEL_SECONDARY = exports.LLM_MODEL_PRIMARY = void 0;
 function envInt(key, fallback) {
     const v = process.env[key];
     if (v === undefined || v === '')
@@ -67,6 +67,8 @@ exports.YAML_LIST_LIMIT = envInt('LT_YAML_LIST_LIMIT', 50);
 /** Default page size for YAML workflow version history. */
 exports.YAML_VERSION_LIMIT = envInt('LT_YAML_VERSION_LIMIT', 20);
 // ── Escalation ──────────────────────────────────────────────────────
+/** Maximum items per atomic bulk resolve (POST /escalations/resolve-all-or-none). */
+exports.ESCALATION_BULK_RESOLVE_MAX = envInt('LT_ESCALATION_BULK_RESOLVE_MAX', 100);
 /**
  * Claim duration presets shown in the dashboard (minutes).
  * Override via JSON array, e.g. LT_CLAIM_DURATION_OPTIONS='[15,30,60,480]'

package/build/routes/escalations/resolve.js

@@ -66,6 +66,24 @@ function registerResolveRoutes(router) {
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
+    /**
+     * POST /api/escalations/resolve-all-or-none
+     * Atomic bulk resolve with per-row payloads: every listed escalation resolves
+     * with its own resolverPayload in one statement, or nothing resolves. Rows
+     * backing a live condition() waiter are woken with their own payload (same
+     * wake contract as /:id/resolve). 409 returns { error, failedIds, failed }
+     * naming exactly the rows that blocked the batch. Max 100 items per call.
+     * Body: { items: Array<{ id: string, resolverPayload: Record<string, any> }>,
+     *         metadata?: Record<string, any>, requireClaimed?: boolean }
+     */
+    router.post('/resolve-all-or-none', async (req, res) => {
+        const result = await api.resolveAllOrNone({
+            items: req.body?.items,
+            metadata: req.body?.metadata,
+            requireClaimed: req.body?.requireClaimed,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * POST /api/escalations/:id/resolve
      * Resolve a pending escalation with a human-provided payload. Routes by

package/build/routes/roles.js

@@ -123,6 +123,26 @@ router.get('/:role/schema/versions', async (req, res) => {
     const result = await api.listRoleSchemaVersions({ role: req.params.role });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
+/**
+ * GET /api/roles/:role/list-schema
+ * Fetch the role's LIST schema (rich list-page formatting). `?version=N` pins a
+ * snapshot; omitted, the live (latest) list schema is returned with its version.
+ * Versions independently from the resolve form schema.
+ */
+router.get('/:role/list-schema', async (req, res) => {
+    const versionParam = req.query.version;
+    const version = versionParam !== undefined ? Number(versionParam) : undefined;
+    const result = await api.getRoleListSchema({ role: req.params.role, version });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
+/**
+ * GET /api/roles/:role/list-schema/versions
+ * List the role's LIST schema version history (newest first).
+ */
+router.get('/:role/list-schema/versions', async (req, res) => {
+    const result = await api.listRoleListSchemaVersions({ role: req.params.role });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * GET /api/roles/:role/escalation-targets
  * Get allowed escalation targets for a specific role.

package/build/sdk/index.d.ts

@@ -153,6 +153,14 @@ export declare function createClient(options?: LTClientOptions): {
             resolverPayload: Record<string, any>;
             metadata?: Record<string, any>;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
+        resolveAllOrNone: (input: {
+            items: Array<{
+                id: string;
+                resolverPayload: Record<string, any>;
+            }>;
+            metadata?: Record<string, any>;
+            requireClaimed?: boolean;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         releaseExpired: typeof escalationsApi.releaseExpiredClaims;
         updatePriority: (input: {
             ids: string[];

package/build/sdk/index.js

@@ -128,6 +128,7 @@ function createClient(options = {}) {
             resolve: bindAuth(escalationsApi.resolveEscalation, auth),
             resolveBySignalKey: bindAuth(escalationsApi.resolveBySignalKey, auth),
             resolveByIds: bindAuth(escalationsApi.resolveByIds, auth),
+            resolveAllOrNone: bindAuth(escalationsApi.resolveAllOrNone, auth),
             releaseExpired: escalationsApi.releaseExpiredClaims,
             updatePriority: bindAuth(escalationsApi.updatePriority, auth),
             bulkClaim: bindAuth(escalationsApi.bulkClaim, auth),

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

@@ -36,6 +36,42 @@ export declare function resolveEscalation(id: string, resolverPayload: Record<st
  * `resolveEscalation` (which delivers the signal).
  */
 export declare function resolveEscalationsByIds(ids: string[], resolverPayload: Record<string, any>, metadata?: Record<string, any>): Promise<LTEscalationRecord[]>;
+/**
+ * Resolve a SET of escalations atomically — every listed row resolves, each
+ * with its OWN resolverPayload, or none do. One SQL statement locks the rows
+ * in deterministic id order, applies per-row payloads, and commits each
+ * waiter's wake WITH its resolve. Unlike {@link resolveEscalationsByIds},
+ * rows backing a live `condition()` waiter are first-class here: each is
+ * woken with its own payload as the condition's return value.
+ *
+ * On failure NOTHING is written and `failed` names exactly the rows that
+ * blocked the batch (`not-found`, `already-resolved`, `already-cancelled`,
+ * `already-expired`, `assignee-mismatch`) — rows that were themselves
+ * resolvable stay pending and are not listed.
+ *
+ * `assertAssignee` (optional) additionally requires every row to be assigned
+ * to that principal, asserted inside the same guarded statement — closing the
+ * claim-race window for claim-then-resolve flows.
+ */
+export declare function resolveEscalationsAllOrNone(items: Array<{
+    id: string;
+    resolverPayload: Record<string, any>;
+}>, metadata?: Record<string, any>, assertAssignee?: string): Promise<{
+    ok: true;
+    escalations: LTEscalationRecord[];
+} | {
+    ok: false;
+    failed: Array<{
+        id: string;
+        reason: string;
+    }>;
+}>;
+/**
+ * Fetch full records for a set of escalation IDs in one indexed query.
+ * Used by bulk orchestrators that need per-row context beyond the scope
+ * fields — signal routing shape, `metadata.form_schema` for redaction.
+ */
+export declare function getEscalationsByIds(ids: string[]): Promise<LTEscalationRecord[]>;
 /**
  * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
  * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.

package/build/services/escalation/crud.js

@@ -4,6 +4,8 @@ exports.createEscalation = createEscalation;
 exports.claimEscalation = claimEscalation;
 exports.resolveEscalation = resolveEscalation;
 exports.resolveEscalationsByIds = resolveEscalationsByIds;
+exports.resolveEscalationsAllOrNone = resolveEscalationsAllOrNone;
+exports.getEscalationsByIds = getEscalationsByIds;
 exports.getEscalationBySignalKey = getEscalationBySignalKey;
 exports.resolveEscalationBySignalKey = resolveEscalationBySignalKey;
 exports.cancelEscalation = cancelEscalation;
@@ -165,6 +167,57 @@ async function resolveEscalationsByIds(ids, resolverPayload, metadata) {
     }
     return records;
 }
+/**
+ * Resolve a SET of escalations atomically — every listed row resolves, each
+ * with its OWN resolverPayload, or none do. One SQL statement locks the rows
+ * in deterministic id order, applies per-row payloads, and commits each
+ * waiter's wake WITH its resolve. Unlike {@link resolveEscalationsByIds},
+ * rows backing a live `condition()` waiter are first-class here: each is
+ * woken with its own payload as the condition's return value.
+ *
+ * On failure NOTHING is written and `failed` names exactly the rows that
+ * blocked the batch (`not-found`, `already-resolved`, `already-cancelled`,
+ * `already-expired`, `assignee-mismatch`) — rows that were themselves
+ * resolvable stay pending and are not listed.
+ *
+ * `assertAssignee` (optional) additionally requires every row to be assigned
+ * to that principal, asserted inside the same guarded statement — closing the
+ * claim-race window for claim-then-resolve flows.
+ */
+async function resolveEscalationsAllOrNone(items, metadata, assertAssignee) {
+    if (items.length === 0)
+        return { ok: true, escalations: [] };
+    const client = await (0, client_1.escalations)();
+    const result = await client.resolveAllOrNone({ items, metadata, assertAssignee });
+    if (!result.ok)
+        return { ok: false, failed: result.failed };
+    const records = (0, map_1.toEscalationRecords)(result.entries);
+    for (const escalation of records) {
+        publishEscalationChange({
+            type: 'escalation.resolved',
+            source: 'service',
+            workflowId: escalation.workflow_id || '',
+            workflowName: escalation.workflow_type || '',
+            taskQueue: escalation.task_queue || '',
+            escalationId: escalation.id,
+            status: 'resolved',
+            data: {},
+        });
+    }
+    return { ok: true, escalations: records };
+}
+/**
+ * Fetch full records for a set of escalation IDs in one indexed query.
+ * Used by bulk orchestrators that need per-row context beyond the scope
+ * fields — signal routing shape, `metadata.form_schema` for redaction.
+ */
+async function getEscalationsByIds(ids) {
+    if (ids.length === 0)
+        return [];
+    const client = await (0, client_1.escalations)();
+    const rows = await client.list({ ids, limit: LOOKUP_LIMIT });
+    return (0, map_1.toEscalationRecords)(rows);
+}
 /**
  * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
  * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.

package/build/services/maintenance/index.js

@@ -38,6 +38,7 @@ const hotmesh_1 = require("@hotmeshio/hotmesh");
 const db_1 = require("../../lib/db");
 const logger_1 = require("../../lib/logger");
 const dbaService = __importStar(require("../dba"));
+const client_1 = require("../escalation/client");
 const CRON_TOPIC = 'lt.maintenance.prune';
 const CRON_ID = 'lt-maintenance-nightly';
 /**
@@ -84,6 +85,27 @@ async function executeRule(appId, rule) {
                 streams: false,
             });
             break;
+        // Age out terminal escalation rows (resolved/cancelled/expired). The
+        // engine-owned prune deletes at most one batch per call in one atomic
+        // statement; loop until the horizon is drained. Pending rows and live
+        // condition() waiters are never touched — every engine state transition
+        // guards on status='pending', so terminal rows are inert audit records.
+        case rule.target === 'escalations' && rule.action === 'delete': {
+            const client = await (0, client_1.escalations)();
+            let deleted = 0;
+            let batch;
+            do {
+                ({ deleted: batch } = await client.prune({
+                    olderThan: rule.olderThan,
+                    statuses: rule.statuses,
+                }));
+                deleted += batch;
+            } while (batch > 0);
+            if (deleted > 0) {
+                logger_1.loggerRegistry.info(`[lt-maintenance] escalations pruned: ${deleted} (olderThan: ${rule.olderThan})`);
+            }
+            break;
+        }
         default:
             logger_1.loggerRegistry.warn(`[lt-maintenance] unknown rule, skipping: ${JSON.stringify(rule)}`);
     }

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

@@ -1,4 +1,4 @@
-import type { EscalationChain, RoleDetail, RoleSchemaVersion, RoleSchemaVersionSummary, UpdateRoleInput } from './types';
+import type { EscalationChain, RoleDetail, RoleSchemaVersion, RoleSchemaVersionSummary, RoleListSchemaVersion, RoleListSchemaVersionSummary, UpdateRoleInput } from './types';
 /**
  * Get the roles a given source role can escalate to.
  */
@@ -60,6 +60,18 @@ export declare function listRoleSchemaVersions(role: string): Promise<RoleSchema
  * Returns null when the role (or the requested version) does not exist.
  */
 export declare function getRoleSchema(role: string, version?: number): Promise<RoleSchemaVersion | null>;
+/**
+ * List the list-schema version history for a role (newest first). The schema is
+ * elided — presence flag only; fetch a full snapshot via getRoleListSchema.
+ */
+export declare function listRoleListSchemaVersions(role: string): Promise<RoleListSchemaVersionSummary[]>;
+/**
+ * Fetch a role's list schema. With a version, reads the immutable snapshot from
+ * lt_role_list_schemas; without one, the live (latest) column — a role that has
+ * never versioned its list schema still answers with version null. Returns null
+ * when the role (or the requested version) does not exist.
+ */
+export declare function getRoleListSchema(role: string, version?: number): Promise<RoleListSchemaVersion | null>;
 /**
  * Fetch a role's live form_schema — the escalation form the dashboard renders.
  */