@hotmeshio/hotmesh 0.21.1 → 0.22.1

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,
                         },
                     });
                 }

package/build/services/durable/workflow/condition.d.ts

@@ -1,5 +1,4 @@
-import type { ConditionQueueConfig } from '../../../types/signal';
-export type { ConditionQueueConfig };
+import { ConditionQueueConfig } from '../../../types/hmsh_escalations';
 /**
  * Pauses the workflow until a signal with the given `signalId` is received.
  * The workflow suspends durably — it survives process restarts and will
@@ -7,64 +6,97 @@ export type { ConditionQueueConfig };
  *
  * `condition` is the **receive** side of the signal coordination pair.
  * The **send** side is `signal()`, which can be called from another
- * workflow, a hook function, or externally via `Durable.Client.workflow.signal()`.
+ * workflow, a hook function, or externally via `client.workflow.signal()`.
  *
  * On replay, `condition` returns the previously stored signal payload
- * immediately (no actual suspension occurs).
+ * immediately — no actual suspension occurs.
  *
- * ## Examples
+ * ## Basic usage
  *
  * ```typescript
  * import { Durable } from '@hotmeshio/hotmesh';
  *
- * // Human-in-the-loop approval pattern
  * export async function approvalWorkflow(orderId: string): Promise<boolean> {
  *   const { submitForReview } = Durable.workflow.proxyActivities<typeof activities>();
- *
  *   await submitForReview(orderId);
  *
- *   // Pause indefinitely until a human approves or rejects
+ *   // Pause until a human approves or rejects
  *   const decision = await Durable.workflow.condition<{ approved: boolean }>('approval');
- *
  *   return decision.approved;
  * }
  *
- * // Later, from outside the workflow (e.g., an API handler):
+ * // From an API handler or another workflow:
  * await client.workflow.signal('approval', { approved: true });
  * ```
  *
+ * ## With timeout
+ *
+ * Pass a duration string as the second argument to set a deadline.
+ * `condition` returns `false` if the timeout fires before a signal arrives.
+ *
  * ```typescript
- * // Fan-in: wait for multiple signals in parallel
- * export async function gatherWorkflow(): Promise<[string, number]> {
- *   const [name, score] = await Promise.all([
- *     Durable.workflow.condition<string>('name-signal'),
- *     Durable.workflow.condition<number>('score-signal'),
- *   ]);
- *   return [name, score];
- * }
+ * const decision = await Durable.workflow.condition<{ approved: boolean }>(
+ *   'approval',
+ *   '72h',              // give reviewers 72 hours; returns false on timeout
+ * );
+ * if (decision === false) return 'auto-rejected-timeout';
+ * return decision.approved ? 'approved' : 'rejected';
  * ```
  *
+ * ## With escalation queue config
+ *
+ * Pass a {@link ConditionQueueConfig} as the second argument to surface the
+ * pause as a claimable row in `public.hmsh_escalations`. The INSERT is
+ * committed atomically with the workflow checkpoint — one write, no
+ * enrichment step, no secondary round-trip.
+ *
  * ```typescript
- * // Paired with hook: spawn work and wait for the result
- * export async function orchestrator(input: string): Promise<string> {
- *   const signalId = `result-${Durable.workflow.random()}`;
- *
- *   // Spawn a hook that will signal back when done
- *   await Durable.workflow.hook({
- *     taskQueue: 'processors',
- *     workflowName: 'processItem',
- *     args: [input, signalId],
- *   });
- *
- *   // Wait for the hook to signal completion
- *   return await Durable.workflow.condition<string>(signalId);
- * }
+ * const decision = await Durable.workflow.condition<{ approved: boolean }>(
+ *   'manager-approval',
+ *   {
+ *     role: 'manager',
+ *     type: 'order-approval',
+ *     subtype: 'regional',
+ *     priority: 2,
+ *     description: 'Approve or reject the regional order',
+ *     metadata: { orderId, region },
+ *     envelope: { instructions: 'Review the attached order' },
+ *   },
+ * );
+ *
+ * // Elsewhere: list, claim, then resolve (resumes the workflow)
+ * const [item] = await client.escalations.list({ role: 'manager', status: 'pending' });
+ * await client.escalations.claim({ id: item.id, assignee: 'alice@company.com' });
+ * await client.escalations.resolve({ id: item.id, resolverPayload: { approved: true } });
+ * ```
+ *
+ * ## Fan-in: wait for multiple signals in parallel
+ *
+ * ```typescript
+ * const [name, score] = await Promise.all([
+ *   Durable.workflow.condition<string>('name-signal'),
+ *   Durable.workflow.condition<number>('score-signal'),
+ * ]);
+ * ```
+ *
+ * ## Paired with hook: spawn work, wait for its signal
+ *
+ * ```typescript
+ * const signalId = `result-${Durable.workflow.random()}`;
+ * await Durable.workflow.hook({
+ *   taskQueue: 'processors',
+ *   workflowName: 'processItem',
+ *   args: [input, signalId],
+ * });
+ * return await Durable.workflow.condition<string>(signalId);
  * ```
  *
  * @template T - The type of data expected in the signal payload.
- * @param {string} signalId - A unique signal identifier shared by the sender and receiver.
- * @param {string | ConditionQueueConfig} [timeoutOrConfig] - Optional timeout string (e.g. '30s') OR queue config object.
- * @param {ConditionQueueConfig} [queueConfig] - Optional queue config when timeout is also provided.
- * @returns {Promise<T | false>} The signal data, or `false` if the timeout expired first.
+ * @param signalId - A unique signal identifier shared by the sender and receiver.
+ * @param timeoutOrConfig - Optional timeout string (e.g. `'30s'`, `'24h'`) OR a
+ *   {@link ConditionQueueConfig} that writes one row to `public.hmsh_escalations`
+ *   atomically at suspension time. Cannot specify both; use the config object's
+ *   `expiresAt` field for deadline enforcement when an escalation is involved.
+ * @returns The signal payload, or `false` if a timeout string was given and it expired.
  */
