@hotmeshio/hotmesh 0.21.0 → 0.22.0

package/build/services/durable/client.js

@@ -285,154 +285,338 @@ class ClientService {
             },
         };
         /**
-         * Signal queue API for managing paused-workflow task records.
-         * Operations: list, get, claim, claimByMetadata, release, resolve,
-         * resolveByMetadata, releaseExpired.
+         * Escalation queue operations over `public.hmsh_escalations` — a global
+         * table that surfaces workflow signal pauses as role-based, claimable,
+         * searchable queue items.
          *
-         * Requires a Postgres store provider. Methods are no-ops (return null/false)
-         * when called against a non-Postgres store.
+         * When a YAML `hook` activity suspends with an `escalation:` block, or
+         * `Durable.workflow.condition(signalId, config)` fires, **one row is
+         * written atomically** with the workflow checkpoint — no enrichment step,
+         * no secondary round-trip. Every connected app shares the same table;
+         * rows are namespaced by `namespace` + `app_id`.
          *
-         * @example
+         * **Status lifecycle:**
+         * ```
+         * pending → claimed → resolved
+         *         ↘ cancelled      (any non-terminal state)
+         *         ↗ pending        (via release or releaseExpired)
+         * ```
+         *
+         * **Typical human-in-the-loop flow:**
          * ```typescript
-         * // Claim a pending task by metadata key
-         * const task = await client.signalQueue.claimByMetadata({
-         *   key: 'orderId', value: 'RX-123',
-         *   assignee: 'pharmacist-jane',
-         *   durationMinutes: 30,
+         * // 1. Workflow pauses and writes the escalation row automatically
+         * const decision = await Durable.workflow.condition('manager-approval', {
+         *   role: 'manager',
+         *   type: 'order-approval',
+         *   priority: 2,
+         *   metadata: { orderId },
          * });
          *
-         * if (task) {
-         *   await client.signalQueue.resolve({
-         *     id: task.id,
-         *     resolverPayload: { approved: true },
-         *   });
-         *   // → paused workflow resumes with { approved: true }
-         * }
+         * // 2. Dashboard lists pending approvals for this role
+         * const [item] = await client.escalations.list({ role: 'manager', status: 'pending' });
+         *
+         * // 3. Reviewer claims it (sets assigned_to + expiry)
+         * await client.escalations.claim({ id: item.id, assignee: 'alice@company.com' });
+         *
+         * // 4. Resolve atomically marks it resolved AND delivers the signal
+         * await client.escalations.resolve({
+         *   id: item.id,
+         *   resolverPayload: { approved: true },
+         * });
+         * // workflow resumes with { approved: true }
          * ```
          */
