@hotmeshio/long-tail 0.5.2 → 0.5.4

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

@@ -3,5 +3,5 @@ export { listEscalations, listAvailableEscalations, listDistinctTypes, getEscala
 export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './single';
 export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkEscalate, bulkTriage } from './bulk';
-export { resolveEscalation } from './resolve';
+export { resolveEscalation, resolveBySignalKey } from './resolve';
 export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = 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.getEscalationStats = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = 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.getEscalationStats = 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");
@@ -24,6 +24,7 @@ Object.defineProperty(exports, "bulkEscalate", { enumerable: true, get: function
 Object.defineProperty(exports, "bulkTriage", { enumerable: true, get: function () { return bulk_1.bulkTriage; } });
 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; } });
 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

@@ -16,3 +16,13 @@ export declare function resolveEscalation(input: {
     id: string;
     resolverPayload: Record<string, any>;
 }, _auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Resolve an efficient (atomic) escalation directly by its `signal_key` and
+ * resume the waiting workflow in place. For webhook callers that know the
+ * deterministic signal id (e.g. `signal-scan-ar-${orderId}`) and want to skip
+ * the id lookup. RBAC-scoped to the caller's visible roles.
+ */
+export declare function resolveBySignalKey(input: {
+    signalKey: string;
+    resolverPayload: Record<string, any>;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/resolve.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveEscalation = resolveEscalation;
+exports.resolveBySignalKey = resolveBySignalKey;
 const escalationService = __importStar(require("../../services/escalation"));
 const taskService = __importStar(require("../../services/task"));
 const escalation_strategy_1 = require("../../services/escalation-strategy");
@@ -41,6 +42,7 @@ const ephemeral_1 = require("../../services/iam/ephemeral");
 const deployer_1 = require("../../services/yaml-workflow/deployer");
 const workers_1 = require("../../workers");
 const defaults_1 = require("../../modules/defaults");
+const helpers_1 = require("./helpers");
 // ── Orchestrator ─────────────────────────────────────────────────────────
 /**
  * Resolve a pending escalation with a human-provided payload.
@@ -76,6 +78,13 @@ async function resolveEscalation(input, _auth) {
         if (signalRouting?.signalId) {
             return resolveViaSignalRouting(escalation, resolverPayload);
         }
+        // Path 0: efficient (atomic) escalation — signal_key resumes in place.
+        // The row was written inside the workflow's Leg1 checkpoint via
+        // `condition(signalId, config)`. The SDK's resolve marks it resolved AND
+        // delivers the signal to `signal_key`, resuming THIS job — no re-run.
+        if (escalation.signal_key) {
+            return resolveViaSignalKey(escalation, resolverPayload);
+        }
         // Path C: escalation strategy may redirect to triage
         const envelope = await reconstructEnvelope(escalation);
         const strategy = escalation_strategy_1.escalationStrategyRegistry.current;
@@ -97,6 +106,34 @@ async function resolveEscalation(input, _auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Resolve an efficient (atomic) escalation directly by its `signal_key` and
+ * resume the waiting workflow in place. For webhook callers that know the
+ * deterministic signal id (e.g. `signal-scan-ar-${orderId}`) and want to skip
+ * the id lookup. RBAC-scoped to the caller's visible roles.
+ */
+async function resolveBySignalKey(input, auth) {
+    try {
+        const { signalKey, resolverPayload } = input;
+        if (!signalKey)
+            return { status: 400, error: 'signalKey is required' };
+        if (!resolverPayload)
+            return { status: 400, error: 'resolverPayload is required' };
+        const escalation = await escalationService.getEscalationBySignalKey(signalKey);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (escalation.status !== 'pending')
+            return { status: 409, error: 'Escalation not available for resolution' };
+        const visibleRoles = await (0, helpers_1.getVisibleRoles)(auth.userId);
+        if (visibleRoles && !visibleRoles.includes(escalation.role)) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        return resolveViaSignalKey(escalation, resolverPayload);
+    }
+    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) {
@@ -107,6 +144,21 @@ async function resolveViaConditionSignal(escalation, resolverPayload) {
     // Event published by service layer (services/escalation/crud.ts)
     return signaledResult(escalation, escalation.workflow_id);
 }
+/**
+ * Path 0: efficient escalation — resolve by `signal_key`. The SDK delivers the
+ * signal to the waiting `condition()` AND marks the row resolved in one
+ * transaction, so the original job resumes in place (no re-run, no separate
+ * resolve activity). Password fields are redacted before they enter the signal.
+ */
+async function resolveViaSignalKey(escalation, resolverPayload) {
+    const signalPayload = await redactPasswords(resolverPayload, escalation.metadata?.form_schema);
+    const resolved = await escalationService.resolveEscalation(escalation.id, signalPayload);
+    if (!resolved) {
+        return { status: 409, error: 'Escalation not available for resolution' };
+    }
+    // Event published by service layer (services/escalation/crud.ts)
+    return signaledResult(escalation, escalation.workflow_id || '');
+}
 /** Path B: waitFor signal escalation — signal via YAML engine or Durable handle. */
 async function resolveViaSignalRouting(escalation, resolverPayload) {
     const signalRouting = escalation.metadata.signal_routing;

package/build/lib/events/system-events.d.ts

@@ -0,0 +1,19 @@
+import type { Types } from '@hotmeshio/hotmesh';
+import type { LTEvent } from '../../types';
+type SystemEvent = Types.SystemEvent;
+/**
+ * Translate a HotMesh `SystemEvent` into long-tail's `LTEvent`. Escalation
+ * events carry the full committed row in `data`, from which we lift the routing
+ * fields; engine/worker lifecycle events pass through with their canonical type.
+ */
+export declare function mapSystemEvent(event: SystemEvent): LTEvent;
+/**
+ * The `EventsConfig.publish` hook long-tail wires into every worker/engine it
+ * constructs. Fire-and-forget — never throws back into the SDK's committed call.
+ */
+export declare function onSystemEvent(event: SystemEvent): void;
+/** The EventsConfig long-tail passes to Durable.Client / Worker.create / HotMesh.init. */
+export declare const systemEventsConfig: {
+    publish: typeof onSystemEvent;
+};
+export {};

package/build/lib/events/system-events.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemEventsConfig = void 0;
+exports.mapSystemEvent = mapSystemEvent;
+exports.onSystemEvent = onSystemEvent;
+const index_1 = require("./index");
+/** Verb → long-tail event status, matching the manual publishEscalationEvent convention. */
+const ESCALATION_STATUS_BY_VERB = {
+    created: 'pending',
+    claimed: 'claimed',
+    released: 'released',
+    reassigned: 'pending',
+    resolved: 'resolved',
+    cancelled: 'cancelled',
+};
+/**
+ * Translate a HotMesh `SystemEvent` into long-tail's `LTEvent`. Escalation
+ * events carry the full committed row in `data`, from which we lift the routing
+ * fields; engine/worker lifecycle events pass through with their canonical type.
+ */
+function mapSystemEvent(event) {
+    const segments = event.type.split('.');
+    const domain = segments[1];
+    if (domain === 'escalation') {
+        const row = (event.data ?? {});
+        const verb = segments[3] ?? '';
+        return {
+            type: event.type,
+            source: 'sdk',
+            workflowId: row.workflow_id || event.workflow_id || '',
+            workflowName: row.workflow_type || '',
+            taskQueue: row.task_queue || '',
+            escalationId: row.id || segments[2],
+            originId: row.origin_id || event.origin_id || undefined,
+            status: ESCALATION_STATUS_BY_VERB[verb] ?? verb,
+            data: row,
+            timestamp: event.ts,
+        };
+    }
+    // Engine / worker lifecycle (system.engine.*, system.worker.*) — additive
+    // observability; pass through with the canonical type and metadata payload.
+    return {
+        type: event.type,
+        source: 'sdk',
+        workflowId: event.workflow_id || '',
+        workflowName: '',
+        taskQueue: event.data?.taskQueue || '',
+        data: event.data,
+        timestamp: event.ts,
+    };
+}
+/**
+ * The `EventsConfig.publish` hook long-tail wires into every worker/engine it
+ * constructs. Fire-and-forget — never throws back into the SDK's committed call.
+ */
+function onSystemEvent(event) {
+    if (!index_1.eventRegistry.hasAdapters)
+        return;
+    void index_1.eventRegistry.publish(mapSystemEvent(event)).catch(() => { });
+}
+/** The EventsConfig long-tail passes to Durable.Client / Worker.create / HotMesh.init. */
+exports.systemEventsConfig = { publish: onSystemEvent };

package/build/modules/ltconfig.d.ts

@@ -23,6 +23,14 @@ declare class LTConfigCache {
      * return null so the interceptor skips them.
      */
     getResolvedConfig(name: string): Promise<LTResolvedConfig | null>;
+    /**
+     * Get the config for any workflow REGISTERED in lt_config_workflows (a row
+     * exists), regardless of certification (roles/consumes). The interceptor
+     * uses this to decide whether to apply task tracking, escalation handling,
+     * and orchestrator context — every registered workflow gets the full
+     * treatment; only unregistered ad-hoc durable workflows are skipped.
+     */
+    getRegisteredConfig(name: string): Promise<LTResolvedConfig | null>;
 }
 export declare const ltConfig: LTConfigCache;
 export {};

package/build/modules/ltconfig.js

@@ -116,5 +116,15 @@ class LTConfigCache {
         const isCertified = (config.roles?.length ?? 0) > 0 || (config.consumes?.length ?? 0) > 0;
         return isCertified ? config : null;
     }
+    /**
+     * Get the config for any workflow REGISTERED in lt_config_workflows (a row
+     * exists), regardless of certification (roles/consumes). The interceptor
+     * uses this to decide whether to apply task tracking, escalation handling,
+     * and orchestrator context — every registered workflow gets the full
+     * treatment; only unregistered ad-hoc durable workflows are skipped.
+     */
+    async getRegisteredConfig(name) {
+        return (await this.get(name)) ?? null;
+    }
 }
 exports.ltConfig = new LTConfigCache();

package/build/routes/escalations/resolve.js

@@ -36,11 +36,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerResolveRoutes = registerResolveRoutes;
 const api = __importStar(require("../../api/escalations"));
 function registerResolveRoutes(router) {
+    /**
+     * POST /api/escalations/resolve-by-signal-key
+     * Resolve an efficient (atomic) escalation by its signal_key and resume the
+     * waiting workflow in place. For webhook callers that know the deterministic
+     * signal id. Literal single-segment path — registered before /:id/resolve so
+     * it is never shadowed by the parameterized route.
+     * Body: { signalKey: string, resolverPayload: Record<string, any> }
+     */
+    router.post('/resolve-by-signal-key', async (req, res) => {
+        const result = await api.resolveBySignalKey({ signalKey: req.body?.signalKey, resolverPayload: req.body?.resolverPayload }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * POST /api/escalations/:id/resolve
-     * Start a new workflow with resolver data to re-run the failed step.
-     * The interceptor in the new workflow resolves the escalation record
-     * and signals back to the orchestrator (if any) on success.
+     * Resolve a pending escalation with a human-provided payload. Routes by
+     * escalation shape: efficient (signal_key) resumes the job in place; legacy
+     * paths signal via routing metadata or re-run the original workflow.
      * Body: { resolverPayload: Record<string, any> }
      */
     router.post('/:id/resolve', async (req, res) => {

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

@@ -22,6 +22,7 @@ export declare function bulkAssignEscalations(ids: string[], targetUserId: strin
 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.
+ * Returns full records so the caller can start triage workflows. No signal is
+ * delivered — the triage workflow takes over handling.
  */
 export declare function bulkResolveForTriage(ids: string[], hint?: string): Promise<LTEscalationRecord[]>;

package/build/services/escalation/bulk.js

@@ -4,8 +4,8 @@ exports.bulkClaimEscalations = bulkClaimEscalations;
 exports.bulkAssignEscalations = bulkAssignEscalations;
 exports.bulkEscalateToRole = bulkEscalateToRole;
 exports.bulkResolveForTriage = bulkResolveForTriage;
-const db_1 = require("../../lib/db");
-const sql_1 = require("./sql");
+const client_1 = require("./client");
+const map_1 = require("./map");
 /**
  * Bulk claim escalations for a user.
  * Items already claimed by another active user are skipped.
@@ -13,10 +13,8 @@ const sql_1 = require("./sql");
 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 };
+    const client = await (0, client_1.escalations)();
+    return client.claimMany({ ids, assignee: userId, durationMinutes });
 }
 /**
  * Bulk assign escalations to a specific user (admin action).
@@ -25,10 +23,13 @@ async function bulkClaimEscalations(ids, userId, durationMinutes = 30) {
 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 };
+    const client = await (0, client_1.escalations)();
+    const { claimed, skipped } = await client.claimMany({
+        ids,
+        assignee: targetUserId,
+        durationMinutes,
+    });
+    return { assigned: claimed, skipped };
 }
 /**
  * Bulk reassign escalations to a different role.
@@ -37,21 +38,21 @@ async function bulkAssignEscalations(ids, targetUserId, durationMinutes = 30) {
 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;
+    const client = await (0, client_1.escalations)();
+    return client.escalateManyToRole({ ids, targetRole });
 }
 /**
  * Bulk resolve escalations for AI triage.
- * Returns full records so the caller can start triage workflows.
+ * Returns full records so the caller can start triage workflows. No signal is
+ * delivered — the triage workflow takes over handling.
  */
 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 client = await (0, client_1.escalations)();
+    const resolved = await client.resolveMany({
+        ids,
+        resolverPayload: { _lt: { needsTriage: true, ...(hint ? { hint } : {}) } },
     });
-    const { rows } = await pool.query(sql_1.BULK_RESOLVE_FOR_TRIAGE, [resolverPayload, ids]);
-    return rows;
+    return (0, map_1.toEscalationRecords)(resolved);
 }

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

@@ -0,0 +1,22 @@
+/**
+ * The escalation client, with the `lt_escalations` compatibility view ensured
+ * exactly once per process. Every service function awaits this so the view is
+ * present before the first read/write in any context (app, route test, or the
+ * service-only test that runs `migrate()` without starting workers).
+ */
+export declare function escalations(): Promise<import("@hotmeshio/hotmesh/build/services/escalations").EscalationClientService>;
+/**
+ * Replace the legacy `lt_escalations` table with a view over
+ * `public.hmsh_escalations`. Idempotent and memoized per process.
+ *
+ * - Migrates any legacy rows into `hmsh_escalations` (no-op on a fresh DB), then
+ *   RENAMES the legacy table to `lt_escalations_legacy` (a recoverable backup —
+ *   never dropped here) so the view can take the `lt_escalations` name.
+ * - Read-path consumers (role, agent, mcp, overview) and frozen test cleanup
+ *   (`DELETE FROM lt_escalations`) continue to work unchanged against the view.
+ * - The one-time conversion is serialized across concurrent containers with a
+ *   dedicated Postgres advisory lock, so a multi-container deploy is safe.
+ *
+ * Safe to call eagerly at startup and lazily on first escalation use.
+ */
+export declare function ensureEscalationCompatView(): Promise<void>;

package/build/services/escalation/client.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escalations = escalations;
+exports.ensureEscalationCompatView = ensureEscalationCompatView;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const db_1 = require("../../lib/db");
+const logger_1 = require("../../lib/logger");
+// ---------------------------------------------------------------------------
+// Escalation client — long-tail's service layer talks to the shared
+// `public.hmsh_escalations` table exclusively through `client.escalations.*`
+// (HotMesh 0.22.3). The escalation client is created off a `Durable.Client`,
+// which injects `getHotMeshClient` so the escalation engine pool is shared
+// with the rest of the app and torn down by `Durable.shutdown()`.
+// ---------------------------------------------------------------------------
+let durableClient = null;
+/** The raw `client.escalations` surface over `public.hmsh_escalations`. */
+function rawEscalations() {
+    if (!durableClient) {
+        durableClient = new hotmesh_1.Durable.Client({ connection: (0, db_1.getConnection)() });
+    }
+    return durableClient.escalations;
+}
+/**
+ * The escalation client, with the `lt_escalations` compatibility view ensured
+ * exactly once per process. Every service function awaits this so the view is
+ * present before the first read/write in any context (app, route test, or the
+ * service-only test that runs `migrate()` without starting workers).
+ */
+async function escalations() {
+    await ensureEscalationCompatView();
+    return rawEscalations();
+}
+let viewReady = null;
+/**
+ * Replace the legacy `lt_escalations` table with a view over
+ * `public.hmsh_escalations`. Idempotent and memoized per process.
+ *
+ * - Migrates any legacy rows into `hmsh_escalations` (no-op on a fresh DB), then
+ *   RENAMES the legacy table to `lt_escalations_legacy` (a recoverable backup —
+ *   never dropped here) so the view can take the `lt_escalations` name.
+ * - Read-path consumers (role, agent, mcp, overview) and frozen test cleanup
+ *   (`DELETE FROM lt_escalations`) continue to work unchanged against the view.
+ * - The one-time conversion is serialized across concurrent containers with a
+ *   dedicated Postgres advisory lock, so a multi-container deploy is safe.
+ *
+ * Safe to call eagerly at startup and lazily on first escalation use.
+ */
+function ensureEscalationCompatView() {
+    if (!viewReady)
+        viewReady = installEscalationCompatView();
+    return viewReady;
+}
+// Dedicated advisory-lock id for the compat-view conversion. Distinct from
+// migrate()'s lock (8675309) because this step runs after HotMesh engine init,
+// outside the migrate() sequence.
+const COMPAT_VIEW_LOCK_ID = 8675310;
+async function installEscalationCompatView() {
+    // Force HotMesh engine init so `public.hmsh_escalations` exists before the
+    // view binds to it (kvtables are deployed on first engine use).
+    await rawEscalations().get('00000000-0000-0000-0000-000000000000');
+    // Serialize the conversion across concurrent containers on a dedicated
+    // connection. Only one process performs the migrate+rename; the rest acquire
+    // the lock afterward, see the view already in place, and no-op (the DO block
+    // is guarded and CREATE OR REPLACE VIEW is idempotent).
+    const pool = (0, db_1.getPool)();
+    const client = await pool.connect();
+    try {
+        await client.query('SELECT pg_advisory_lock($1)', [COMPAT_VIEW_LOCK_ID]);
+        await client.query(MIGRATE_AND_RENAME_LEGACY_TABLE);
+        await client.query(CREATE_COMPAT_VIEW);
+        logger_1.loggerRegistry.info('[escalation] lt_escalations compatibility view ensured');
+    }
+    finally {
+        await client.query('SELECT pg_advisory_unlock($1)', [COMPAT_VIEW_LOCK_ID]).catch(() => { });
+        client.release();
+    }
+}
+// Migrate legacy `lt_escalations` rows into `hmsh_escalations` (idempotent),
+// then preserve the original table as `lt_escalations_legacy` rather than
+// dropping it — the rows survive untouched for verification and rollback; a
+// later explicit migration can drop the backup once the cut is confirmed. Runs
+// only while `lt_escalations` is still a real table; once it is a view this
+// block is skipped. Payload/envelope TEXT columns are cast to JSONB defensively
+// so a malformed value can never abort the upgrade.
+const MIGRATE_AND_RENAME_LEGACY_TABLE = `
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.relname = 'lt_escalations' AND c.relkind = 'r' AND n.nspname = 'public'
+  ) THEN
+    CREATE OR REPLACE FUNCTION pg_temp.lt_try_jsonb(t text) RETURNS jsonb AS $fn$
+      BEGIN
+        IF t IS NULL OR t = '' THEN RETURN NULL; END IF;
+        RETURN t::jsonb;
+      EXCEPTION WHEN others THEN
+        RETURN to_jsonb(t);
+      END;
+    $fn$ LANGUAGE plpgsql IMMUTABLE;
+
+    INSERT INTO public.hmsh_escalations
+      (id, namespace, app_id, type, subtype, description, status, priority,
+       task_id, origin_id, parent_id, workflow_id, task_queue, workflow_type,
+       role, assigned_to, assigned_until, claim_expires_at, resolved_at, claimed_at,
+       created_by, envelope, metadata, escalation_payload, resolver_payload,
+       trace_id, span_id, created_at, updated_at)
+    SELECT
+      id, 'hmsh', 'hmsh', type, subtype, description, status, priority,
+      task_id::text, origin_id, parent_id, workflow_id, task_queue, workflow_type,
+      role, assigned_to, assigned_until, assigned_until, resolved_at, claimed_at,
+      created_by::text,
+      pg_temp.lt_try_jsonb(envelope),
+      metadata,
+      pg_temp.lt_try_jsonb(escalation_payload),
+      pg_temp.lt_try_jsonb(resolver_payload),
+      trace_id, span_id, created_at, updated_at
+    FROM public.lt_escalations
+    ON CONFLICT (id) DO NOTHING;
+
+    -- Preserve the originals as a recoverable backup (rows already migrated).
+    -- If a backup already exists from a prior conversion, the current table is
+    -- redundant and is dropped instead of clobbering the backup.
+    IF EXISTS (
+      SELECT 1 FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relname = 'lt_escalations_legacy' AND n.nspname = 'public'
+    ) THEN
+      DROP TABLE public.lt_escalations CASCADE;
+    ELSE
+      ALTER TABLE public.lt_escalations RENAME TO lt_escalations_legacy;
+    END IF;
+  END IF;
+END $$;`;
+// `available` mirrors the legacy isEffectivelyClaimed/isAvailable heuristic so
+// existing `SELECT *` consumers are unaffected; the column is additive.
+const CREATE_COMPAT_VIEW = `
+CREATE OR REPLACE VIEW public.lt_escalations AS
+  SELECT *,
+    (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()) AS available
+  FROM public.hmsh_escalations;`;

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

@@ -2,20 +2,39 @@ 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.
+ * Atomic claim. Implicit model — status stays 'pending'; "claimed" is
+ * assigned_to + assigned_until > NOW(). `isExtension` is true when the same
+ * user re-claims (extends expiry). Returns null when the row is not claimable.
  */
 export declare function claimEscalation(id: string, userId: string, durationMinutes?: number): Promise<ClaimResult | null>;
+/**
+ * Mark an escalation resolved. Signal delivery is owned by the resolution
+ * orchestrator (api/escalations/resolve.ts); service-created rows have no
+ * signal_key, so this never delivers a signal itself. Returns null when the
+ * row is missing or already terminal.
+ */
 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.
+ * Look up an efficient (atomic) escalation by its `signal_key` — the signal id
+ * passed to `conditionLT(signalId, config)` / `condition(signalId, config)`.
+ * Returns null when no row carries that key.
+ */
+export declare function getEscalationBySignalKey(signalKey: string): Promise<LTEscalationRecord | null>;
+/**
+ * Resolve an efficient (atomic) escalation by its `signal_key` and resume the
+ * waiting workflow in place. Convenience for webhook callers that know the
+ * deterministic signal id (e.g. `signal-scan-ar-${orderId}`) and want to skip
+ * the id lookup. Returns null when the key is unknown or already terminal.
+ *
+ * Race-free: `signal_key → id` is an immutable mapping, and the state mutation
+ * is delegated to `resolveEscalation`, whose `client.resolve` uses FOR UPDATE +
+ * `WHERE status = 'pending'` so exactly one concurrent caller commits. No status
+ * pre-check (that would be a TOCTOU window) — the atomic resolve is the arbiter.
+ */
+export declare function resolveEscalationBySignalKey(signalKey: string, resolverPayload: Record<string, any>): Promise<LTEscalationRecord | null>;
+/**
+ * Bulk update priority for a set of escalations. Only pending escalations are
+ * updated.
  */
 export declare function updateEscalationsPriority(ids: string[], priority: 1 | 2 | 3 | 4): Promise<number>;
 /**
@@ -28,6 +47,12 @@ export declare function getEscalationRoles(ids: string[]): Promise<string[]>;
  * Only the assigned user (or superadmin via route) may release.
  */
 export declare function releaseEscalation(id: string, userId: string): Promise<LTEscalationRecord | null>;
+/**
+ * Sweep expired claims back to the available pool, returning the count cleared.
+ * Availability is already query-time in the implicit model, but long-tail's
+ * public contract clears `assigned_to` and returns a count, so this runs as a
+ * single direct UPDATE on the shared table (the SDK's releaseExpired is a no-op).
+ */
 export declare function releaseExpiredClaims(): Promise<number>;
 /**
  * Reassign an escalation to a different role.
@@ -50,13 +75,12 @@ export declare function findByMetadata(key: string, value: string, status?: stri
     total: number;
 }>;
 /**
- * Atomic claim by metadata with inline RBAC.
- * The SQL WHERE clause enforces role membership — if the caller
- * doesn't have an allowed role, zero rows match and the claim
- * never happens. No pre-flight find, no TOCTOU.
+ * Atomic claim by metadata with inline RBAC and optional metadata merge.
+ * The SDK enforces the role filter in SQL — callers without an allowed role
+ * match zero rows. Returns `{ escalation, isExtension, candidatesExist }` or
+ * null when nothing was claimed.
  *
- * @param allowedRoles — roles the caller can claim (null = no filter / global access)
- * @returns `{ escalation, isExtension, candidatesExist }` or null
+ * @param allowedRoles — roles the caller can claim (null = no filter / global)
  */
 export declare function claimByMetadata(key: string, value: string, userId: string, durationMinutes?: number, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<(ClaimResult & {
     candidatesExist: number;
@@ -74,11 +98,13 @@ export interface ResolveByMetadataResult {
     taskQueue?: string;
 }
 /**
- * Atomic resolve by metadata with signal guard.
+ * Atomic resolve by metadata with signal guard, in a single CTE.
  *
- * Single query, two outcomes:
- * 1. No signal_id → claim + resolve atomically. Returns { outcome: 'resolved', escalation }.
- * 2. signal_id present → resolve skipped. Returns { outcome: 'signal_required', signalId, escalationId, ... }
- *    so the caller can signal the workflow. conditionLT handles the rest.
+ * Signal-backed rows (those carrying `metadata.signal_id`) are NOT resolved
+ * here — long-tail signals the paused workflow and the workflow interceptor
+ * resolves durably. If the workflow is gone the signal fails and the row stays
+ * pending, which is the contract the route suite pins. This guard is long-tail
+ * business logic over the shared table, so it runs as one atomic statement on
+ * `hmsh_escalations` rather than through the generic SDK resolve.
  */
 export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<ResolveByMetadataResult>;