@hotmeshio/long-tail 0.5.3 → 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/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/crud.d.ts

@@ -14,6 +14,24 @@ export declare function claimEscalation(id: string, userId: string, durationMinu
  * row is missing or already terminal.
  */
 export declare function resolveEscalation(id: string, resolverPayload: Record<string, any>): Promise<LTEscalationRecord | null>;
+/**
+ * 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.

package/build/services/escalation/crud.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEscalation = createEscalation;
 exports.claimEscalation = claimEscalation;
 exports.resolveEscalation = resolveEscalation;
+exports.getEscalationBySignalKey = getEscalationBySignalKey;
+exports.resolveEscalationBySignalKey = resolveEscalationBySignalKey;
 exports.updateEscalationsPriority = updateEscalationsPriority;
 exports.getEscalationRoles = getEscalationRoles;
 exports.releaseEscalation = releaseEscalation;
@@ -109,6 +111,33 @@ async function resolveEscalation(id, resolverPayload) {
     });
     return escalation;
 }
+/**
+ * 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.
+ */
+async function getEscalationBySignalKey(signalKey) {
+    const client = await (0, client_1.escalations)();
+    const entry = await client.getBySignalKey(signalKey);
+    return entry ? (0, map_1.toEscalationRecord)(entry) : 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.
+ */
+async function resolveEscalationBySignalKey(signalKey, resolverPayload) {
+    const escalation = await getEscalationBySignalKey(signalKey);
+    if (!escalation)
+        return null;
+    return resolveEscalation(escalation.id, resolverPayload);
+}
 /**
  * Bulk update priority for a set of escalations. Only pending escalations are
  * updated.

package/build/services/escalation/map.js

@@ -23,6 +23,7 @@ function toEscalationRecord(entry) {
         workflow_id: entry.workflow_id,
         task_queue: entry.task_queue,
         workflow_type: entry.workflow_type,
+        signal_key: entry.signal_key,
         role: entry.role ?? '',
         assigned_to: entry.assigned_to,
         assigned_until: entry.assigned_until,

package/build/services/orchestrator/condition.d.ts

@@ -1,34 +1,39 @@
+import type { Types } from '@hotmeshio/hotmesh';
 /**
  * Wait for a signal and resolve the associated escalation automatically.
  *
- * Wraps `Durable.workflow.condition()` with escalation lifecycle:
- * when the signal arrives (from the dashboard resolve endpoint),
- * the payload includes an injected `$escalation_id` field. This
- * helper strips it, calls `ltResolveEscalation` as a durable
- * activity, and returns the clean resolver payload.
+ * Two ways to call it:
+ *
+ * **Efficient (atomic) — pass an escalation config.** The escalation row is
+ * written inside this workflow's Leg1 checkpoint (one commit, crash-safe — no
+ * separate create activity, no enrich). `signal_key` is the signal id, so the
+ * dashboard resolve endpoint (Path 0), `resolveEscalationBySignalKey`, and any
+ * webhook resume the SAME job in place. `system.escalation.{id}.created` fires
+ * from the engine automatically.
  *
- * Usage (from within a workflow):
  * ```typescript
- * import { conditionLT } from '@hotmeshio/long-tail';
+ * const decision = await conditionLT<{ approved: boolean }>(signalId, {
+ *   role: 'reviewer',
+ *   type: 'orderPipeline',
+ *   subtype: stationName,
+ *   priority: 2,
+ *   description: instructions,
+ *   metadata: { orderId, station: stationName },
+ *   envelope: { instructions },
+ * });
+ * ```
  *
- * export async function myWorkflow(envelope: LTEnvelope) {
- *   // Create an escalation with signal_id in metadata
- *   const signalId = `approval-${Durable.workflow.workflowId}`;
- *   await activities.ltCreateEscalation({
- *     type: 'approval',
- *     role: 'reviewer',
- *     metadata: { signal_id: signalId },
- *     // ...
- *   });
+ * **Legacy (two-step) — no config.** Create the escalation first (e.g. via
+ * `ltCreateEscalation`) with `signal_id`/`signal_routing` metadata, then wait.
+ * On resume the signal payload carries an injected `$escalation_id`; this helper
+ * strips it, resolves the escalation as a durable activity, and returns the
+ * clean resolver payload. If no `$escalation_id` is present (efficient path, or
+ * a manual signal), the payload is returned as-is — the escalation was already
+ * resolved server-side.
  *
- *   // Wait — the dashboard signals on resolve
- *   const decision = await conditionLT<{ approved: boolean }>(signalId);
- *   // decision.approved is clean — no $escalation_id
- * }
+ * ```typescript
+ * await activities.ltCreateEscalation({ type: 'approval', role: 'reviewer', metadata: { signal_id: signalId } });
+ * const decision = await conditionLT<{ approved: boolean }>(signalId);
  * ```
- *
- * If the signal payload does not contain `$escalation_id` (e.g., signaled
- * manually), the function returns the payload as-is without calling
- * the resolve activity.
  */
-export declare function conditionLT<T = Record<string, any>>(signalId: string): Promise<T>;
+export declare function conditionLT<T = Record<string, any>>(signalId: string, escalation?: Types.ConditionQueueConfig): Promise<T>;

package/build/services/orchestrator/condition.js

@@ -40,38 +40,42 @@ const LT_ACTIVITY_QUEUE = 'lt-interceptor';
 /**
  * Wait for a signal and resolve the associated escalation automatically.
  *
- * Wraps `Durable.workflow.condition()` with escalation lifecycle:
- * when the signal arrives (from the dashboard resolve endpoint),
- * the payload includes an injected `$escalation_id` field. This
- * helper strips it, calls `ltResolveEscalation` as a durable
- * activity, and returns the clean resolver payload.
+ * Two ways to call it:
+ *
+ * **Efficient (atomic) — pass an escalation config.** The escalation row is
+ * written inside this workflow's Leg1 checkpoint (one commit, crash-safe — no
+ * separate create activity, no enrich). `signal_key` is the signal id, so the
+ * dashboard resolve endpoint (Path 0), `resolveEscalationBySignalKey`, and any
+ * webhook resume the SAME job in place. `system.escalation.{id}.created` fires
+ * from the engine automatically.
  *
- * Usage (from within a workflow):
  * ```typescript
- * import { conditionLT } from '@hotmeshio/long-tail';
+ * const decision = await conditionLT<{ approved: boolean }>(signalId, {
+ *   role: 'reviewer',
+ *   type: 'orderPipeline',
+ *   subtype: stationName,
+ *   priority: 2,
+ *   description: instructions,
+ *   metadata: { orderId, station: stationName },
+ *   envelope: { instructions },
+ * });
+ * ```
  *
- * export async function myWorkflow(envelope: LTEnvelope) {
- *   // Create an escalation with signal_id in metadata
- *   const signalId = `approval-${Durable.workflow.workflowId}`;
- *   await activities.ltCreateEscalation({
- *     type: 'approval',
- *     role: 'reviewer',
- *     metadata: { signal_id: signalId },
- *     // ...
- *   });
+ * **Legacy (two-step) — no config.** Create the escalation first (e.g. via
+ * `ltCreateEscalation`) with `signal_id`/`signal_routing` metadata, then wait.
+ * On resume the signal payload carries an injected `$escalation_id`; this helper
+ * strips it, resolves the escalation as a durable activity, and returns the
+ * clean resolver payload. If no `$escalation_id` is present (efficient path, or
+ * a manual signal), the payload is returned as-is — the escalation was already
+ * resolved server-side.
  *
- *   // Wait — the dashboard signals on resolve
- *   const decision = await conditionLT<{ approved: boolean }>(signalId);
- *   // decision.approved is clean — no $escalation_id
- * }
+ * ```typescript
+ * await activities.ltCreateEscalation({ type: 'approval', role: 'reviewer', metadata: { signal_id: signalId } });
+ * const decision = await conditionLT<{ approved: boolean }>(signalId);
  * ```
- *
- * If the signal payload does not contain `$escalation_id` (e.g., signaled
- * manually), the function returns the payload as-is without calling
- * the resolve activity.
  */
-async function conditionLT(signalId) {
-    const raw = await hotmesh_1.Durable.workflow.condition(signalId);
+async function conditionLT(signalId, escalation) {
+    const raw = await hotmesh_1.Durable.workflow.condition(signalId, escalation);
     const escalationId = raw.$escalation_id;
     if (escalationId) {
         // Resolve the escalation as a durable activity (crash-safe)

package/build/types/escalation.d.ts

@@ -13,6 +13,7 @@ export interface LTEscalationRecord {
     workflow_id: string | null;
     task_queue: string | null;
     workflow_type: string | null;
+    signal_key: string | null;
     role: string;
     assigned_to: string | null;
     assigned_until: Date | null;

package/docs/api/http/escalations.md

@@ -215,8 +215,27 @@ The workflow is responsible for resolving the escalation. The `conditionLT()` he
 
 If you use raw `Durable.workflow.condition()` instead, you must resolve the escalation yourself using the `$escalation_id` from the signal data.
 
+### Signal-key resolution (efficient/atomic — `signal_key`)
+
+When an escalation was written atomically by `conditionLT(signalId, config)` (or `Durable.workflow.condition(signalId, config)`), the row carries a `signal_key` and no `signal_id`/`signal_routing` metadata. The resolve endpoint detects `signal_key` and resolves it through the SDK: the resolve marks the row resolved **and** delivers the signal to the waiting `condition()` in one transaction, so the original job resumes in place — no re-run, no separate resolve activity. `system.escalation.{id}.resolved` fires.
+
+```
+POST /api/escalations/resolve-by-signal-key
+```
+
+For callers that know the deterministic signal id (webhooks — e.g. `signal-scan-ar-${orderId}`) and want to skip the id lookup.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `signalKey` | `string` | yes | The signal id passed to `conditionLT(signalId, config)` |
+| `resolverPayload` | `object` | yes | The decision payload delivered to the waiting workflow |
+
+Returns `404` when the key is unknown, `409` when the escalation is already terminal, and `200 { signaled: true }` on success. RBAC-scoped to the caller's visible roles.
+
 ### What happens during resolution
 
+> Applies to the **re-run** path (an escalation with no `signal_id`, `signal_routing`, or `signal_key`). Signal-based and signal-key escalations resume the live workflow in place, as described above.
+
 1. The route reads the escalation record and verifies it is still `pending`.
 2. It reconstructs the original workflow envelope from the escalation's `envelope` field (or from the parent task if the escalation envelope is missing).
 3. It injects `resolver` (the reviewer's payload) and `lt.escalationId` into the envelope.

package/docs/api/sdk/escalations.md

@@ -279,6 +279,39 @@ const result = await lt.escalations.resolve({
 
 Wait for a signal and automatically resolve the associated escalation. This is the counterpart to `executeLT` — where `executeLT` wraps `startChild` + `condition`, `conditionLT` wraps `condition` + escalation resolution.
 
+```typescript
+conditionLT<T>(signalId: string, escalation?: ConditionQueueConfig): Promise<T>
+```
+
+### Atomic form (recommended)
+
+Pass an escalation config as the second argument. The escalation row is written inside the workflow's Leg1 checkpoint — one commit, crash-safe: no separate `ltCreateEscalation` activity, no enrich step. `signal_key` is set to `signalId`, so the dashboard resolve endpoint (resolve-by-id → Path 0) and `POST /escalations/resolve-by-signal-key` resume *this* job in place, and `system.escalation.{id}.created` fires automatically.
+
+```typescript
+import { conditionLT } from '@hotmeshio/long-tail';
+
+export async function stationWorker(envelope: LTEnvelope) {
+  const ctx = Durable.workflow.workflowInfo();
+  const signalId = `station-done-${ctx.workflowId}`;
+
+  const decision = await conditionLT<{ approved: boolean }>(signalId, {
+    role: 'qc-inspector',
+    type: 'orderPipeline',
+    subtype: 'qc',
+    priority: 2,
+    description: 'Inspect the order and approve',
+    workflowType: 'stationWorker',
+    metadata: { orderId: envelope.data.orderId, station: 'qc' },
+    envelope: { instructions: 'Review and approve or reject' },
+  });
+  // decision is clean — the escalation was resolved by the resolve endpoint
+}
+```
+
+### Two-step form
+
+Create the escalation first (e.g. to enrich routing metadata), then wait:
+
 ```typescript
 import { conditionLT } from '@hotmeshio/long-tail';
 

package/docs/hitl-guide.md

@@ -31,7 +31,50 @@ Durable Workflow                  Long-tail Platform              Dashboard
 
 ### Pattern 1: `conditionLT` Signal (Recommended)
 
-The workflow stays running and waits for a signal. Lightweight, no re-run needed.
+The workflow stays running and waits for a signal. Lightweight, no re-run needed. Two forms — prefer the atomic one.
+
+#### Atomic form (recommended)
+
+Pass an escalation config to `conditionLT`. The escalation row is written inside the workflow's Leg1 checkpoint — one commit, crash-safe: no separate create activity, no enrich step. `signal_key` is the resume key, so the dashboard resolve endpoint and `POST /escalations/resolve-by-signal-key` both resume *this* job in place, and `system.escalation.{id}.created` fires automatically.
+
+```typescript
+import { conditionLT } from '@hotmeshio/long-tail';
+
+export async function approvalWorkflow(envelope: LTEnvelope) {
+  const ctx = Durable.workflow.workflowInfo();
+  const signalId = `approval-${ctx.workflowId}`;
+
+  // One atomic expression: write the escalation in Leg1, then pause.
+  const decision = await conditionLT<{ approved: boolean; notes?: string }>(signalId, {
+    role: 'finance-reviewer',
+    type: 'approval',
+    subtype: 'budget-request',
+    priority: 2,
+    description: `Budget approval needed: $${envelope.data.amount}`,
+    metadata: {
+      form_schema: {
+        title: 'Budget Approval',
+        properties: {
+          approved: { type: 'boolean', description: 'Approve this request?' },
+          notes: { type: 'string', format: 'textarea' },
+        },
+        required: ['approved'],
+      },
+    },
+    envelope: { data: envelope.data },
+  });
+
+  if (decision.approved) {
+    // ... proceed with approved flow ...
+  } else {
+    // ... handle rejection ...
+  }
+}
+```
+
+#### Two-step form
+
+When you need to create the escalation separately — for example to enrich routing metadata before pausing — create it first, then wait:
 
 ```typescript
 import { conditionLT } from 'long-tail/orchestrator';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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",