@hotmeshio/long-tail 0.1.0

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

@@ -0,0 +1,21 @@
+/**
+ * List all HotMesh applications from the global registry.
+ * Keys follow the pattern `hmsh:a:{appId}`. Non-expired only.
+ */
+export declare const LIST_APPS = "\n  SELECT DISTINCT key FROM hotmesh_applications\n  WHERE key LIKE 'hmsh:a:%'\n    AND (expiry IS NULL OR expiry > NOW())\n  ORDER BY key";
+/**
+ * Count pending (unprocessed) stream messages across both tables.
+ * expired_at IS NULL = message has not been consumed yet.
+ * $1 = stream_name filter (NULL = all streams).
+ */
+export declare const COUNT_PENDING: (schema: string) => string;
+/**
+ * Count processed stream messages within a time interval.
+ * $1 = interval, $2 = stream_name filter (NULL = all streams).
+ */
+export declare const COUNT_PROCESSED_SINCE: (schema: string) => string;
+/**
+ * Volume breakdown by stream_name within a time interval.
+ * $1 = interval, $2 = stream_name filter (NULL = all streams).
+ */
+export declare const VOLUME_BY_STREAM: (schema: string) => string;

package/build/services/controlplane/sql.js

@@ -0,0 +1,70 @@
+"use strict";
+// ─── Application discovery ──────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOLUME_BY_STREAM = exports.COUNT_PROCESSED_SINCE = exports.COUNT_PENDING = exports.LIST_APPS = void 0;
+/**
+ * List all HotMesh applications from the global registry.
+ * Keys follow the pattern `hmsh:a:{appId}`. Non-expired only.
+ */
+exports.LIST_APPS = `
+  SELECT DISTINCT key FROM hotmesh_applications
+  WHERE key LIKE 'hmsh:a:%'
+    AND (expiry IS NULL OR expiry > NOW())
+  ORDER BY key`;
+// ─── Stream statistics ──────────────────────────────────────────────────────
+//
+// HotMesh v0.11.0 split the single `streams` table into `engine_streams`
+// (internal engine orchestration) and `worker_streams` (worker task messages).
+// All queries now UNION both tables for aggregate statistics.
+/**
+ * Count pending (unprocessed) stream messages across both tables.
+ * expired_at IS NULL = message has not been consumed yet.
+ * $1 = stream_name filter (NULL = all streams).
+ */
+const COUNT_PENDING = (schema) => `
+  SELECT COUNT(*)::int AS count FROM (
+    SELECT stream_name FROM "${schema}".engine_streams
+    WHERE expired_at IS NULL
+      AND ($1::text IS NULL OR stream_name = $1)
+    UNION ALL
+    SELECT stream_name FROM "${schema}".worker_streams
+    WHERE expired_at IS NULL
+      AND ($1::text IS NULL OR stream_name = $1)
+  ) combined`;
+exports.COUNT_PENDING = COUNT_PENDING;
+/**
+ * Count processed stream messages within a time interval.
+ * $1 = interval, $2 = stream_name filter (NULL = all streams).
+ */
+const COUNT_PROCESSED_SINCE = (schema) => `
+  SELECT COUNT(*)::int AS count FROM (
+    SELECT stream_name FROM "${schema}".engine_streams
+    WHERE expired_at IS NOT NULL
+      AND expired_at > NOW() - $1::interval
+      AND ($2::text IS NULL OR stream_name = $2)
+    UNION ALL
+    SELECT stream_name FROM "${schema}".worker_streams
+    WHERE expired_at IS NOT NULL
+      AND expired_at > NOW() - $1::interval
+      AND ($2::text IS NULL OR stream_name = $2)
+  ) combined`;
+exports.COUNT_PROCESSED_SINCE = COUNT_PROCESSED_SINCE;
+/**
+ * Volume breakdown by stream_name within a time interval.
+ * $1 = interval, $2 = stream_name filter (NULL = all streams).
+ */
+const VOLUME_BY_STREAM = (schema) => `
+  SELECT stream_type, stream_name, COUNT(*)::int AS count FROM (
+    SELECT 'engine' AS stream_type, stream_name FROM "${schema}".engine_streams
+    WHERE expired_at IS NOT NULL
+      AND expired_at > NOW() - $1::interval
+      AND ($2::text IS NULL OR stream_name = $2)
+    UNION ALL
+    SELECT 'worker' AS stream_type, stream_name FROM "${schema}".worker_streams
+    WHERE expired_at IS NOT NULL
+      AND expired_at > NOW() - $1::interval
+      AND ($2::text IS NULL OR stream_name = $2)
+  ) combined
+  GROUP BY stream_type, stream_name
+  ORDER BY stream_type, count DESC`;
+exports.VOLUME_BY_STREAM = VOLUME_BY_STREAM;

