@hotmeshio/hotmesh 0.12.1 → 0.14.0

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

@@ -0,0 +1,104 @@
+/**
+ * Error thrown when a workflow detects a pending cancellation request.
+ * Workflows can catch this error to perform cleanup before terminating.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function myWorkflow(): Promise<string> {
+ *   const acts = Durable.workflow.proxyActivities<typeof activities>({ ... });
+ *
+ *   try {
+ *     await acts.longRunningTask();
+ *   } catch (err) {
+ *     if (Durable.workflow.isCancellation(err)) {
+ *       await CancellationScope.nonCancellable(async () => {
+ *         await acts.cleanup();
+ *       });
+ *       return 'cancelled-with-cleanup';
+ *     }
+ *     throw err;
+ *   }
+ *   return 'done';
+ * }
+ * ```
+ */
+export declare class CancelledFailure extends Error {
+    type: string;
+    constructor(message?: string);
+}
+/**
+ * Type guard that returns `true` if the error is a {@link CancelledFailure},
+ * indicating the workflow was cancelled via `handle.cancel()`.
+ *
+ * Use this inside `catch` blocks to distinguish cancellation from
+ * application errors. Always check with `didInterrupt` first for
+ * engine control-flow signals, then check `isCancellation` for
+ * cooperative cancellation.
+ *
+ * @param {any} err - The error to check.
+ * @returns {boolean} `true` if the error is a `CancelledFailure`.
+ */
+export declare function isCancellation(err: any): err is CancelledFailure;
+/**
+ * Controls how cancellation propagates through workflow code.
+ *
+ * When a workflow is cancelled via `handle.cancel()`, the next durable
+ * operation (`sleep`, `proxyActivities`, `executeChild`, `condition`,
+ * `continueAsNew`) throws a {@link CancelledFailure}. Use
+ * `CancellationScope.nonCancellable(fn)` to shield cleanup code from
+ * this behavior — durable operations inside the scope will execute
+ * normally even when cancellation is pending.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * const { CancellationScope, isCancellation } = Durable.workflow;
+ *
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   const acts = Durable.workflow.proxyActivities<typeof activities>({ ... });
+ *
+ *   try {
+ *     await acts.chargePayment(orderId);
+ *     await Durable.workflow.sleep('7 days');
+ *     await acts.shipOrder(orderId);
+ *   } catch (err) {
+ *     if (isCancellation(err)) {
+ *       // Shield cleanup from further cancellation
+ *       await CancellationScope.nonCancellable(async () => {
+ *         await acts.refundPayment(orderId);
+ *         await acts.notifyCustomer(orderId, 'Order cancelled');
+ *       });
+ *       return 'cancelled';
+ *     }
+ *     throw err;
+ *   }
+ *   return 'shipped';
+ * }
+ * ```
+ */
+export declare class CancellationScope {
+    /**
+     * Execute `fn` with cancellation suppressed. Durable operations
+     * inside the callback will not throw `CancelledFailure` even if
+     * the workflow has a pending cancellation request. Use this for
+     * cleanup logic (refunds, notifications, audit logs) that must
+     * complete regardless of cancellation state.
+     *
+     * @param fn - The async function to execute without cancellation.
+     * @returns The return value of `fn`.
+     */
+    static nonCancellable<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Checks for a pending cancellation request and throws
+ * `CancelledFailure` if one exists and we are not inside
+ * a `CancellationScope.nonCancellable()` block.
+ *
+ * Called at the entry of every durable operation.
+ * @private
+ */
+export declare function checkCancellation(): void;

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

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCancellation = exports.CancellationScope = exports.isCancellation = exports.CancelledFailure = void 0;
+const common_1 = require("./common");
+/**
+ * Error thrown when a workflow detects a pending cancellation request.
+ * Workflows can catch this error to perform cleanup before terminating.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function myWorkflow(): Promise<string> {
+ *   const acts = Durable.workflow.proxyActivities<typeof activities>({ ... });
+ *
+ *   try {
+ *     await acts.longRunningTask();
+ *   } catch (err) {
+ *     if (Durable.workflow.isCancellation(err)) {
+ *       await CancellationScope.nonCancellable(async () => {
+ *         await acts.cleanup();
+ *       });
+ *       return 'cancelled-with-cleanup';
+ *     }
+ *     throw err;
+ *   }
+ *   return 'done';
+ * }
+ * ```
+ */
+class CancelledFailure extends Error {
+    constructor(message = 'Workflow cancelled') {
+        super(message);
+        this.type = 'CancelledFailure';
+        this.name = 'CancelledFailure';
+    }
+}
+exports.CancelledFailure = CancelledFailure;
+/**
+ * Type guard that returns `true` if the error is a {@link CancelledFailure},
+ * indicating the workflow was cancelled via `handle.cancel()`.
+ *
+ * Use this inside `catch` blocks to distinguish cancellation from
+ * application errors. Always check with `didInterrupt` first for
+ * engine control-flow signals, then check `isCancellation` for
+ * cooperative cancellation.
+ *
+ * @param {any} err - The error to check.
+ * @returns {boolean} `true` if the error is a `CancelledFailure`.
+ */
+function isCancellation(err) {
+    return err instanceof CancelledFailure;
+}
+exports.isCancellation = isCancellation;
+/**
+ * Controls how cancellation propagates through workflow code.
+ *
+ * When a workflow is cancelled via `handle.cancel()`, the next durable
+ * operation (`sleep`, `proxyActivities`, `executeChild`, `condition`,
+ * `continueAsNew`) throws a {@link CancelledFailure}. Use
+ * `CancellationScope.nonCancellable(fn)` to shield cleanup code from
+ * this behavior — durable operations inside the scope will execute
+ * normally even when cancellation is pending.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * const { CancellationScope, isCancellation } = Durable.workflow;
+ *
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   const acts = Durable.workflow.proxyActivities<typeof activities>({ ... });
+ *
+ *   try {
+ *     await acts.chargePayment(orderId);
+ *     await Durable.workflow.sleep('7 days');
+ *     await acts.shipOrder(orderId);
+ *   } catch (err) {
+ *     if (isCancellation(err)) {
+ *       // Shield cleanup from further cancellation
+ *       await CancellationScope.nonCancellable(async () => {
+ *         await acts.refundPayment(orderId);
+ *         await acts.notifyCustomer(orderId, 'Order cancelled');
+ *       });
+ *       return 'cancelled';
+ *     }
+ *     throw err;
+ *   }
+ *   return 'shipped';
+ * }
+ * ```
+ */
+class CancellationScope {
+    /**
+     * Execute `fn` with cancellation suppressed. Durable operations
+     * inside the callback will not throw `CancelledFailure` even if
+     * the workflow has a pending cancellation request. Use this for
+     * cleanup logic (refunds, notifications, audit logs) that must
+     * complete regardless of cancellation state.
+     *
+     * @param fn - The async function to execute without cancellation.
+     * @returns The return value of `fn`.
+     */
+    static async nonCancellable(fn) {
+        const store = common_1.asyncLocalStorage.getStore();
+        const prev = store.get('nonCancellable');
+        store.set('nonCancellable', true);
+        try {
+            return await fn();
+        }
+        finally {
+            store.set('nonCancellable', prev ?? false);
+        }
+    }
+}
+exports.CancellationScope = CancellationScope;
+/**
+ * Checks for a pending cancellation request and throws
+ * `CancelledFailure` if one exists and we are not inside
+ * a `CancellationScope.nonCancellable()` block.
+ *
+ * Called at the entry of every durable operation.
+ * @private
+ */
+function checkCancellation() {
+    const store = common_1.asyncLocalStorage.getStore();
+    if (!store)
+        return;
+    const replay = store.get('replay');
+    if (!replay)
+        return;
+    const workflowDimension = store.get('workflowDimension') ?? '';
+    const cancelKey = `-cancelled${workflowDimension}-`;
+    if (cancelKey in replay && !store.get('nonCancellable')) {
+        throw new CancelledFailure();
+    }
+}
+exports.checkCancellation = checkCancellation;

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

@@ -1,4 +1,4 @@
-import { DurableChildError, DurableFatalError, DurableMaxedError, DurableProxyError, DurableRetryError, DurableSleepError, DurableTimeoutError, DurableWaitForError } from '../../../modules/errors';
+import { DurableChildError, DurableContinueAsNewError, DurableFatalError, DurableMaxedError, DurableProxyError, DurableRetryError, DurableSleepError, DurableTimeoutError, DurableWaitForError } from '../../../modules/errors';
 import { KeyService, KeyType } from '../../../modules/key';
 import { asyncLocalStorage } from '../../../modules/storage';
 import { deterministicRandom, guid, s, sleepImmediate } from '../../../modules/utils';
@@ -8,13 +8,14 @@ import { ActivityConfig, ChildResponseType, HookOptions, ProxyResponseType, Prox
 import { JobInterruptOptions } from '../../../types/job';
 import { StreamCode, StreamStatus } from '../../../types/stream';
 import { StringAnyType, StringScalarType, StringStringType } from '../../../types/serializer';
-import { HMSH_CODE_DURABLE_CHILD, HMSH_CODE_DURABLE_FATAL, HMSH_CODE_DURABLE_MAXED, HMSH_CODE_DURABLE_PROXY, HMSH_CODE_DURABLE_SLEEP, HMSH_CODE_DURABLE_TIMEOUT, HMSH_CODE_DURABLE_WAIT, HMSH_DURABLE_EXP_BACKOFF, HMSH_DURABLE_MAX_ATTEMPTS, HMSH_DURABLE_MAX_INTERVAL } from '../../../modules/enums';
-import { DurableChildErrorType, DurableProxyErrorType } from '../../../types/error';
+import { HMSH_CODE_DURABLE_CHILD, HMSH_CODE_DURABLE_CONTINUE, HMSH_CODE_DURABLE_FATAL, HMSH_CODE_DURABLE_MAXED, HMSH_CODE_DURABLE_PROXY, HMSH_CODE_DURABLE_SLEEP, HMSH_CODE_DURABLE_TIMEOUT, HMSH_CODE_DURABLE_WAIT, HMSH_DURABLE_EXP_BACKOFF, HMSH_DURABLE_INITIAL_INTERVAL, HMSH_DURABLE_MAX_ATTEMPTS, HMSH_DURABLE_MAX_INTERVAL } from '../../../modules/enums';
+import { DurableChildErrorType, DurableContinueAsNewErrorType, DurableProxyErrorType } from '../../../types/error';
 import { TelemetryService } from '../../telemetry';
+import { DurableTelemetryService } from '../telemetry';
 import { QuorumMessage } from '../../../types';
 import { UserMessage } from '../../../types/quorum';
 import { Search } from '../search';
 import { WorkerService } from '../worker';
 import { Entity } from '../entity';
 import { ExecHookOptions } from './execHook';
-export { DurableChildError, DurableFatalError, DurableMaxedError, DurableProxyError, DurableRetryError, DurableSleepError, DurableTimeoutError, DurableWaitForError, KeyService, KeyType, asyncLocalStorage, deterministicRandom, guid, s, sleepImmediate, HotMesh, SerializerService, ActivityConfig, ChildResponseType, HookOptions, ExecHookOptions, ProxyResponseType, ProxyType, WorkflowContext, WorkflowOptions, JobInterruptOptions, StreamCode, StreamStatus, StringAnyType, StringScalarType, StringStringType, HMSH_CODE_DURABLE_CHILD, HMSH_CODE_DURABLE_FATAL, HMSH_CODE_DURABLE_MAXED, HMSH_CODE_DURABLE_PROXY, HMSH_CODE_DURABLE_SLEEP, HMSH_CODE_DURABLE_TIMEOUT, HMSH_CODE_DURABLE_WAIT, HMSH_DURABLE_EXP_BACKOFF, HMSH_DURABLE_MAX_ATTEMPTS, HMSH_DURABLE_MAX_INTERVAL, DurableChildErrorType, DurableProxyErrorType, TelemetryService, QuorumMessage, UserMessage, Search, WorkerService, Entity, };
+export { DurableChildError, DurableContinueAsNewError, DurableFatalError, DurableMaxedError, DurableProxyError, DurableRetryError, DurableSleepError, DurableTimeoutError, DurableWaitForError, KeyService, KeyType, asyncLocalStorage, deterministicRandom, guid, s, sleepImmediate, HotMesh, SerializerService, ActivityConfig, ChildResponseType, HookOptions, ExecHookOptions, ProxyResponseType, ProxyType, WorkflowContext, WorkflowOptions, JobInterruptOptions, StreamCode, StreamStatus, StringAnyType, StringScalarType, StringStringType, HMSH_CODE_DURABLE_CHILD, HMSH_CODE_DURABLE_CONTINUE, HMSH_CODE_DURABLE_FATAL, HMSH_CODE_DURABLE_MAXED, HMSH_CODE_DURABLE_PROXY, HMSH_CODE_DURABLE_SLEEP, HMSH_CODE_DURABLE_TIMEOUT, HMSH_CODE_DURABLE_WAIT, HMSH_DURABLE_EXP_BACKOFF, HMSH_DURABLE_INITIAL_INTERVAL, HMSH_DURABLE_MAX_ATTEMPTS, HMSH_DURABLE_MAX_INTERVAL, DurableChildErrorType, DurableContinueAsNewErrorType, DurableProxyErrorType, TelemetryService, DurableTelemetryService, QuorumMessage, UserMessage, Search, WorkerService, Entity, };

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

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Entity = exports.WorkerService = exports.Search = exports.TelemetryService = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_SLEEP = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_CHILD = exports.StreamStatus = exports.SerializerService = exports.HotMesh = exports.sleepImmediate = exports.s = exports.guid = exports.deterministicRandom = exports.asyncLocalStorage = exports.KeyType = exports.KeyService = exports.DurableWaitForError = exports.DurableTimeoutError = exports.DurableSleepError = exports.DurableRetryError = exports.DurableProxyError = exports.DurableMaxedError = exports.DurableFatalError = exports.DurableChildError = void 0;
+exports.Entity = exports.WorkerService = exports.Search = exports.DurableTelemetryService = exports.TelemetryService = exports.HMSH_DURABLE_MAX_INTERVAL = exports.HMSH_DURABLE_MAX_ATTEMPTS = exports.HMSH_DURABLE_INITIAL_INTERVAL = exports.HMSH_DURABLE_EXP_BACKOFF = exports.HMSH_CODE_DURABLE_WAIT = exports.HMSH_CODE_DURABLE_TIMEOUT = exports.HMSH_CODE_DURABLE_SLEEP = exports.HMSH_CODE_DURABLE_PROXY = exports.HMSH_CODE_DURABLE_MAXED = exports.HMSH_CODE_DURABLE_FATAL = exports.HMSH_CODE_DURABLE_CONTINUE = exports.HMSH_CODE_DURABLE_CHILD = exports.StreamStatus = exports.SerializerService = exports.HotMesh = exports.sleepImmediate = exports.s = exports.guid = exports.deterministicRandom = exports.asyncLocalStorage = exports.KeyType = exports.KeyService = exports.DurableWaitForError = exports.DurableTimeoutError = exports.DurableSleepError = exports.DurableRetryError = exports.DurableProxyError = exports.DurableMaxedError = exports.DurableFatalError = exports.DurableContinueAsNewError = exports.DurableChildError = void 0;
 const errors_1 = require("../../../modules/errors");
 Object.defineProperty(exports, "DurableChildError", { enumerable: true, get: function () { return errors_1.DurableChildError; } });
+Object.defineProperty(exports, "DurableContinueAsNewError", { enumerable: true, get: function () { return errors_1.DurableContinueAsNewError; } });
 Object.defineProperty(exports, "DurableFatalError", { enumerable: true, get: function () { return errors_1.DurableFatalError; } });
 Object.defineProperty(exports, "DurableMaxedError", { enumerable: true, get: function () { return errors_1.DurableMaxedError; } });
 Object.defineProperty(exports, "DurableProxyError", { enumerable: true, get: function () { return errors_1.DurableProxyError; } });
@@ -28,6 +29,7 @@ const stream_1 = require("../../../types/stream");
 Object.defineProperty(exports, "StreamStatus", { enumerable: true, get: function () { return stream_1.StreamStatus; } });
 const enums_1 = require("../../../modules/enums");
 Object.defineProperty(exports, "HMSH_CODE_DURABLE_CHILD", { enumerable: true, get: function () { return enums_1.HMSH_CODE_DURABLE_CHILD; } });
+Object.defineProperty(exports, "HMSH_CODE_DURABLE_CONTINUE", { enumerable: true, get: function () { return enums_1.HMSH_CODE_DURABLE_CONTINUE; } });
 Object.defineProperty(exports, "HMSH_CODE_DURABLE_FATAL", { enumerable: true, get: function () { return enums_1.HMSH_CODE_DURABLE_FATAL; } });
 Object.defineProperty(exports, "HMSH_CODE_DURABLE_MAXED", { enumerable: true, get: function () { return enums_1.HMSH_CODE_DURABLE_MAXED; } });
 Object.defineProperty(exports, "HMSH_CODE_DURABLE_PROXY", { enumerable: true, get: function () { return enums_1.HMSH_CODE_DURABLE_PROXY; } });
@@ -35,10 +37,13 @@ Object.defineProperty(exports, "HMSH_CODE_DURABLE_SLEEP", { enumerable: true, ge
 Object.defineProperty(exports, "HMSH_CODE_DURABLE_TIMEOUT", { enumerable: true, get: function () { return enums_1.HMSH_CODE_DURABLE_TIMEOUT; } });
 Object.defineProperty(exports, "HMSH_CODE_DURABLE_WAIT", { enumerable: true, get: function () { return enums_1.HMSH_CODE_DURABLE_WAIT; } });
 Object.defineProperty(exports, "HMSH_DURABLE_EXP_BACKOFF", { enumerable: true, get: function () { return enums_1.HMSH_DURABLE_EXP_BACKOFF; } });
+Object.defineProperty(exports, "HMSH_DURABLE_INITIAL_INTERVAL", { enumerable: true, get: function () { return enums_1.HMSH_DURABLE_INITIAL_INTERVAL; } });
 Object.defineProperty(exports, "HMSH_DURABLE_MAX_ATTEMPTS", { enumerable: true, get: function () { return enums_1.HMSH_DURABLE_MAX_ATTEMPTS; } });
 Object.defineProperty(exports, "HMSH_DURABLE_MAX_INTERVAL", { enumerable: true, get: function () { return enums_1.HMSH_DURABLE_MAX_INTERVAL; } });
 const telemetry_1 = require("../../telemetry");
 Object.defineProperty(exports, "TelemetryService", { enumerable: true, get: function () { return telemetry_1.TelemetryService; } });
+const telemetry_2 = require("../telemetry");
+Object.defineProperty(exports, "DurableTelemetryService", { enumerable: true, get: function () { return telemetry_2.DurableTelemetryService; } });
 const search_1 = require("../search");
 Object.defineProperty(exports, "Search", { enumerable: true, get: function () { return search_1.Search; } });
 const worker_1 = require("../worker");

package/build/services/durable/workflow/{waitFor.d.ts → condition.d.ts}

@@ -3,11 +3,11 @@
  * The workflow suspends durably — it survives process restarts and will
  * resume exactly once when the matching `signal()` call delivers data.
  *
- * `waitFor` is the **receive** side of the signal coordination pair.
+ * `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()`.
  *
- * On replay, `waitFor` returns the previously stored signal payload
+ * On replay, `condition` returns the previously stored signal payload
  * immediately (no actual suspension occurs).
  *
  * ## Examples
@@ -22,7 +22,7 @@
  *   await submitForReview(orderId);
  *
  *   // Pause indefinitely until a human approves or rejects
- *   const decision = await Durable.workflow.waitFor<{ approved: boolean }>('approval');
+ *   const decision = await Durable.workflow.condition<{ approved: boolean }>('approval');
  *
  *   return decision.approved;
  * }
@@ -35,8 +35,8 @@
  * // Fan-in: wait for multiple signals in parallel
  * export async function gatherWorkflow(): Promise<[string, number]> {
  *   const [name, score] = await Promise.all([
- *     Durable.workflow.waitFor<string>('name-signal'),
- *     Durable.workflow.waitFor<number>('score-signal'),
+ *     Durable.workflow.condition<string>('name-signal'),
+ *     Durable.workflow.condition<number>('score-signal'),
  *   ]);
  *   return [name, score];
  * }
@@ -55,12 +55,13 @@
  *   });
  *
  *   // Wait for the hook to signal completion
- *   return await Durable.workflow.waitFor<string>(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.
- * @returns {Promise<T>} The data payload associated with the received signal.
+ * @param {string} [timeout] - Optional duration (e.g., '30s', '5m', '1h'). Returns `false` on timeout.
+ * @returns {Promise<T | false>} The signal data, or `false` if the timeout expired first.
  */
-export declare function waitFor<T>(signalId: string): Promise<T>;
+export declare function condition<T>(signalId: string, timeout?: string): Promise<T | false>;

package/build/services/durable/workflow/{waitFor.js → condition.js}

@@ -1,18 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.waitFor = void 0;
+exports.condition = void 0;
 const common_1 = require("./common");
+const cancellationScope_1 = require("./cancellationScope");
 const didRun_1 = require("./didRun");
 /**
  * Pauses the workflow until a signal with the given `signalId` is received.
  * The workflow suspends durably — it survives process restarts and will
  * resume exactly once when the matching `signal()` call delivers data.
  *
- * `waitFor` is the **receive** side of the signal coordination pair.
+ * `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()`.
  *
- * On replay, `waitFor` returns the previously stored signal payload
+ * On replay, `condition` returns the previously stored signal payload
  * immediately (no actual suspension occurs).
  *
  * ## Examples
@@ -27,7 +28,7 @@ const didRun_1 = require("./didRun");
  *   await submitForReview(orderId);
  *
  *   // Pause indefinitely until a human approves or rejects
- *   const decision = await Durable.workflow.waitFor<{ approved: boolean }>('approval');
+ *   const decision = await Durable.workflow.condition<{ approved: boolean }>('approval');
  *
  *   return decision.approved;
  * }
@@ -40,8 +41,8 @@ const didRun_1 = require("./didRun");
  * // Fan-in: wait for multiple signals in parallel
  * export async function gatherWorkflow(): Promise<[string, number]> {
  *   const [name, score] = await Promise.all([
- *     Durable.workflow.waitFor<string>('name-signal'),
- *     Durable.workflow.waitFor<number>('score-signal'),
+ *     Durable.workflow.condition<string>('name-signal'),
+ *     Durable.workflow.condition<number>('score-signal'),
  *   ]);
  *   return [name, score];
  * }
@@ -60,20 +61,51 @@ const didRun_1 = require("./didRun");
  *   });
  *
  *   // Wait for the hook to signal completion
- *   return await Durable.workflow.waitFor<string>(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.
- * @returns {Promise<T>} The data payload associated with the received signal.
+ * @param {string} [timeout] - Optional duration (e.g., '30s', '5m', '1h'). Returns `false` on timeout.
+ * @returns {Promise<T | false>} The signal data, or `false` if the timeout expired first.
  */
-async function waitFor(signalId) {
+async function condition(signalId, timeout) {
     const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('wait');
+    (0, cancellationScope_1.checkCancellation)();
     if (didRunAlready) {
+        // Emit RETURN span in debug mode
+        if (common_1.DurableTelemetryService.isVerbose() && result) {
+            const store = common_1.asyncLocalStorage.getStore();
+            const workflowTrace = store.get('workflowTrace');
+            const workflowSpan = store.get('workflowSpan');
+            if (workflowTrace && workflowSpan && result.ac && result.au) {
+                common_1.DurableTelemetryService.emitDurationSpan(workflowTrace, workflowSpan, `RETURN/wait/${signalId}/${execIndex}`, common_1.DurableTelemetryService.parseTimestamp(result.ac), common_1.DurableTelemetryService.parseTimestamp(result.au), {
+                    'durable.operation.type': 'wait',
+                    'durable.signal.id': signalId,
+                    'durable.exec.index': execIndex,
+                });
+            }
+        }
+        // If the condition timed out (timeout won the race), return false
+        if (result?.timedOut) {
+            return false;
+        }
         return result.data.data;
     }
     const store = common_1.asyncLocalStorage.getStore();
+    // Emit DISPATCH span in debug mode
+    if (common_1.DurableTelemetryService.isVerbose()) {
+        const workflowTrace = store.get('workflowTrace');
+        const workflowSpan = store.get('workflowSpan');
+        if (workflowTrace && workflowSpan) {
+            common_1.DurableTelemetryService.emitPointSpan(workflowTrace, workflowSpan, `DISPATCH/wait/${signalId}/${execIndex}`, {
+                'durable.operation.type': 'wait',
+                'durable.signal.id': signalId,
+                'durable.exec.index': execIndex,
+            });
+        }
+    }
     const interruptionRegistry = store.get('interruptionRegistry');
     const workflowId = store.get('workflowId');
     const workflowDimension = store.get('workflowDimension') ?? '';
@@ -84,10 +116,11 @@ async function waitFor(signalId) {
         workflowDimension,
         type: 'DurableWaitForError',
         code: common_1.HMSH_CODE_DURABLE_WAIT,
+        ...(timeout ? { duration: (0, common_1.s)(timeout) } : {}),
     };
     interruptionRegistry.push(interruptionMessage);
     await (0, common_1.sleepImmediate)();
-    //if you are seeing this error in the logs, you might have forgotten to `await waitFor(...)`
+    //if you are seeing this error in the logs, you might have forgotten to `await condition(...)`
     throw new common_1.DurableWaitForError(interruptionMessage);
 }
-exports.waitFor = waitFor;
+exports.condition = condition;

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

@@ -0,0 +1,65 @@
+/**
+ * Completes the current workflow execution and immediately starts a new
+ * execution of the same workflow with the provided arguments. The execution
+ * history is reset, preventing unbounded state growth in long-running
+ * workflows.
+ *
+ * `continueAsNew` never returns — it always throws an internal interruption
+ * error that the engine catches to orchestrate the restart. Any code after
+ * the call is unreachable.
+ *
+ * ## When to Use
+ *
+ * Use `continueAsNew` for workflows that would otherwise run indefinitely
+ * and accumulate unbounded replay history:
+ * - Polling loops
+ * - Subscription renewals
+ * - Iterative processing with cursors
+ * - Long-running agents with periodic state resets
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * // Cursor-based batch processor
+ * export async function batchProcessor(cursor: string, totalProcessed = 0): Promise<void> {
+ *   const { fetchBatch, processBatch } = Durable.workflow.proxyActivities<typeof activities>({
+ *     activities,
+ *     retry: { maximumAttempts: 3 },
+ *   });
+ *
+ *   const batch = await fetchBatch(cursor);
+ *   await processBatch(batch.items);
+ *
+ *   if (batch.nextCursor) {
+ *     // Restart with fresh history, carrying forward the cursor
+ *     await Durable.workflow.continueAsNew(batch.nextCursor, totalProcessed + batch.items.length);
+ *   }
+ *   // No more items — workflow completes naturally
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Periodic polling workflow
+ * export async function poller(resourceId: string, attempt = 0): Promise<string> {
+ *   const { checkStatus } = Durable.workflow.proxyActivities<typeof activities>({
+ *     activities,
+ *     retry: { maximumAttempts: 3 },
+ *   });
+ *
+ *   const status = await checkStatus(resourceId);
+ *   if (status === 'ready') return status;
+ *
+ *   await Durable.workflow.sleep('30 seconds');
+ *
+ *   // Reset history on each poll iteration
+ *   await Durable.workflow.continueAsNew(resourceId, attempt + 1);
+ * }
+ * ```
+ *
+ * @param {...any[]} args - The arguments to pass to the new workflow execution.
+ *   These become the workflow function's parameters on restart.
+ * @returns {Promise<never>} Never returns — always throws an internal interruption.
+ */
+export declare function continueAsNew(...args: any[]): Promise<never>;

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

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.continueAsNew = void 0;
+const common_1 = require("./common");
+const cancellationScope_1 = require("./cancellationScope");
+/**
+ * Completes the current workflow execution and immediately starts a new
+ * execution of the same workflow with the provided arguments. The execution
+ * history is reset, preventing unbounded state growth in long-running
+ * workflows.
+ *
+ * `continueAsNew` never returns — it always throws an internal interruption
+ * error that the engine catches to orchestrate the restart. Any code after
+ * the call is unreachable.
+ *
+ * ## When to Use
+ *
+ * Use `continueAsNew` for workflows that would otherwise run indefinitely
+ * and accumulate unbounded replay history:
+ * - Polling loops
+ * - Subscription renewals
+ * - Iterative processing with cursors
+ * - Long-running agents with periodic state resets
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * // Cursor-based batch processor
+ * export async function batchProcessor(cursor: string, totalProcessed = 0): Promise<void> {
+ *   const { fetchBatch, processBatch } = Durable.workflow.proxyActivities<typeof activities>({
+ *     activities,
+ *     retry: { maximumAttempts: 3 },
+ *   });
+ *
+ *   const batch = await fetchBatch(cursor);
+ *   await processBatch(batch.items);
+ *
+ *   if (batch.nextCursor) {
+ *     // Restart with fresh history, carrying forward the cursor
+ *     await Durable.workflow.continueAsNew(batch.nextCursor, totalProcessed + batch.items.length);
+ *   }
+ *   // No more items — workflow completes naturally
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Periodic polling workflow
+ * export async function poller(resourceId: string, attempt = 0): Promise<string> {
+ *   const { checkStatus } = Durable.workflow.proxyActivities<typeof activities>({
+ *     activities,
+ *     retry: { maximumAttempts: 3 },
+ *   });
+ *
+ *   const status = await checkStatus(resourceId);
+ *   if (status === 'ready') return status;
+ *
+ *   await Durable.workflow.sleep('30 seconds');
+ *
+ *   // Reset history on each poll iteration
+ *   await Durable.workflow.continueAsNew(resourceId, attempt + 1);
+ * }
+ * ```
+ *
+ * @param {...any[]} args - The arguments to pass to the new workflow execution.
+ *   These become the workflow function's parameters on restart.
+ * @returns {Promise<never>} Never returns — always throws an internal interruption.
+ */
+async function continueAsNew(...args) {
+    const store = common_1.asyncLocalStorage.getStore();
+    (0, cancellationScope_1.checkCancellation)();
+    const interruptionRegistry = store.get('interruptionRegistry');
+    const workflowId = store.get('workflowId');
+    const workflowDimension = store.get('workflowDimension') ?? '';
+    const counter = store.get('counter');
+    const execIndex = (counter.counter = counter.counter + 1);
+    const payload = {
+        arguments: args,
+        index: execIndex,
+        workflowDimension,
+        workflowId,
+    };
+    interruptionRegistry.push({
+        code: common_1.HMSH_CODE_DURABLE_CONTINUE,
+        type: 'DurableContinueAsNewError',
+        ...payload,
+    });
+    await (0, common_1.sleepImmediate)();
+    throw new common_1.DurableContinueAsNewError(payload);
+}
+exports.continueAsNew = continueAsNew;

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

@@ -1,13 +1,13 @@
 /**
  * The core of the deterministic replay mechanism. Every durable operation
- * (`proxyActivities`, `execChild`, `sleepFor`, `waitFor`, etc.) calls
+ * (`proxyActivities`, `executeChild`, `sleep`, `condition`, etc.) calls
  * `didRun` before executing. It increments a shared counter to produce
  * a unique `sessionId` of the form `-{prefix}{dimension}-{index}-`.
  *
  * If that `sessionId` already exists in the `replay` hash (loaded from
  * the job's stored state), the previously persisted result is
  * deserialized and returned — skipping re-execution entirely. This is
- * analogous to Temporal's event history replay.
+ * analogous to event history replay in durable workflow engines.
  *
  * ## Session ID Format
  *