-        this.signalQueue = {
-            list: async (params = {}) => {
-                const hotMesh = await this.getHotMeshClient(null, params.namespace);
-                const store = hotMesh.engine.store;
-                if (typeof store.listSignals !== 'function')
-                    return [];
-                const ns = params.namespace ?? factory_1.APP_ID;
-                return store.listSignals({
-                    namespace: ns,
-                    appId: store.appId,
-                    status: params.status,
-                    role: params.role,
-                    taskQueue: params.taskQueue,
-                    limit: params.limit,
-                    offset: params.offset,
-                });
+        this.escalations = {
+            /**
+             * Returns all escalation rows matching the given filters.
+             *
+             * @example
+             * ```typescript
+             * // All pending approvals for the manager role
+             * const items = await client.escalations.list({ role: 'manager', status: 'pending' });
+             *
+             * // By workflow ID
+             * const items = await client.escalations.list({ workflowId: 'order-123' });
+             * ```
+             */
+            list: async (params) => {
+                const hotMeshClient = await this.getHotMeshClient(null, params?.namespace);
+                return hotMeshClient.engine.store.listEscalations(params ?? {});
             },
+            /**
+             * Returns a single escalation row by its UUID primary key.
+             * Returns `null` if not found.
+             */
             get: async (id, namespace) => {
-                const hotMesh = await this.getHotMeshClient(null, namespace);
-                const store = hotMesh.engine.store;
-                if (typeof store.getSignal !== 'function')
-                    return null;
-                const ns = namespace ?? factory_1.APP_ID;
-                return store.getSignal({ namespace: ns, appId: store.appId, id });
+                const hotMeshClient = await this.getHotMeshClient(null, namespace);
+                return hotMeshClient.engine.store.getEscalation(id, namespace);
+            },
+            /**
+             * Looks up an escalation row by its `signal_key` — the value that was
+             * passed to `condition()` or stored in the hook activity's collation rule.
+             * This is the same key used to deliver the signal via `hotMesh.signal()`.
+             *
+             * @example
+             * ```typescript
+             * const item = await client.escalations.getBySignalKey('manager-approval');
+             * ```
+             */
+            getBySignalKey: async (signalKey, namespace) => {
+                const hotMeshClient = await this.getHotMeshClient(null, namespace);
+                return hotMeshClient.engine.store.getEscalationBySignalKey(signalKey, namespace);
+            },
+            /**
+             * Creates a standalone escalation row that is **not** backed by a signal.
+             * `signal_key` is `null`. Useful for external task tracking that doesn't
+             * need to resume a workflow (e.g., audit tasks, out-of-band approvals).
+             *
+             * @example
+             * ```typescript
+             * const entry = await client.escalations.create({
+             *   role: 'support',
+             *   type: 'data-correction',
+             *   description: 'Fix the customer address',
+             *   metadata: { customerId: 'cust-42' },
+             * });
+             * ```
+             */
+            create: async (params) => {
+                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
+                return hotMeshClient.engine.store.createEscalation(params);
+            },
+            /**
+             * Patches an existing escalation row. All fields are optional — only
+             * provided fields are written. `metadata` is **merged**, not replaced.
+             *
+             * Signal routing fields (`signalKey`, `topic`, `workflowId`, …) can be
+             * enriched after the row is created — useful when the row is created
+             * before the workflow starts and routing context is not yet known.
+             *
+             * @example
+             * ```typescript
+             * await client.escalations.update({
+             *   id: item.id,
+             *   description: 'Updated description',
+             *   metadata: { extraKey: 'value' },  // merged into existing metadata
+             * });
+             * ```
+             */
+            update: async (params) => {
+                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
+                return hotMeshClient.engine.store.updateEscalation(params);
             },
+            /**
+             * Appends one or more milestone entries to the escalation's
+             * `milestones` audit trail array. Milestones are append-only; they
+             * record events like state transitions, reviewer notes, or external
+             * system callbacks.
+             *
+             * @example
+             * ```typescript
+             * await client.escalations.appendMilestones({
+             *   id: item.id,
+             *   milestones: [{ at: new Date().toISOString(), by: 'alice', note: 'Reviewed' }],
+             * });
+             * ```
+             */
+            appendMilestones: async (params) => {
+                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
+                return hotMeshClient.engine.store.appendEscalationMilestones(params);
+            },
+            /**
+             * Atomically claims an escalation row by UUID. Sets `assigned_to`,
+             * `claimed_at`, and `claim_expires_at`. Returns `conflict` if another
+             * actor already holds the claim.
+             *
+             * @example
+             * ```typescript
+             * const result = await client.escalations.claim({
+             *   id: item.id,
+             *   assignee: 'alice@company.com',
+             *   durationMinutes: 30,
+             * });
+             * if (!result.ok) console.warn('Already claimed by someone else');
+             * ```
+             */
             claim: async (params) => {
-                const hotMesh = await this.getHotMeshClient(null, params.namespace);
-                const store = hotMesh.engine.store;
-                if (typeof store.claimSignal !== 'function') {
-                    return { ok: false, reason: 'not-found' };
-                }
-                const ns = params.namespace ?? factory_1.APP_ID;
-                return store.claimSignal({
-                    namespace: ns,
-                    appId: store.appId,
-                    id: params.id,
-                    assignee: params.assignee,
-                    durationMinutes: params.durationMinutes,
-                });
+                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
+                return hotMeshClient.engine.store.claimEscalation(params);
             },
+            /**
+             * Atomically claims the highest-priority pending escalation whose
+             * `metadata` contains the given key/value pair. Uses
+             * `FOR UPDATE SKIP LOCKED` so concurrent callers never double-claim.
+             *
+             * Returns `candidatesExist` to distinguish two cases:
+             * - `not-found, candidatesExist: 0` — no rows matched the metadata filter
+             * - `conflict, candidatesExist: N` — matching rows exist but all are claimed
+             *
+             * @example
+             * ```typescript
+             * const result = await client.escalations.claimByMetadata({
+             *   key: 'region',
+             *   value: 'west',
+             *   assignee: 'bob@company.com',
+             *   roles: ['manager'],
+             * });
+             * if (result.ok) console.log('Claimed:', result.entry.id);
+             * ```
+             */
             claimByMetadata: async (params) => {
-                const hotMesh = await this.getHotMeshClient(null, params.namespace);
-                const store = hotMesh.engine.store;
-                if (typeof store.claimSignalByMetadata !== 'function') {
-                    return { ok: false, reason: 'not-found' };
-                }
-                const ns = params.namespace ?? factory_1.APP_ID;
-                return store.claimSignalByMetadata({
-                    namespace: ns,
-                    appId: store.appId,
-                    key: params.key,
-                    value: params.value,
-                    assignee: params.assignee,
-                    durationMinutes: params.durationMinutes,
-                });
+                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
+                return hotMeshClient.engine.store.claimEscalationByMetadata(params);
             },
+            /**
+             * Releases a claimed escalation, returning it to `pending` status and
+             * clearing `assigned_to` and `claim_expires_at`. The row is immediately
+             * available for other actors to claim.
+             *
+             * @example
+             * ```typescript
+             * await client.escalations.release({ id: item.id });
+             * ```
+             */
             release: async (params) => {
-                const hotMesh = await this.getHotMeshClient(null, params.namespace);
-                const store = hotMesh.engine.store;
-                if (typeof store.releaseSignal !== 'function') {
-                    return { ok: false, reason: 'not-found' };
-                }
-                const ns = params.namespace ?? factory_1.APP_ID;
-                return store.releaseSignal({
-                    namespace: ns,
-                    appId: store.appId,
-                    id: params.id,
-                });
+                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
+                return hotMeshClient.engine.store.releaseEscalation(params);
+            },
+            /**
+             * Reassigns the escalation to a different role, clearing any current
+             * claim and returning status to `pending`. Use when an escalation must
+             * be handled by a different team or tier.
+             *
+             * @example
+             * ```typescript
+             * await client.escalations.escalateToRole({ id: item.id, role: 'senior-manager' });
+             * ```
+             */
+            escalateToRole: async (params) => {
+                const hotMeshClient = await this.getHotMeshClient(null, params.namespace);
+                return hotMeshClient.engine.store.escalateEscalationToRole(params);
+            },
+            /**
+             * Terminates the escalation without delivering a signal. Rows in
+             * `pending` or `claimed` state move to `cancelled`. Terminal rows
+             * (`resolved`, `cancelled`) return `already-terminal`.
+             *
+             * @example
+             * ```typescript
+             * await client.escalations.cancel(item.id);
+             * ```
+             */
+            cancel: async (id, namespace) => {
+                const hotMeshClient = await this.getHotMeshClient(null, namespace);
+                return hotMeshClient.engine.store.cancelEscalation(id, namespace);
             },
-            resolve: async (params) => {
-                const hotMesh = await this.getHotMeshClient(null, params.namespace);
-                const store = hotMesh.engine.store;
-                if (typeof store.resolveSignal !== 'function') {
+            /**
+             * Atomically marks the escalation `resolved` **and** delivers the
+             * signal to the waiting workflow — one round-trip, no separate
+             * `signal()` call required. If `signal_key` is null (standalone
+             * escalation), only the row is updated.
+             *
+             * @example
+             * ```typescript
+             * const result = await client.escalations.resolve({
+             *   id: item.id,
+             *   resolverPayload: { approved: true, note: 'LGTM' },
+             * });
+             * if (!result.ok) console.error(result.reason); // 'not-found' | 'already-resolved' | 'signal-failed'
+             * // workflow resumes with { approved: true, note: 'LGTM' }
+             * ```
+             */
+            resolve: async (params, namespace) => {
+                const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
+                const hotMeshClient = await this.getHotMeshClient(null, ns);
+                const store = hotMeshClient.engine.store;
+                // UUID primary-key lookup — no namespace filter needed; use existing.namespace for the UPDATE.
+                const existing = await store.getEscalation(params.id);
+                if (!existing)
                     return { ok: false, reason: 'not-found' };
+                if (existing.status === 'resolved')
+                    return { ok: false, reason: 'already-resolved' };
+                if (existing.status === 'cancelled')
+                    return { ok: false, reason: 'already-cancelled' };
+                // Build a single atomic transaction: signal stream INSERTs + escalation UPDATE in one BEGIN/COMMIT.
+                // engine.signal() with a transaction queues an INSERT into the stream table without executing;
+                // queueResolveEscalation() queues the status UPDATE; txn.exec() commits all in one round-trip.
+                const txn = store.transact();
+                if (existing.signal_key && existing.topic) {
+                    const signalPayload = { id: existing.signal_key, data: params.resolverPayload ?? {} };
+                    try {
+                        const sc = await this.getHotMeshClient(`${ns}.wfs.signal`, ns);
+                        await sc.engine.signal(`${ns}.wfs.signal`, signalPayload, types_1.StreamStatus.SUCCESS, 200, txn);
+                    }
+                    catch { /* no collator hook rule — skip */ }
+                    try {
+                        const wc = await this.getHotMeshClient(`${ns}.wfs.wait`, ns);
+                        await wc.engine.signal(`${ns}.wfs.wait`, signalPayload, types_1.StreamStatus.SUCCESS, 200, txn);
+                    }
+                    catch { /* no waiter hook rule — skip */ }
                 }
-                const ns = params.namespace ?? factory_1.APP_ID;
-                const storeResult = await store.resolveSignal({
-                    namespace: ns,
-                    appId: store.appId,
-                    id: params.id,
-                    resolverPayload: params.resolverPayload,
-                });
-                if (!storeResult.ok)
-                    return storeResult;
-                try {
-                    await this.workflow.signal(storeResult.signalKey, params.resolverPayload ?? {}, params.namespace);
-                    return { ok: true };
-                }
-                catch {
-                    return { ok: false, reason: 'signal-failed', signalKey: storeResult.signalKey };
-                }
+                store.queueResolveEscalation({ id: params.id, namespace: existing.namespace ?? ns, resolverPayload: params.resolverPayload }, txn);
+                await txn.exec();
+                return { ok: true };
             },
-            resolveByMetadata: async (params) => {
-                const hotMesh = await this.getHotMeshClient(null, params.namespace);
-                const store = hotMesh.engine.store;
-                if (typeof store.resolveSignalByMetadata !== 'function') {
+            /**
+             * Resolves the highest-priority matching escalation by metadata filter,
+             * then delivers its signal. Identical semantics to `resolve()` but
+             * selects the target row by metadata key/value instead of UUID.
+             *
+             * @example
+             * ```typescript
+             * await client.escalations.resolveByMetadata({
+             *   key: 'orderId',
+             *   value: 'order-123',
+             *   resolverPayload: { approved: true },
+             * });
+             * ```
+             */
+            resolveByMetadata: async (params, namespace) => {
+                const ns = (params.namespace ?? namespace) ?? factory_1.APP_ID;
+                const hotMeshClient = await this.getHotMeshClient(null, ns);
+                const store = hotMeshClient.engine.store;
+                // Metadata lookup: filter by namespace to scope correctly, but use existing.namespace for the UPDATE.
+                const existing = await store.findEscalationByMetadata(params.key, params.value, params.roles ?? null);
+                if (!existing)
                     return { ok: false, reason: 'not-found' };
+                if (existing.status === 'resolved')
+                    return { ok: false, reason: 'already-resolved' };
+                if (existing.status === 'cancelled')
+                    return { ok: false, reason: 'already-cancelled' };
+                // Same atomic pattern as resolve(): signal INSERTs + UPDATE in one transaction.
+                const txn = store.transact();
+                if (existing.signal_key && existing.topic) {
+                    const signalPayload = { id: existing.signal_key, data: params.resolverPayload ?? {} };
+                    try {
+                        const sc = await this.getHotMeshClient(`${ns}.wfs.signal`, ns);
+                        await sc.engine.signal(`${ns}.wfs.signal`, signalPayload, types_1.StreamStatus.SUCCESS, 200, txn);
+                    }
+                    catch { /* no collator hook rule — skip */ }
+                    try {
+                        const wc = await this.getHotMeshClient(`${ns}.wfs.wait`, ns);
+                        await wc.engine.signal(`${ns}.wfs.wait`, signalPayload, types_1.StreamStatus.SUCCESS, 200, txn);
+                    }
+                    catch { /* no waiter hook rule — skip */ }
                 }
-                const ns = params.namespace ?? factory_1.APP_ID;
-                const storeResult = await store.resolveSignalByMetadata({
-                    namespace: ns,
-                    appId: store.appId,
-                    key: params.key,
-                    value: params.value,
-                    resolverPayload: params.resolverPayload,
-                });
-                if (!storeResult.ok)
-                    return storeResult;
-                try {
-                    await this.workflow.signal(storeResult.signalKey, params.resolverPayload ?? {}, params.namespace);
-                    return { ok: true };
-                }
-                catch {
-                    return { ok: false, reason: 'signal-failed', signalKey: storeResult.signalKey };
-                }
+                store.queueResolveEscalation({ id: existing.id, namespace: existing.namespace ?? ns, resolverPayload: params.resolverPayload }, txn);
+                await txn.exec();
+                return { ok: true };
             },
+            /**
+             * Releases all claimed escalations whose `claim_expires_at` has lapsed,
+             * returning them to `pending` so they can be claimed again. Returns the
+             * number of rows released. Call periodically from a maintenance job or
+             * cron to prevent stale claims from blocking the queue.
+             *
+             * @example
+             * ```typescript
+             * const released = await client.escalations.releaseExpired();
+             * console.log(`Released ${released} expired claims`);
+             * ```
+             */
             releaseExpired: async (namespace) => {
-                const hotMesh = await this.getHotMeshClient(null, namespace);
-                const store = hotMesh.engine.store;
-                if (typeof store.releaseExpiredSignals !== 'function')
-                    return 0;
-                const ns = namespace ?? factory_1.APP_ID;
-                return store.releaseExpiredSignals({ namespace: ns, appId: store.appId });
+                const hotMeshClient = await this.getHotMeshClient(null, namespace);
+                return hotMeshClient.engine.store.releaseExpiredEscalations(namespace);
             },
         };
         this.connection = config.connection;

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

@@ -318,5 +318,3 @@ declare class DurableClass {
 }
 export { DurableClass as Durable };
 export type { ContextType };
-export type { ConditionQueueConfig } from './workflow/condition';
-export type { ClaimSignalResult, ReleaseSignalResult, ResolveSignalResult, SignalQueueEntry, } from '../../types/signal';

package/build/services/durable/schemas/factory.js

@@ -336,6 +336,9 @@ const getWorkflowYAML = (app, version) => {
                     type: string
                   originJobId:
                     type: string
+                  queueConfig:
+                    type: object
+                    description: optional escalation queue config passed to condition()
           job:
             maps:
               response: '{$self.output.data.response}'
@@ -370,6 +373,23 @@ const getWorkflowYAML = (app, version) => {
         waiter:
           title: Waits for a matching signal or optional timeout (single condition)
           type: hook
+          escalation:
+            type: '{worker.output.data.queueConfig.type}'
+            subtype: '{worker.output.data.queueConfig.subtype}'
+            entity: '{worker.output.data.queueConfig.entity}'
+            description: '{worker.output.data.queueConfig.description}'
+            role: '{worker.output.data.queueConfig.role}'
+            priority: '{worker.output.data.queueConfig.priority}'
+            metadata: '{worker.output.data.queueConfig.metadata}'
+            envelope: '{worker.output.data.queueConfig.envelope}'
+            originId: '{worker.output.data.queueConfig.originId}'
+            parentId: '{worker.output.data.queueConfig.parentId}'
+            initiatedBy: '{worker.output.data.queueConfig.initiatedBy}'
+            traceId: '{worker.output.data.queueConfig.traceId}'
+            spanId: '{worker.output.data.queueConfig.spanId}'
+            expiresAt: '{worker.output.data.queueConfig.expiresAt}'
+            taskQueue: '{trigger.output.data.taskQueue}'
+            workflowType: '{trigger.output.data.workflowName}'
           sleep: '{worker.output.data.duration}'
           hook:
             type: object
@@ -1137,6 +1157,9 @@ const getWorkflowYAML = (app, version) => {
                     type: string
                   originJobId:
                     type: string
+                  queueConfig:
+                    type: object
+                    description: optional escalation queue config passed to condition()
 
         signaler_sleeper:
           title: Pauses a single thread within the worker for a set amount of seconds while the main flow thread and all other subthreads remain active
@@ -1165,6 +1188,23 @@ const getWorkflowYAML = (app, version) => {
         signaler_waiter:
           title: Waits for a matching signal or optional timeout (single condition in signal-in path)
           type: hook
+          escalation:
+            type: '{signaler_worker.output.data.queueConfig.type}'
+            subtype: '{signaler_worker.output.data.queueConfig.subtype}'
+            entity: '{signaler_worker.output.data.queueConfig.entity}'
+            description: '{signaler_worker.output.data.queueConfig.description}'
+            role: '{signaler_worker.output.data.queueConfig.role}'
+            priority: '{signaler_worker.output.data.queueConfig.priority}'
+            metadata: '{signaler_worker.output.data.queueConfig.metadata}'
+            envelope: '{signaler_worker.output.data.queueConfig.envelope}'
+            originId: '{signaler_worker.output.data.queueConfig.originId}'
+            parentId: '{signaler_worker.output.data.queueConfig.parentId}'
+            initiatedBy: '{signaler_worker.output.data.queueConfig.initiatedBy}'
+            traceId: '{signaler_worker.output.data.queueConfig.traceId}'
+            spanId: '{signaler_worker.output.data.queueConfig.spanId}'
+            expiresAt: '{signaler_worker.output.data.queueConfig.expiresAt}'
+            taskQueue: '{trigger.output.data.taskQueue}'
+            workflowType: '{trigger.output.data.workflowName}'
           sleep: '{signaler_worker.output.data.duration}'
           hook:
             type: object

package/build/services/durable/worker.js

@@ -806,45 +806,22 @@ class WorkerService {
                     const workflowInput = data.data;
                     const execIndex = counter.counter;
                     const { workflowId, workflowDimension, originJobId } = workflowInput;
-                    const payload = interruptionRegistry[0];
-                    //if condition() was called with queueConfig, create a signal queue record
-                    if (payload.queueConfig) {
-                        const store = this.workflowRunner.engine.store;
-                        if (typeof store.enqueueSignal === 'function') {
-                            const ns = config.namespace ?? factory_1.APP_ID;
-                            try {
-                                await store.enqueueSignal({
-                                    namespace: ns,
-                                    appId: store.appId,
-                                    signalKey: payload.signalId,
-                                    workflowId,
-                                    topic: `${ns}.wfs.wait`,
-                                    taskQueue: config.taskQueue ?? payload.queueConfig.taskQueue,
-                                    ...payload.queueConfig,
-                                });
-                            }
-                            catch (enqueueErr) {
-                                this.workflowRunner.engine.logger.warn('signal-queue-enqueue-err', {
-                                    signalId: payload.signalId,
-                                    error: enqueueErr,
-                                });
-                            }
-                        }
-                    }
+                    const pendingInterruption = interruptionRegistry[0];
                     return withPatchMarkers({
                         status: stream_1.StreamStatus.SUCCESS,
                         code: enums_1.HMSH_CODE_DURABLE_WAIT,
                         metadata: { ...data.metadata },
                         data: {
                             code: enums_1.HMSH_CODE_DURABLE_WAIT,
-                            signalId: interruptionRegistry[0].signalId,
+                            signalId: pendingInterruption.signalId,
                             index: execIndex,
-                            workflowDimension: interruptionRegistry[0].workflowDimension ||
+                            workflowDimension: pendingInterruption.workflowDimension ||
                                 workflowDimension ||
                                 '',
-                            duration: interruptionRegistry[0].duration,
+                            duration: pendingInterruption.duration,
                             workflowId,
                             originJobId: originJobId || workflowId,
+                            queueConfig: pendingInterruption.queueConfig ?? null,
                         },
                     });
                 }