@hotmeshio/long-tail 0.5.9 → 0.5.10

package/build/api/escalations/metadata.js

@@ -125,10 +125,26 @@ async function resolveByMetadata(input, auth) {
         if (result.outcome === 'not_found') {
             return { status: 404, error: 'No pending escalation found for this metadata, or insufficient role permissions' };
         }
+        if (result.outcome === 'conflict') {
+            return { status: 409, error: 'A concurrent resolution is already in progress for this escalation' };
+        }
         if (result.outcome === 'resolved') {
             return { status: 200, data: { escalation: result.escalation } };
         }
-        // Signal-backed escalation — signal the workflow, conditionLT resolves durably
+        // Atomic conditionLT escalation (signal_key set) — SDK resolve atomically marks
+        // resolved AND delivers the signal to the waiting condition(), resuming the workflow.
+        if (result.signalKey) {
+            const resolved = await escalationService.resolveEscalation(result.escalationId, input.resolverPayload);
+            if (!resolved) {
+                return { status: 409, error: 'Escalation not available for resolution' };
+            }
+            return {
+                status: 200,
+                data: { signaled: true, escalationId: result.escalationId, workflowId: result.workflowId },
+            };
+        }
+        // Legacy conditionLT escalation (metadata.signal_id set) — signal the workflow,
+        // conditionLT interceptor resolves durably via ltResolveEscalation.
         const { createClient } = await Promise.resolve().then(() => __importStar(require('../../workers')));
         const client = createClient();
         const handle = await client.workflow.getHandle(result.taskQueue, result.workflowType, result.workflowId);

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

@@ -103,12 +103,19 @@ export declare function claimByMetadata(key: string, value: string, userId: stri
     candidatesExist: number;
 }) | null>;
 export interface ResolveByMetadataResult {
-    /** 'resolved' = done atomically. 'signal_required' = signal_id present, caller must signal. */
-    outcome: 'resolved' | 'signal_required' | 'not_found';
+    /**
+     * 'resolved'        = done atomically in SQL (no signal backing).
+     * 'signal_required' = signal backing present, caller must deliver the signal.
+     * 'conflict'        = signal_id row already claimed by a concurrent caller; skip re-signal.
+     * 'not_found'       = no pending escalation matched the metadata filter.
+     */
+    outcome: 'resolved' | 'signal_required' | 'conflict' | 'not_found';
     /** The resolved escalation (when outcome = 'resolved') */
     escalation?: LTEscalationRecord;
-    /** Signal info (when outcome = 'signal_required') */
+    /** Legacy conditionLT signal info (when signalId is set, caller uses handle.signal) */
     signalId?: string;
+    /** Atomic conditionLT signal key (when signalKey is set, caller uses SDK resolve to atomically mark+signal) */
+    signalKey?: string;
     escalationId?: string;
     workflowId?: string;
     workflowType?: string;

package/build/services/escalation/crud.js

@@ -402,10 +402,15 @@ async function resolveByMetadataAtomic(key, value, userId, resolverPayload, meta
         });
         return { outcome: 'resolved', escalation };
     }