-export declare function condition<T>(signalId: string, timeoutOrConfig?: string | ConditionQueueConfig, queueConfig?: ConditionQueueConfig): Promise<T | false>;
+export declare function condition<T>(signalId: string, timeoutOrConfig?: string | ConditionQueueConfig): Promise<T | false>;

package/build/services/durable/workflow/condition.js

@@ -11,71 +11,102 @@ const didRun_1 = require("./didRun");
  *
  * `condition` is the **receive** side of the signal coordination pair.
  * The **send** side is `signal()`, which can be called from another
- * workflow, a hook function, or externally via `Durable.Client.workflow.signal()`.
+ * workflow, a hook function, or externally via `client.workflow.signal()`.
  *
  * On replay, `condition` returns the previously stored signal payload
- * immediately (no actual suspension occurs).
+ * immediately — no actual suspension occurs.
  *
- * ## Examples
+ * ## Basic usage
  *
  * ```typescript
  * import { Durable } from '@hotmeshio/hotmesh';
  *
- * // Human-in-the-loop approval pattern
  * export async function approvalWorkflow(orderId: string): Promise<boolean> {
  *   const { submitForReview } = Durable.workflow.proxyActivities<typeof activities>();
- *
  *   await submitForReview(orderId);
  *
- *   // Pause indefinitely until a human approves or rejects
+ *   // Pause until a human approves or rejects
  *   const decision = await Durable.workflow.condition<{ approved: boolean }>('approval');
- *
  *   return decision.approved;
  * }
  *
- * // Later, from outside the workflow (e.g., an API handler):
+ * // From an API handler or another workflow:
  * await client.workflow.signal('approval', { approved: true });
  * ```
  *
+ * ## With timeout
+ *
+ * Pass a duration string as the second argument to set a deadline.
+ * `condition` returns `false` if the timeout fires before a signal arrives.
+ *
  * ```typescript
- * // Fan-in: wait for multiple signals in parallel
- * export async function gatherWorkflow(): Promise<[string, number]> {
- *   const [name, score] = await Promise.all([
- *     Durable.workflow.condition<string>('name-signal'),
- *     Durable.workflow.condition<number>('score-signal'),
- *   ]);
- *   return [name, score];
- * }
+ * const decision = await Durable.workflow.condition<{ approved: boolean }>(
+ *   'approval',
+ *   '72h',              // give reviewers 72 hours; returns false on timeout
+ * );
+ * if (decision === false) return 'auto-rejected-timeout';
+ * return decision.approved ? 'approved' : 'rejected';
  * ```
  *