package/build/services/controlplane/types.d.ts

@@ -0,0 +1,13 @@
+/** Type definitions for the control plane service. */
+export interface ControlPlaneApp {
+    appId: string;
+}
+export interface StreamStats {
+    pending: number;
+    processed: number;
+    byStream: Array<{
+        stream_type: 'engine' | 'worker';
+        stream_name: string;
+        count: number;
+    }>;
+}

package/build/services/controlplane/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Type definitions for the control plane service. */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,46 @@
+import type { LTWorkflowConfig } from '../../types';
+/**
+ * Singleton registry for workflow cron schedules.
+ *
+ * Follows the same pattern as maintenanceRegistry:
+ * - connect()   — load configs with cron_schedule, start Virtual.cron for each
+ * - disconnect() — interrupt all crons
+ * - restartCron() — stop + start a single cron after config change
+ * - clear()     — reset for tests
+ */
+declare class LTCronRegistry {
+    private activeCrons;
+    private connected;
+    private systemPrincipal;
+    /**
+     * Load all workflow configs with a cron_schedule and start Virtual.cron for each.
+     * Call after workers and migrations are ready.
+     */
+    connect(): Promise<void>;
+    /**
+     * Start a single Virtual.cron for a workflow config.
+     */
+    startCron(config: LTWorkflowConfig): Promise<void>;
+    /**
+     * Stop a single cron for a workflow type.
+     */
+    stopCron(workflowType: string): Promise<void>;
+    /**
+     * Restart a cron after a config change.
+     * Stops the old cron (if any) and starts a new one if cron_schedule is set.
+     */
+    restartCron(config: LTWorkflowConfig): Promise<void>;
+    /**
+     * Stop all active crons. Call during graceful shutdown.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Reset state. Used in tests.
+     */
+    clear(): void;
+    get hasActiveCrons(): boolean;
+    get activeWorkflowTypes(): string[];
+}
+/** Singleton cron registry */
+export declare const cronRegistry: LTCronRegistry;
+export {};

package/build/services/cron/index.js