+    // Signal_id row already claimed by a concurrent caller — skip re-signal to prevent duplicate delivery.
+    if (row.signal_id && row.signal_already_claimed) {
+        return { outcome: 'conflict', escalationId: row.target_id };
+    }
     // Signal-backed escalation — return the signal info for the caller to deliver.
     return {
         outcome: 'signal_required',
-        signalId: row.signal_id,
+        signalId: row.signal_id ?? undefined,
+        signalKey: row.signal_key ?? undefined,
         escalationId: row.target_id,
         workflowId: row.target_workflow_id,
         workflowType: row.target_workflow_type,

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

@@ -11,13 +11,23 @@ export declare const RELEASE_EXPIRED_CLAIMS = "UPDATE public.hmsh_escalations\nS
 /**
  * Atomic resolve by metadata with signal guard.
  *
- * Single query, two outcomes:
- * 1. No `metadata.signal_id` → claim + resolve atomically. `resolved` is populated.
- * 2. `metadata.signal_id` present → resolve CTE skips (guard in WHERE). `resolved`
- *    is null, but `target_id`, `signal_id`, and workflow routing are returned so
- *    the caller can signal the workflow directly.
+ * Single query, four outcomes:
+ * 1. No signal backing → claim + resolve atomically. `resolved` is populated.
+ * 2. `metadata.signal_id` present, row unclaimed → claim the row (preventing concurrent
+ *    duplicate signals via FOR UPDATE serialization), then return signal info so the
+ *    caller can signal the workflow. `signal_already_claimed = false`.
+ * 3. `metadata.signal_id` present, row already claimed and claim not expired →
+ *    a concurrent caller is handling the signal. `signal_already_claimed = true`;
+ *    caller returns 409 without re-signaling.
+ * 4. `signal_key` present (atomic conditionLT) → `claimed` and `resolved` both skip.
+ *    Caller invokes SDK resolve to atomically mark resolved + deliver the signal.
+ *
+ * Signal_id hardening: the `claimed` CTE runs for signal_id rows (previously excluded).
+ * This stamps `assigned_to` on the row inside the FOR UPDATE transaction, so a
+ * concurrent second caller sees `signal_already_claimed = true` and aborts.
+ * The `resolved` CTE still skips signal_id rows — the workflow resolves durably.
  *
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
-export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND (target.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE public.hmsh_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";
+export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND target.signal_key IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE public.hmsh_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n    AND (claimed.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.signal_key AS signal_key,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  (target.assigned_to IS NOT NULL\n    AND target.assigned_until IS NOT NULL\n    AND target.assigned_until > NOW()) AS signal_already_claimed,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";

package/build/services/escalation/sql.js

@@ -34,11 +34,21 @@ WHERE status = 'pending'
 /**
  * Atomic resolve by metadata with signal guard.
  *
- * Single query, two outcomes:
- * 1. No `metadata.signal_id` → claim + resolve atomically. `resolved` is populated.
- * 2. `metadata.signal_id` present → resolve CTE skips (guard in WHERE). `resolved`
- *    is null, but `target_id`, `signal_id`, and workflow routing are returned so
- *    the caller can signal the workflow directly.
+ * Single query, four outcomes:
+ * 1. No signal backing → claim + resolve atomically. `resolved` is populated.
+ * 2. `metadata.signal_id` present, row unclaimed → claim the row (preventing concurrent
+ *    duplicate signals via FOR UPDATE serialization), then return signal info so the
+ *    caller can signal the workflow. `signal_already_claimed = false`.
+ * 3. `metadata.signal_id` present, row already claimed and claim not expired →
+ *    a concurrent caller is handling the signal. `signal_already_claimed = true`;
+ *    caller returns 409 without re-signaling.
+ * 4. `signal_key` present (atomic conditionLT) → `claimed` and `resolved` both skip.
+ *    Caller invokes SDK resolve to atomically mark resolved + deliver the signal.
+ *
+ * Signal_id hardening: the `claimed` CTE runs for signal_id rows (previously excluded).
+ * This stamps `assigned_to` on the row inside the FOR UPDATE transaction, so a
+ * concurrent second caller sees `signal_already_claimed = true` and aborts.
+ * The `resolved` CTE still skips signal_id rows — the workflow resolves durably.
  *
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
@@ -70,7 +80,7 @@ claimed AS (
       updated_at = NOW()
   FROM target
   WHERE e.id = target.id
-    AND (target.metadata->>'signal_id') IS NULL
+    AND target.signal_key IS NULL
   RETURNING e.*
 ),
 resolved AS (
@@ -81,15 +91,20 @@ resolved AS (
       updated_at = NOW()
   FROM claimed
   WHERE e.id = claimed.id
+    AND (claimed.metadata->>'signal_id') IS NULL
   RETURNING e.*
 )
 SELECT
   resolved.*,
   target.id AS target_id,
   target.metadata->>'signal_id' AS signal_id,
+  target.signal_key AS signal_key,
   target.workflow_id AS target_workflow_id,
   target.workflow_type AS target_workflow_type,
   target.task_queue AS target_task_queue,
+  (target.assigned_to IS NOT NULL
+    AND target.assigned_until IS NOT NULL
+    AND target.assigned_until > NOW()) AS signal_already_claimed,
   CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome
 FROM target
 LEFT JOIN resolved ON resolved.id = target.id`;

package/docs/hitl-guide.md

@@ -594,6 +594,54 @@ metadata: {
 
 ---
 
+## Resolving from System Code
+
+When a backend service (not the dashboard UI) needs to resolve an escalation — for example, an ingress handler that receives a webhook or processes a domain event — use the escalation SDK methods directly.
+
+### By escalation ID
+
+Use when you already have the escalation UUID (e.g. stored in your own DB alongside the order):
+
+```typescript
+const result = await lt.escalations.resolve({
+  id: escalationId,
+  resolverPayload: { approved: true, targetStatus: 'ready' },
+});
+```
+
+This routes through the full resolution path and works for all escalation types — atomic `conditionLT` (signal_key), legacy `conditionLT` (signal_id), and re-run-style escalations.
+
+### By metadata key-value pair
+
+Use when you know a domain identifier (e.g. `orderId`) but not the escalation UUID. `resolveByMetadata` finds the highest-priority pending escalation matching the key-value pair and resolves it atomically — no pre-flight lookup, no TOCTOU:
+
+```typescript
+const result = await lt.escalations.resolveByMetadata({
+  key: 'orderId',
+  value: orderId,
+  resolverPayload: { approved: true, targetStatus: 'ready' },
+});
+
+if (result.status === 404) {
+  // No pending escalation for this orderId
+}
+```
+
+This works for all escalation types including atomic `conditionLT` rows (those with `signal_key` set). The routing is transparent — the caller does not need to know which pattern the workflow used.
+
+### By signal key
+
+When the signal key is deterministic and known to the caller (e.g. `station-done-${workflowId}`), use the direct signal-key path to skip the metadata lookup:
+
+```typescript
+await lt.escalations.resolveBySignalKey({
+  signalKey: `station-done-${workflowId}`,
+  resolverPayload: { approved: true },
+});
+```
+
+---
+
 ## Cancelling Escalations
 
 Escalations can be cancelled at any point before they are resolved. Cancellation is terminal — a cancelled escalation cannot be re-opened.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",