+ * ## With escalation queue config
+ *
+ * Pass a {@link ConditionQueueConfig} as the second argument to surface the
+ * pause as a claimable row in `public.hmsh_escalations`. The INSERT is
+ * committed atomically with the workflow checkpoint — one write, no
+ * enrichment step, no secondary round-trip.
+ *
  * ```typescript
- * // Paired with hook: spawn work and wait for the result
- * export async function orchestrator(input: string): Promise<string> {
- *   const signalId = `result-${Durable.workflow.random()}`;
- *
- *   // Spawn a hook that will signal back when done
- *   await Durable.workflow.hook({
- *     taskQueue: 'processors',
- *     workflowName: 'processItem',
- *     args: [input, signalId],
- *   });
- *
- *   // Wait for the hook to signal completion
- *   return await Durable.workflow.condition<string>(signalId);
- * }
+ * const decision = await Durable.workflow.condition<{ approved: boolean }>(
+ *   'manager-approval',
+ *   {
+ *     role: 'manager',
+ *     type: 'order-approval',
+ *     subtype: 'regional',
+ *     priority: 2,
+ *     description: 'Approve or reject the regional order',
+ *     metadata: { orderId, region },
+ *     envelope: { instructions: 'Review the attached order' },
+ *   },
+ * );
+ *
+ * // Elsewhere: list, claim, then resolve (resumes the workflow)
+ * const [item] = await client.escalations.list({ role: 'manager', status: 'pending' });
+ * await client.escalations.claim({ id: item.id, assignee: 'alice@company.com' });
+ * await client.escalations.resolve({ id: item.id, resolverPayload: { approved: true } });
+ * ```
+ *
+ * ## Fan-in: wait for multiple signals in parallel
+ *
+ * ```typescript
+ * const [name, score] = await Promise.all([
+ *   Durable.workflow.condition<string>('name-signal'),
+ *   Durable.workflow.condition<number>('score-signal'),
+ * ]);
+ * ```
+ *
+ * ## Paired with hook: spawn work, wait for its signal
+ *
+ * ```typescript
+ * const signalId = `result-${Durable.workflow.random()}`;
+ * await Durable.workflow.hook({
+ *   taskQueue: 'processors',
+ *   workflowName: 'processItem',
+ *   args: [input, signalId],
+ * });
+ * return await Durable.workflow.condition<string>(signalId);
  * ```
  *
  * @template T - The type of data expected in the signal payload.
- * @param {string} signalId - A unique signal identifier shared by the sender and receiver.
- * @param {string | ConditionQueueConfig} [timeoutOrConfig] - Optional timeout string (e.g. '30s') OR queue config object.
- * @param {ConditionQueueConfig} [queueConfig] - Optional queue config when timeout is also provided.
- * @returns {Promise<T | false>} The signal data, or `false` if the timeout expired first.
+ * @param signalId - A unique signal identifier shared by the sender and receiver.
+ * @param timeoutOrConfig - Optional timeout string (e.g. `'30s'`, `'24h'`) OR a
+ *   {@link ConditionQueueConfig} that writes one row to `public.hmsh_escalations`
+ *   atomically at suspension time. Cannot specify both; use the config object's
+ *   `expiresAt` field for deadline enforcement when an escalation is involved.
+ * @returns The signal payload, or `false` if a timeout string was given and it expired.
  */