@@ -0,0 +1,199 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cronRegistry = void 0;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const pg_1 = require("pg");
+const config_1 = require("../../modules/config");
+const defaults_1 = require("../../modules/defaults");
+const logger_1 = require("../logger");
+const configService = __importStar(require("../config"));
+const principal_1 = require("../iam/principal");
+const CRON_TOPIC_PREFIX = 'lt.cron';
+const CRON_ID_PREFIX = 'lt-cron';
+/**
+ * Singleton registry for workflow cron schedules.
+ *
+ * Follows the same pattern as maintenanceRegistry:
+ * - connect()   — load configs with cron_schedule, start Virtual.cron for each
+ * - disconnect() — interrupt all crons
+ * - restartCron() — stop + start a single cron after config change
+ * - clear()     — reset for tests
+ */
+class LTCronRegistry {
+    constructor() {
+        this.activeCrons = new Map(); // workflowType -> cronId
+        this.connected = false;
+        this.systemPrincipal = null;
+    }
+    /**
+     * Load all workflow configs with a cron_schedule and start Virtual.cron for each.
+     * Call after workers and migrations are ready.
+     */
+    async connect() {
+        if (this.connected)
+            return;
+        // Resolve the real system bot principal (ensured at startup)
+        this.systemPrincipal = await (0, principal_1.resolvePrincipal)('lt-system');
+        const configs = await configService.listWorkflowConfigs();
+        const cronConfigs = configs.filter((c) => c.cron_schedule && c.invocable && c.task_queue);
+        for (const config of cronConfigs) {
+            await this.startCron(config);
+        }
+        this.connected = true;
+        if (cronConfigs.length > 0) {
+            logger_1.loggerRegistry.info(`[lt-cron] started ${cronConfigs.length} cron(s): ${cronConfigs.map((c) => c.workflow_type).join(', ')}`);
+        }
+    }
+    /**
+     * Start a single Virtual.cron for a workflow config.
+     */
+    async startCron(config) {
+        if (!config.cron_schedule || !config.task_queue)
+            return;
+        const connection = { class: pg_1.Client, options: config_1.postgres_options };
+        const topic = `${CRON_TOPIC_PREFIX}.${config.workflow_type}`;
+        const cronId = `${CRON_ID_PREFIX}-${config.workflow_type}`;
+        const defaultEnvelope = config.envelope_schema
+            ? { ...config.envelope_schema }
+            : { data: {}, metadata: {} };
+        // Ensure metadata.source identifies the cron
+        if (!defaultEnvelope.metadata)
+            defaultEnvelope.metadata = {};
+        defaultEnvelope.metadata.source = 'cron';
+        // Resolve executing principal: per-config execute_as, or system bot fallback
+        if (!defaultEnvelope.lt)
+            defaultEnvelope.lt = {};
+        if (!defaultEnvelope.lt.principal) {
+            let cronPrincipal = this.systemPrincipal;
+            if (config.execute_as) {
+                const botPrincipal = await (0, principal_1.resolvePrincipal)(config.execute_as);
+                if (botPrincipal)
+                    cronPrincipal = botPrincipal;
+            }
+            if (cronPrincipal) {
+                defaultEnvelope.lt.userId = cronPrincipal.id;
+                defaultEnvelope.lt.principal = cronPrincipal;
+            }
+            defaultEnvelope.lt.scopes = ['workflow:cron'];
+        }
+        const workflowType = config.workflow_type;
+        const taskQueue = config.task_queue;
+        await hotmesh_1.Virtual.cron({
+            topic,
+            connection,
+            callback: async () => {
+                try {
+                    const client = new hotmesh_1.Durable.Client({ connection });
+                    const workflowId = `${workflowType}-cron-${hotmesh_1.Durable.guid()}`;
+                    logger_1.loggerRegistry.info(`[lt-cron] invoking ${workflowType} (${workflowId})`);
+                    await client.workflow.start({
+                        args: [defaultEnvelope],
+                        taskQueue,
+                        workflowName: workflowType,
+                        workflowId,
+                        expire: defaults_1.JOB_EXPIRE_SECS,
+                        entity: workflowType,
+                    });
+                }
+                catch (err) {
+                    logger_1.loggerRegistry.error(`[lt-cron] ${workflowType} failed: ${err?.message}`);
+                }
+            },
+            args: [],
+            options: {
+                id: cronId,
+                interval: config.cron_schedule,
+            },
+        });
+        this.activeCrons.set(config.workflow_type, cronId);
+    }
+    /**
+     * Stop a single cron for a workflow type.
+     */
+    async stopCron(workflowType) {
+        const cronId = this.activeCrons.get(workflowType);
+        if (!cronId)
+            return;
+        const connection = { class: pg_1.Client, options: config_1.postgres_options };
+        const topic = `${CRON_TOPIC_PREFIX}.${workflowType}`;
+        try {
+            await hotmesh_1.Virtual.interrupt({
+                topic,
+                connection,
+                options: { id: cronId },
+            });
+        }
+        catch (err) {
+            logger_1.loggerRegistry.warn(`[lt-cron] interrupt failed for ${workflowType}: ${err?.message}`);
+        }
+        this.activeCrons.delete(workflowType);
+    }
+    /**
+     * Restart a cron after a config change.
+     * Stops the old cron (if any) and starts a new one if cron_schedule is set.
+     */
+    async restartCron(config) {
+        await this.stopCron(config.workflow_type);
+        if (config.cron_schedule && config.invocable && config.task_queue) {
+            await this.startCron(config);
+            logger_1.loggerRegistry.info(`[lt-cron] restarted ${config.workflow_type} (${config.cron_schedule})`);
+        }
+    }
+    /**
+     * Stop all active crons. Call during graceful shutdown.
+     */
+    async disconnect() {
+        for (const workflowType of [...this.activeCrons.keys()]) {
+            await this.stopCron(workflowType);
+        }
+        this.connected = false;
+    }
+    /**
+     * Reset state. Used in tests.
+     */
+    clear() {
+        this.activeCrons.clear();
+        this.connected = false;
+    }
+    get hasActiveCrons() {
+        return this.activeCrons.size > 0;
+    }
+    get activeWorkflowTypes() {
+        return [...this.activeCrons.keys()];
+    }
+}
+/** Singleton cron registry */
+exports.cronRegistry = new LTCronRegistry();

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

@@ -0,0 +1,3 @@
+import { Pool } from 'pg';
+export declare function getPool(): Pool;
+export declare function closePool(): Promise<void>;

package/build/services/db/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPool = getPool;
+exports.closePool = closePool;
+const pg_1 = require("pg");
+const config_1 = require("../../modules/config");
+let pool = null;
+function getPool() {
+    if (!pool) {
+        pool = new pg_1.Pool(config_1.postgres_options);
+    }
+    return pool;
+}
+async function closePool() {
+    if (pool) {
+        await pool.end();
+        pool = null;
+    }
+}

package/build/services/db/migrate.d.ts

@@ -0,0 +1 @@
+export declare function migrate(): Promise<void>;

package/build/services/db/migrate.js

@@ -0,0 +1,78 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrate = migrate;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const index_1 = require("./index");
+const logger_1 = require("../logger");
+const SCHEMAS_DIR = path.join(__dirname, 'schemas');
+async function migrate() {
+    const pool = (0, index_1.getPool)();
+    // ensure migration tracking table
+    await pool.query(`
+    CREATE TABLE IF NOT EXISTS lt_migrations (
+      id SERIAL PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    );
+  `);
+    // find and sort migration files
+    const files = fs.readdirSync(SCHEMAS_DIR)
+        .filter(f => f.endsWith('.sql'))
+        .sort();
+    for (const file of files) {
+        const { rows } = await pool.query('SELECT 1 FROM lt_migrations WHERE name = $1', [file]);
+        if (rows.length === 0) {
+            const sql = fs.readFileSync(path.join(SCHEMAS_DIR, file), 'utf-8');
+            await pool.query(sql);
+            await pool.query('INSERT INTO lt_migrations (name) VALUES ($1)', [file]);
+            logger_1.loggerRegistry.info(`[migrate] applied: ${file}`);
+        }
+    }
+}
+// run directly: npx ts-node services/db/migrate.ts
+if (require.main === module) {
+    require('dotenv').config();
+    migrate()
+        .then(() => {
+        logger_1.loggerRegistry.info('[migrate] done');
+        return (0, index_1.closePool)();
+    })
+        .catch((err) => {
+        logger_1.loggerRegistry.error(`[migrate] failed: ${err}`);
+        process.exit(1);
+    });
+}

package/build/services/dba.d.ts