-async function condition(signalId, timeoutOrConfig, queueConfig) {
+async function condition(signalId, timeoutOrConfig) {
     const timeout = typeof timeoutOrConfig === 'string' ? timeoutOrConfig : undefined;
-    const resolvedQueueConfig = typeof timeoutOrConfig === 'object' && timeoutOrConfig !== null
-        ? timeoutOrConfig
-        : queueConfig;
+    const queueConfig = timeoutOrConfig && typeof timeoutOrConfig === 'object' ? timeoutOrConfig : undefined;
     const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('wait');
     (0, cancellationScope_1.checkCancellation)();
     if (didRunAlready) {
@@ -122,7 +153,7 @@ async function condition(signalId, timeoutOrConfig, queueConfig) {
         type: 'DurableWaitForError',
         code: common_1.HMSH_CODE_DURABLE_WAIT,
         ...(timeout ? { duration: (0, common_1.s)(timeout) } : {}),
-        ...(resolvedQueueConfig ? { queueConfig: resolvedQueueConfig } : {}),
+        ...(queueConfig ? { queueConfig } : {}),
     };
     interruptionRegistry.push(interruptionMessage);
     await (0, common_1.sleepImmediate)();

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

@@ -320,11 +320,38 @@ declare class HotMesh {
      */
     scrub(jobId: string): Promise<void>;
     /**
-     * Sends a signal to a paused workflow, delivering data and resuming
-     * execution. Pairs with `condition()` in the Durable workflow API.
+     * Sends a signal to a paused workflow, resuming its execution with the
+     * provided data. This is the low-level primitive used by both the Durable
+     * `client.workflow.signal()` wrapper and `client.escalations.resolve()`.
      *
-     * @param topic - The signal topic.
-     * @param data - Signal payload.
+     * The signal is matched to the waiting activity by the `id` field inside
+     * `data` — it must equal the value used in the hook rule's
+     * `conditions.match[0].expected` expression (typically the job ID).
+     *
+     * **YAML DAG hook example** — signal a workflow paused at a webhook:
+     *
+     * ```typescript
+     * // The hook activity is waiting on topic 'order.approval'
+     * // The hook rule expects: actual '{$self.hook.data.id}' === '{t1.output.data.id}'
+     * await hotMesh.signal('order.approval', { id: jobId, approved: true });
+     * ```
+     *
+     * **Durable workflow** — use `client.workflow.signal()` instead, which
+     * resolves the topic internally:
+     *
+     * ```typescript
+     * await client.workflow.signal('manager-approval', { approved: true });
+     * ```
+     *
+     * **With escalation** — use `client.escalations.resolve()` to atomically
+     * deliver the signal and mark the escalation row resolved:
+     *
+     * ```typescript
+     * await client.escalations.resolve({ id: escalationId, resolverPayload: { approved: true } });
+     * ```
+     *
+     * @param topic - The signal topic (must match a deployed hook rule).
+     * @param data - Signal payload. Must contain `id` matching the hook rule's expected value.
      */
     signal(topic: string, data: JobData, status?: StreamStatus, code?: StreamCode): Promise<string>;
     /** @private */

package/build/services/hotmesh/index.js

@@ -428,11 +428,38 @@ class HotMesh {
         return Jobs.scrub(this, jobId);
     }
     /**
-     * Sends a signal to a paused workflow, delivering data and resuming
-     * execution. Pairs with `condition()` in the Durable workflow API.
+     * Sends a signal to a paused workflow, resuming its execution with the
+     * provided data. This is the low-level primitive used by both the Durable
+     * `client.workflow.signal()` wrapper and `client.escalations.resolve()`.
      *
-     * @param topic - The signal topic.
-     * @param data - Signal payload.
+     * The signal is matched to the waiting activity by the `id` field inside
+     * `data` — it must equal the value used in the hook rule's
+     * `conditions.match[0].expected` expression (typically the job ID).
+     *
+     * **YAML DAG hook example** — signal a workflow paused at a webhook:
+     *
+     * ```typescript
+     * // The hook activity is waiting on topic 'order.approval'
+     * // The hook rule expects: actual '{$self.hook.data.id}' === '{t1.output.data.id}'
+     * await hotMesh.signal('order.approval', { id: jobId, approved: true });
+     * ```
+     *
+     * **Durable workflow** — use `client.workflow.signal()` instead, which
+     * resolves the topic internally:
+     *
+     * ```typescript
+     * await client.workflow.signal('manager-approval', { approved: true });
+     * ```
+     *
+     * **With escalation** — use `client.escalations.resolve()` to atomically
+     * deliver the signal and mark the escalation row resolved:
+     *
+     * ```typescript
+     * await client.escalations.resolve({ id: escalationId, resolverPayload: { approved: true } });
+     * ```
+     *
+     * @param topic - The signal topic (must match a deployed hook rule).
+     * @param data - Signal payload. Must contain `id` matching the hook rule's expected value.
      */
     async signal(topic, data, status, code) {
         return Jobs.signal(this, topic, data, status, code);

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

@@ -45,7 +45,7 @@ declare abstract class StoreService<Provider extends ProviderClient, Transaction
     jobId: string, appId: string, guidField: string, // 
     guidWeight: number, transaction?: ProviderTransaction): Promise<any>;
     abstract getStatus(jobId: string, appId: string): Promise<number>;
-    abstract setStateNX(jobId: string, appId: string, status?: number, entity?: string, transaction?: ProviderTransaction): Promise<boolean>;
+    abstract setStateNX(jobId: string, appId: string, status?: number, entity?: string, transaction?: ProviderTransaction, originId?: string, parentId?: string): Promise<boolean>;
     abstract setState(state: StringAnyType, status: number | null, jobId: string, symbolNames: string[], dIds: StringStringType, transaction?: TransactionProvider): Promise<string>;
     abstract getQueryState(jobId: string, fields: string[]): Promise<StringAnyType>;
     abstract getState(jobId: string, consumes: Consumes, dIds: StringStringType): Promise<[StringAnyType, number] | undefined>;

package/build/services/store/providers/postgres/kvsql.d.ts

@@ -59,7 +59,7 @@ export declare class KVSQL {
     setnxex: (key: string, value: string, delay: number, multi?: ProviderTransaction) => Promise<boolean>;
     hset: (key: string, fields: Record<string, string>, options?: import("./kvtypes/hash/index").HSetOptions, multi?: any) => Promise<any>;
     _hset: (key: string, fields: Record<string, string>, options?: import("./kvtypes/hash/index").HSetOptions) => import("./kvtypes/hash/types").SqlResult;
-    hsetnx: (key: string, field: string, value: string, multi?: ProviderTransaction, entity?: string) => Promise<number>;
+    hsetnx: (key: string, field: string, value: string, multi?: ProviderTransaction, entity?: string, originId?: string, parentId?: string) => Promise<number>;
     hget: (key: string, field: string, multi?: ProviderTransaction) => Promise<string>;
     _hget: (key: string, field: string) => import("./kvtypes/hash/types").SqlResult;
     hdel: (key: string, fields: string[], multi?: unknown) => Promise<number>;