@@ -0,0 +1,28 @@
+import type { PruneOptions, PruneResult } from '@hotmeshio/hotmesh/build/types/dba';
+/**
+ * Deploy the server-side prune() Postgres function and run
+ * any schema migrations (e.g. adding the `pruned_at` column).
+ * Idempotent — safe to call on every startup.
+ */
+export declare function deploy(): Promise<void>;
+/**
+ * Prune expired jobs, streams, and/or execution artifacts.
+ *
+ * - `jobs` — hard-delete expired job rows older than `expire`
+ * - `streams` — hard-delete expired stream messages (engine + worker) older than `expire`
+ * - `attributes` — strip execution artifacts from completed jobs
+ *   (preserves jdata, udata, jmark for execution export)
+ * - `entities` — allowlist: only prune these entity types
+ * - `pruneTransient` — also delete jobs where entity IS NULL
+ * - `keepHmark` — preserve hmark rows during stripping
+ */
+export declare function prune(options: {
+    expire?: string;
+    jobs?: boolean;
+    streams?: boolean;
+    attributes?: boolean;
+    entities?: string[];
+    pruneTransient?: boolean;
+    keepHmark?: boolean;
+}): Promise<PruneResult>;
+export type { PruneOptions, PruneResult };

package/build/services/dba.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploy = deploy;
+exports.prune = prune;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const pg_1 = require("pg");
+const config_1 = require("../modules/config");
+const APP_ID = 'durable';
+/**
+ * Deploy the server-side prune() Postgres function and run
+ * any schema migrations (e.g. adding the `pruned_at` column).
+ * Idempotent — safe to call on every startup.
+ */
+async function deploy() {
+    const connection = { class: pg_1.Client, options: config_1.postgres_options };
+    await hotmesh_1.DBA.deploy(connection, APP_ID);
+}
+/**
+ * Prune expired jobs, streams, and/or execution artifacts.
+ *
+ * - `jobs` — hard-delete expired job rows older than `expire`
+ * - `streams` — hard-delete expired stream messages (engine + worker) older than `expire`
+ * - `attributes` — strip execution artifacts from completed jobs
+ *   (preserves jdata, udata, jmark for execution export)
+ * - `entities` — allowlist: only prune these entity types
+ * - `pruneTransient` — also delete jobs where entity IS NULL
+ * - `keepHmark` — preserve hmark rows during stripping
+ */
+async function prune(options) {
+    const connection = { class: pg_1.Client, options: config_1.postgres_options };
+    return hotmesh_1.DBA.prune({ appId: APP_ID, connection, ...options });
+}

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

@@ -0,0 +1,27 @@
+import type { LTEscalationRecord } from '../../types';
+/**
+ * Bulk claim escalations for a user.
+ * Items already claimed by another active user are skipped.
+ */
+export declare function bulkClaimEscalations(ids: string[], userId: string, durationMinutes?: number): Promise<{
+    claimed: number;
+    skipped: number;
+}>;
+/**
+ * Bulk assign escalations to a specific user (admin action).
+ * Items already claimed by another active user are skipped.
+ */
+export declare function bulkAssignEscalations(ids: string[], targetUserId: string, durationMinutes?: number): Promise<{
+    assigned: number;
+    skipped: number;
+}>;
+/**
+ * Bulk reassign escalations to a different role.
+ * Clears assignment on all affected rows.
+ */
+export declare function bulkEscalateToRole(ids: string[], targetRole: string): Promise<number>;
+/**
+ * Bulk resolve escalations for AI triage.
+ * Returns full records so the caller can start triage workflows.
+ */
+export declare function bulkResolveForTriage(ids: string[], hint?: string): Promise<LTEscalationRecord[]>;

package/build/services/escalation/bulk.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bulkClaimEscalations = bulkClaimEscalations;
+exports.bulkAssignEscalations = bulkAssignEscalations;
+exports.bulkEscalateToRole = bulkEscalateToRole;
+exports.bulkResolveForTriage = bulkResolveForTriage;
+const db_1 = require("../db");
+const sql_1 = require("./sql");
+/**
+ * Bulk claim escalations for a user.
+ * Items already claimed by another active user are skipped.
+ */
+async function bulkClaimEscalations(ids, userId, durationMinutes = 30) {
+    if (ids.length === 0)
+        return { claimed: 0, skipped: 0 };
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(sql_1.BULK_CLAIM, [userId, durationMinutes, ids]);
+    const claimed = rowCount ?? 0;
+    return { claimed, skipped: ids.length - claimed };
+}
+/**
+ * Bulk assign escalations to a specific user (admin action).
+ * Items already claimed by another active user are skipped.
+ */
+async function bulkAssignEscalations(ids, targetUserId, durationMinutes = 30) {
+    if (ids.length === 0)
+        return { assigned: 0, skipped: 0 };
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(sql_1.BULK_ASSIGN, [targetUserId, durationMinutes, ids]);
+    const assigned = rowCount ?? 0;
+    return { assigned, skipped: ids.length - assigned };
+}
+/**
+ * Bulk reassign escalations to a different role.
+ * Clears assignment on all affected rows.
+ */
+async function bulkEscalateToRole(ids, targetRole) {
+    if (ids.length === 0)
+        return 0;
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(sql_1.BULK_ESCALATE_TO_ROLE, [targetRole, ids]);
+    return rowCount ?? 0;
+}
+/**
+ * Bulk resolve escalations for AI triage.
+ * Returns full records so the caller can start triage workflows.
+ */
+async function bulkResolveForTriage(ids, hint) {
+    if (ids.length === 0)
+        return [];
+    const pool = (0, db_1.getPool)();
+    const resolverPayload = JSON.stringify({
+        _lt: { needsTriage: true, ...(hint ? { hint } : {}) },
+    });
+    const { rows } = await pool.query(sql_1.BULK_RESOLVE_FOR_TRIAGE, [resolverPayload, ids]);
+    return rows;
+}

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

@@ -0,0 +1,47 @@
+import type { LTEscalationRecord } from '../../types';
+import type { CreateEscalationInput, ClaimResult } from './types';
+export declare function createEscalation(input: CreateEscalationInput): Promise<LTEscalationRecord>;
+/**
+ * Atomic claim operation. Does NOT change status — "claimed" is implicit
+ * via assigned_to + assigned_until > NOW().
+ *
+ * Conditions:
+ * - status = 'pending' (not resolved/cancelled)
+ * - Either: unassigned, expired claim, or same user (extension)
+ *
+ * Uses a CTE to capture the previous state so callers can detect extensions.
+ */
+export declare function claimEscalation(id: string, userId: string, durationMinutes?: number): Promise<ClaimResult | null>;
+export declare function resolveEscalation(id: string, resolverPayload: Record<string, any>): Promise<LTEscalationRecord | null>;
+/**
+ * Bulk update priority for a set of escalations.
+ * Only updates pending escalations.
+ */
+export declare function updateEscalationsPriority(ids: string[], priority: 1 | 2 | 3 | 4): Promise<number>;
+/**
+ * Get the distinct roles for a set of escalation IDs.
+ * Used for permission validation before bulk operations.
+ */
+export declare function getEscalationRoles(ids: string[]): Promise<string[]>;
+/**
+ * Release a single escalation claim back to the available pool.
+ * Only the assigned user (or superadmin via route) may release.
+ */
+export declare function releaseEscalation(id: string, userId: string): Promise<LTEscalationRecord | null>;
+export declare function releaseExpiredClaims(): Promise<number>;
+/**
+ * Reassign an escalation to a different role.
+ * Clears the current assignment so it becomes available to the new role.
+ */
+export declare function escalateToRole(id: string, targetRole: string): Promise<LTEscalationRecord | null>;
+export declare function getEscalation(id: string): Promise<LTEscalationRecord | null>;
+export declare function getEscalationsByTaskId(taskId: string): Promise<LTEscalationRecord[]>;
+export declare function getEscalationsByWorkflowId(workflowId: string): Promise<LTEscalationRecord[]>;
+export declare function updateEscalationMetadata(id: string, patch: Record<string, any>): Promise<LTEscalationRecord | null>;
+export declare function enrichEscalationRouting(id: string, metadataPatch: Record<string, any>, workflowFields: {
+    workflowType?: string;
+    workflowId?: string;
+    taskQueue?: string;
+    taskId?: string;
+}): Promise<LTEscalationRecord | null>;
+export declare function getEscalationsByOriginId(originId: string): Promise<LTEscalationRecord[]>;