@hotmeshio/hotmesh 0.8.0 → 0.10.0

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

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hook = void 0;
+const common_1 = require("./common");
+const context_1 = require("./context");
+const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
+/**
+ * Spawns a hook execution against an existing workflow job. The hook runs
+ * in an isolated dimensional thread within the target job's namespace,
+ * allowing it to read/write the same job state without interfering with
+ * the main workflow thread.
+ *
+ * This is the low-level primitive behind `execHook()`. Use `hook()`
+ * directly when you need fire-and-forget hook execution or when you
+ * manage signal coordination yourself.
+ *
+ * ## Target Resolution
+ *
+ * - If `taskQueue` and `workflowName` (or `entity`) are provided, the
+ *   hook targets that specific workflow type.
+ * - If neither is provided, the hook targets the **current** workflow.
+ *   However, targeting the same topic as the current workflow is
+ *   rejected to prevent infinite loops.
+ *
+ * ## Idempotency
+ *
+ * The `isSideEffectAllowed` guard ensures hooks fire exactly once —
+ * on replay, the hook is not re-spawned.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * // Fire-and-forget: spawn a hook without waiting for its result
+ * export async function notifyWorkflow(userId: string): Promise<void> {
+ *   await Durable.workflow.hook({
+ *     taskQueue: 'notifications',
+ *     workflowName: 'sendNotification',
+ *     args: [userId, 'Your order has shipped'],
+ *   });
+ *   // Continues immediately, does not wait for the hook
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Manual signal coordination (equivalent to execHook)
+ * export async function manualHookPattern(itemId: string): Promise<string> {
+ *   const signalId = `process-${itemId}`;
+ *
+ *   await Durable.workflow.hook({
+ *     taskQueue: 'processors',
+ *     workflowName: 'processItem',
+ *     args: [itemId, signalId],
+ *   });
+ *
+ *   // Manually wait for the hook to signal back
+ *   return await Durable.workflow.waitFor<string>(signalId);
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Hook with retry configuration
+ * await Durable.workflow.hook({
+ *   taskQueue: 'enrichment',
+ *   workflowName: 'enrichProfile',
+ *   args: [profileId],
+ *   config: {
+ *     maximumAttempts: 5,
+ *     backoffCoefficient: 2,
+ *     maximumInterval: '1m',
+ *   },
+ * });
+ * ```
+ *
+ * @param {HookOptions} options - Hook configuration including target workflow and arguments.
+ * @returns {Promise<string>} The resulting hook/stream ID.
+ */
+async function hook(options) {
+    const { workflowId, connection, namespace, workflowTopic } = (0, context_1.getContext)();
+    const hotMeshClient = await common_1.WorkerService.getHotMesh(workflowTopic, {
+        connection,
+        namespace,
+    });
+    if (await (0, isSideEffectAllowed_1.isSideEffectAllowed)(hotMeshClient, 'hook')) {
+        const targetWorkflowId = options.workflowId ?? workflowId;
+        let targetTopic;
+        if (options.entity || (options.taskQueue && options.workflowName)) {
+            targetTopic = `${options.taskQueue ?? options.entity}-${options.entity ?? options.workflowName}`;
+        }
+        else {
+            targetTopic = workflowTopic;
+        }
+        // DEFENSIVE CHECK: Prevent infinite loops
+        if (targetTopic === workflowTopic &&
+            !options.entity &&
+            !options.taskQueue) {
+            throw new Error(`Durable Hook Error: Potential infinite loop detected!\n\n` +
+                `The hook would target the same workflow topic ('${workflowTopic}') as the current workflow, ` +
+                `creating an infinite loop.\n\n` +
+                `To fix this, provide either:\n` +
+                `1. 'taskQueue' parameter: Durable.workflow.hook({ taskQueue: 'your-queue', workflowName: '${options.workflowName}', args: [...] })\n` +
+                `2. 'entity' parameter: Durable.workflow.hook({ entity: 'your-entity', args: [...] })\n\n` +
+                `Current workflow topic: ${workflowTopic}\n` +
+                `Target topic would be: ${targetTopic}\n` +
+                `Provided options: ${JSON.stringify({
+                    workflowName: options.workflowName,
+                    taskQueue: options.taskQueue,
+                    entity: options.entity,
+                }, null, 2)}`);
+        }
+        const payload = {
+            arguments: [...options.args],
+            id: targetWorkflowId,
+            workflowTopic: targetTopic,
+            backoffCoefficient: options.config?.backoffCoefficient || common_1.HMSH_DURABLE_EXP_BACKOFF,
+            maximumAttempts: options.config?.maximumAttempts || common_1.HMSH_DURABLE_MAX_ATTEMPTS,
+            maximumInterval: (0, common_1.s)(options?.config?.maximumInterval ?? common_1.HMSH_DURABLE_MAX_INTERVAL),
+        };
+        return await hotMeshClient.signal(`${namespace}.flow.signal`, payload, common_1.StreamStatus.PENDING, 202);
+    }
+}
+exports.hook = hook;

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

@@ -0,0 +1,129 @@
+import { getContext } from './context';
+import { didRun } from './didRun';
+import { isSideEffectAllowed } from './isSideEffectAllowed';
+import { trace } from './trace';
+import { enrich } from './enrich';
+import { emit } from './emit';
+import { execChild, startChild } from './execChild';
+import { execHook } from './execHook';
+import { execHookBatch } from './execHookBatch';
+import { proxyActivities } from './proxyActivities';
+import { search } from './searchMethods';
+import { random } from './random';
+import { signal } from './signal';
+import { hook } from './hook';
+import { interrupt } from './interrupt';
+import { didInterrupt } from './interruption';
+import { all } from './all';
+import { sleepFor } from './sleepFor';
+import { waitFor } from './waitFor';
+import { HotMesh } from './common';
+import { entity } from './entityMethods';
+/**
+ * The workflow-internal API surface, exposed as `Durable.workflow`. Every
+ * method on this class is designed to be called **inside** a workflow
+ * function — they participate in deterministic replay and durable state
+ * management.
+ *
+ * ## Core Primitives
+ *
+ * | Method | Purpose |
+ * |--------|---------|
+ * | {@link proxyActivities} | Create durable activity proxies with retry |
+ * | {@link sleepFor} | Durable, crash-safe sleep |
+ * | {@link waitFor} | Pause until a signal is received |
+ * | {@link signal} | Send data to a waiting workflow |
+ * | {@link execChild} | Spawn and await a child workflow |
+ * | {@link startChild} | Spawn a child workflow (fire-and-forget) |
+ * | {@link execHook} | Spawn a hook and await its signal response |
+ * | {@link execHookBatch} | Spawn multiple hooks in parallel |
+ * | {@link hook} | Low-level hook spawning |
+ * | {@link interrupt} | Terminate a running workflow |
+ *
+ * ## Data & Observability
+ *
+ * | Method | Purpose |
+ * |--------|---------|
+ * | {@link search} | Read/write flat HASH key-value data |
+ * | {@link enrich} | One-shot HASH enrichment |
+ * | {@link entity} | Structured JSONB document storage |
+ * | {@link emit} | Publish events to the event bus |
+ * | {@link trace} | Emit OpenTelemetry trace spans |
+ *
+ * ## Utilities
+ *
+ * | Method | Purpose |
+ * |--------|---------|
+ * | {@link getContext} | Access workflow ID, namespace, replay state |
+ * | {@link random} | Deterministic pseudo-random numbers |
+ * | {@link all} | Workflow-safe `Promise.all` |
+ * | {@link didInterrupt} | Type guard for engine control-flow errors |
+ *
+ * ## Example
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * import * as activities from './activities';
+ *
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   // Proxy activities for durable execution
+ *   const { validateOrder, processPayment, sendReceipt } =
+ *     Durable.workflow.proxyActivities<typeof activities>({
+ *       activities,
+ *       retryPolicy: { maximumAttempts: 3 },
+ *     });
+ *
+ *   await validateOrder(orderId);
+ *
+ *   // Durable sleep (survives restarts)
+ *   await Durable.workflow.sleepFor('5 seconds');
+ *
+ *   const receipt = await processPayment(orderId);
+ *
+ *   // Store searchable metadata
+ *   await Durable.workflow.enrich({ orderId, status: 'paid' });
+ *
+ *   // Wait for external approval signal
+ *   const approval = await Durable.workflow.waitFor<{ ok: boolean }>('approve');
+ *   if (!approval.ok) return 'cancelled';
+ *
+ *   await sendReceipt(orderId, receipt);
+ *   return receipt;
+ * }
+ * ```
+ */
+export declare class WorkflowService {
+    /**
+     * @private
+     * The constructor is private to prevent instantiation;
+     * all methods are static.
+     */
+    private constructor();
+    static getContext: typeof getContext;
+    static didRun: typeof didRun;
+    static isSideEffectAllowed: typeof isSideEffectAllowed;
+    static trace: typeof trace;
+    static enrich: typeof enrich;
+    static emit: typeof emit;
+    static execChild: typeof execChild;
+    static executeChild: typeof execChild;
+    static startChild: typeof startChild;
+    static execHook: typeof execHook;
+    static execHookBatch: typeof execHookBatch;
+    static proxyActivities: typeof proxyActivities;
+    static search: typeof search;
+    static entity: typeof entity;
+    static random: typeof random;
+    static signal: typeof signal;
+    static hook: typeof hook;
+    static didInterrupt: typeof didInterrupt;
+    static interrupt: typeof interrupt;
+    static all: typeof all;
+    static sleepFor: typeof sleepFor;
+    static waitFor: typeof waitFor;
+    /**
+     * Return a handle to the HotMesh client hosting the workflow execution.
+     * @returns {Promise<HotMesh>} The HotMesh client instance.
+     */
+    static getHotMesh(): Promise<HotMesh>;
+}

package/build/services/{memflow → durable}/workflow/index.js

@@ -23,20 +23,75 @@ const waitFor_1 = require("./waitFor");
 const common_1 = require("./common");
 const entityMethods_1 = require("./entityMethods");
 /**
- * The WorkflowService class provides a set of static methods to be used within a workflow function.
- * These methods ensure deterministic replay, persistence of state, and error handling across
- * re-entrant workflow executions.
+ * The workflow-internal API surface, exposed as `Durable.workflow`. Every
+ * method on this class is designed to be called **inside** a workflow
+ * function — they participate in deterministic replay and durable state
+ * management.
+ *
+ * ## Core Primitives
+ *
+ * | Method | Purpose |
+ * |--------|---------|
+ * | {@link proxyActivities} | Create durable activity proxies with retry |
+ * | {@link sleepFor} | Durable, crash-safe sleep |
+ * | {@link waitFor} | Pause until a signal is received |
+ * | {@link signal} | Send data to a waiting workflow |
+ * | {@link execChild} | Spawn and await a child workflow |
+ * | {@link startChild} | Spawn a child workflow (fire-and-forget) |
+ * | {@link execHook} | Spawn a hook and await its signal response |
+ * | {@link execHookBatch} | Spawn multiple hooks in parallel |
+ * | {@link hook} | Low-level hook spawning |
+ * | {@link interrupt} | Terminate a running workflow |
+ *
+ * ## Data & Observability
+ *
+ * | Method | Purpose |
+ * |--------|---------|
+ * | {@link search} | Read/write flat HASH key-value data |
+ * | {@link enrich} | One-shot HASH enrichment |
+ * | {@link entity} | Structured JSONB document storage |
+ * | {@link emit} | Publish events to the event bus |
+ * | {@link trace} | Emit OpenTelemetry trace spans |
+ *
+ * ## Utilities
+ *
+ * | Method | Purpose |
+ * |--------|---------|
+ * | {@link getContext} | Access workflow ID, namespace, replay state |
+ * | {@link random} | Deterministic pseudo-random numbers |
+ * | {@link all} | Workflow-safe `Promise.all` |
+ * | {@link didInterrupt} | Type guard for engine control-flow errors |
+ *
+ * ## Example
  *
- * @example
  * ```typescript
- * import { MemFlow } from '@hotmeshio/hotmesh';
+ * import { Durable } from '@hotmeshio/hotmesh';
+ * import * as activities from './activities';
+ *
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   // Proxy activities for durable execution
+ *   const { validateOrder, processPayment, sendReceipt } =
+ *     Durable.workflow.proxyActivities<typeof activities>({
+ *       activities,
+ *       retryPolicy: { maximumAttempts: 3 },
+ *     });
+ *
+ *   await validateOrder(orderId);
+ *
+ *   // Durable sleep (survives restarts)
+ *   await Durable.workflow.sleepFor('5 seconds');
+ *
+ *   const receipt = await processPayment(orderId);
+ *
+ *   // Store searchable metadata
+ *   await Durable.workflow.enrich({ orderId, status: 'paid' });
+ *
+ *   // Wait for external approval signal
+ *   const approval = await Durable.workflow.waitFor<{ ok: boolean }>('approve');
+ *   if (!approval.ok) return 'cancelled';
  *
- * export async function waitForExample(): Promise<[boolean, number]> {
- *   const [s1, s2] = await Promise.all([
- *     MemFlow.workflow.waitFor<boolean>('my-sig-nal-1'),
- *     MemFlow.workflow.waitFor<number>('my-sig-nal-2')
- *   ]);
- *   return [s1, s2];
+ *   await sendReceipt(orderId, receipt);
+ *   return receipt;
  * }
  * ```
  */

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

@@ -0,0 +1,55 @@
+import { JobInterruptOptions } from './common';
+/**
+ * Terminates a running workflow job by its ID. The target job's status
+ * is set to an error code indicating abnormal termination, and any
+ * pending activities or timers are cancelled.
+ *
+ * This is the workflow-internal interrupt — it can only be called from
+ * within a workflow function. For external interruption, use
+ * `hotMesh.interrupt()` directly.
+ *
+ * The interrupt fires exactly once per workflow execution — the
+ * `isSideEffectAllowed` guard prevents re-interrupting on replay.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * // Cancel a child workflow from the parent
+ * export async function supervisorWorkflow(): Promise<void> {
+ *   const childId = await Durable.workflow.startChild({
+ *     taskQueue: 'workers',
+ *     workflowName: 'longTask',
+ *     args: [],
+ *   });
+ *
+ *   // Wait for a timeout, then cancel the child
+ *   await Durable.workflow.sleepFor('5 minutes');
+ *   await Durable.workflow.interrupt(childId, {
+ *     reason: 'Timed out waiting for child',
+ *     descend: true,     // also interrupt any grandchild workflows
+ *   });
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Self-interrupt on validation failure
+ * export async function validatedWorkflow(input: string): Promise<void> {
+ *   const { workflowId } = Durable.workflow.getContext();
+ *   const { validate } = Durable.workflow.proxyActivities<typeof activities>();
+ *
+ *   const isValid = await validate(input);
+ *   if (!isValid) {
+ *     await Durable.workflow.interrupt(workflowId, {
+ *       reason: 'Invalid input',
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @param {string} jobId - The ID of the workflow job to interrupt.
+ * @param {JobInterruptOptions} [options={}] - Interruption options (`reason`, `descend`, etc.).
+ * @returns {Promise<string | void>} The result of the interruption, if any.
+ */
+export declare function interrupt(jobId: string, options?: JobInterruptOptions): Promise<string | void>;

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

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interrupt = void 0;
+const common_1 = require("./common");
+const context_1 = require("./context");
+const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
+/**
+ * Terminates a running workflow job by its ID. The target job's status
+ * is set to an error code indicating abnormal termination, and any
+ * pending activities or timers are cancelled.
+ *
+ * This is the workflow-internal interrupt — it can only be called from
+ * within a workflow function. For external interruption, use
+ * `hotMesh.interrupt()` directly.
+ *
+ * The interrupt fires exactly once per workflow execution — the
+ * `isSideEffectAllowed` guard prevents re-interrupting on replay.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * // Cancel a child workflow from the parent
+ * export async function supervisorWorkflow(): Promise<void> {
+ *   const childId = await Durable.workflow.startChild({
+ *     taskQueue: 'workers',
+ *     workflowName: 'longTask',
+ *     args: [],
+ *   });
+ *
+ *   // Wait for a timeout, then cancel the child
+ *   await Durable.workflow.sleepFor('5 minutes');
+ *   await Durable.workflow.interrupt(childId, {
+ *     reason: 'Timed out waiting for child',
+ *     descend: true,     // also interrupt any grandchild workflows
+ *   });
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Self-interrupt on validation failure
+ * export async function validatedWorkflow(input: string): Promise<void> {
+ *   const { workflowId } = Durable.workflow.getContext();
+ *   const { validate } = Durable.workflow.proxyActivities<typeof activities>();
+ *
+ *   const isValid = await validate(input);
+ *   if (!isValid) {
+ *     await Durable.workflow.interrupt(workflowId, {
+ *       reason: 'Invalid input',
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @param {string} jobId - The ID of the workflow job to interrupt.
+ * @param {JobInterruptOptions} [options={}] - Interruption options (`reason`, `descend`, etc.).
+ * @returns {Promise<string | void>} The result of the interruption, if any.
+ */
+async function interrupt(jobId, options = {}) {
+    const { workflowTopic, connection, namespace } = (0, context_1.getContext)();
+    const hotMeshClient = await common_1.WorkerService.getHotMesh(workflowTopic, {
+        connection,
+        namespace,
+    });
+    if (await (0, isSideEffectAllowed_1.isSideEffectAllowed)(hotMeshClient, 'interrupt')) {
+        return await hotMeshClient.interrupt(`${hotMeshClient.appId}.execute`, jobId, options);
+    }
+}
+exports.interrupt = interrupt;

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

@@ -0,0 +1,61 @@
+/**
+ * Type guard that returns `true` if an error is a Durable engine
+ * control-flow signal rather than a genuine application error.
+ *
+ * Durable uses thrown errors internally to suspend workflow execution
+ * for durable operations like `sleepFor`, `waitFor`, `proxyActivities`,
+ * and `execChild`. These errors must be re-thrown (not swallowed) so
+ * the engine can persist state and schedule the next step.
+ *
+ * **Always use `didInterrupt` in `catch` blocks inside workflow
+ * functions** to avoid accidentally swallowing engine signals.
+ *
+ * ## Recognized Error Types
+ *
+ * `DurableChildError`, `DurableFatalError`, `DurableMaxedError`,
+ * `DurableProxyError`, `DurableRetryError`, `DurableSleepError`,
+ * `DurableTimeoutError`, `DurableWaitForError`, `DurableWaitForAllError`
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function safeWorkflow(): Promise<string> {
+ *   const { riskyOperation } = Durable.workflow.proxyActivities<typeof activities>();
+ *
+ *   try {
+ *     return await riskyOperation();
+ *   } catch (error) {
+ *     // CRITICAL: re-throw engine signals
+ *     if (Durable.workflow.didInterrupt(error)) {
+ *       throw error;
+ *     }
+ *     // Handle real application errors
+ *     return 'fallback-value';
+ *   }
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Common pattern in interceptors
+ * const interceptor: WorkflowInterceptor = {
+ *   async execute(ctx, next) {
+ *     try {
+ *       return await next();
+ *     } catch (error) {
+ *       if (Durable.workflow.didInterrupt(error)) {
+ *         throw error;  // always re-throw engine signals
+ *       }
+ *       // Log and re-throw application errors
+ *       console.error('Workflow failed:', error);
+ *       throw error;
+ *     }
+ *   },
+ * };
+ * ```
+ *
+ * @param {Error} error - The error to check.
+ * @returns {boolean} `true` if the error is a Durable engine interruption signal.
+ */
+export declare function didInterrupt(error: Error): boolean;

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

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.didInterrupt = void 0;
+const errors_1 = require("../../../modules/errors");
+/**
+ * Type guard that returns `true` if an error is a Durable engine
+ * control-flow signal rather than a genuine application error.
+ *
+ * Durable uses thrown errors internally to suspend workflow execution
+ * for durable operations like `sleepFor`, `waitFor`, `proxyActivities`,
+ * and `execChild`. These errors must be re-thrown (not swallowed) so
+ * the engine can persist state and schedule the next step.
+ *
+ * **Always use `didInterrupt` in `catch` blocks inside workflow
+ * functions** to avoid accidentally swallowing engine signals.
+ *
+ * ## Recognized Error Types
+ *
+ * `DurableChildError`, `DurableFatalError`, `DurableMaxedError`,
+ * `DurableProxyError`, `DurableRetryError`, `DurableSleepError`,
+ * `DurableTimeoutError`, `DurableWaitForError`, `DurableWaitForAllError`
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function safeWorkflow(): Promise<string> {
+ *   const { riskyOperation } = Durable.workflow.proxyActivities<typeof activities>();
+ *
+ *   try {
+ *     return await riskyOperation();
+ *   } catch (error) {
+ *     // CRITICAL: re-throw engine signals
+ *     if (Durable.workflow.didInterrupt(error)) {
+ *       throw error;
+ *     }
+ *     // Handle real application errors
+ *     return 'fallback-value';
+ *   }
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Common pattern in interceptors
+ * const interceptor: WorkflowInterceptor = {
+ *   async execute(ctx, next) {
+ *     try {
+ *       return await next();
+ *     } catch (error) {
+ *       if (Durable.workflow.didInterrupt(error)) {
+ *         throw error;  // always re-throw engine signals
+ *       }
+ *       // Log and re-throw application errors
+ *       console.error('Workflow failed:', error);
+ *       throw error;
+ *     }
+ *   },
+ * };
+ * ```
+ *
+ * @param {Error} error - The error to check.
+ * @returns {boolean} `true` if the error is a Durable engine interruption signal.
+ */
+function didInterrupt(error) {
+    return (error instanceof errors_1.DurableChildError ||
+        error instanceof errors_1.DurableFatalError ||
+        error instanceof errors_1.DurableMaxedError ||
+        error instanceof errors_1.DurableProxyError ||
+        error instanceof errors_1.DurableRetryError ||
+        error instanceof errors_1.DurableSleepError ||
+        error instanceof errors_1.DurableTimeoutError ||
+        error instanceof errors_1.DurableWaitForError ||
+        error instanceof errors_1.DurableWaitForAllError);
+}
+exports.didInterrupt = didInterrupt;

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

@@ -0,0 +1,27 @@
+import { HotMesh } from './common';
+/**
+ * Guards side-effectful operations (`emit`, `signal`, `hook`, `trace`,
+ * `interrupt`) against duplicate execution during replay. Unlike
+ * `didRun()` (which replays stored results), this guard is for
+ * operations that don't produce a return value to cache — they simply
+ * must not run twice.
+ *
+ * ## Mechanism
+ *
+ * 1. Increments the execution counter to produce a `sessionId`.
+ * 2. If that `sessionId` already exists in the `replay` hash, the
+ *    operation already ran in a previous execution → return `false`.
+ * 3. Otherwise, atomically increments a field on the job's backend
+ *    HASH via `incrementFieldByFloat`. If the result is exactly `1`,
+ *    this is the first worker to reach this point → return `true`.
+ *    If `> 1`, a concurrent worker already executed it → return `false`.
+ *
+ * This provides **distributed idempotency** for side effects across
+ * replays and concurrent worker instances.
+ *
+ * @private
+ * @param {HotMesh} hotMeshClient - The HotMesh client.
+ * @param {string} prefix - Operation type (`'trace'`, `'emit'`, `'signal'`, `'hook'`, `'interrupt'`).
+ * @returns {Promise<boolean>} `true` if the side effect should execute, `false` if it already ran.
+ */
+export declare function isSideEffectAllowed(hotMeshClient: HotMesh, prefix: string): Promise<boolean>;

package/build/services/{memflow → durable}/workflow/isSideEffectAllowed.js

@@ -3,12 +3,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSideEffectAllowed = void 0;
 const common_1 = require("./common");
 /**
- * Checks if a side-effect is allowed to run. This ensures certain actions
- * are executed exactly once.
+ * Guards side-effectful operations (`emit`, `signal`, `hook`, `trace`,
+ * `interrupt`) against duplicate execution during replay. Unlike
+ * `didRun()` (which replays stored results), this guard is for
+ * operations that don't produce a return value to cache — they simply
+ * must not run twice.
+ *
+ * ## Mechanism
+ *
+ * 1. Increments the execution counter to produce a `sessionId`.
+ * 2. If that `sessionId` already exists in the `replay` hash, the
+ *    operation already ran in a previous execution → return `false`.
+ * 3. Otherwise, atomically increments a field on the job's backend
+ *    HASH via `incrementFieldByFloat`. If the result is exactly `1`,
+ *    this is the first worker to reach this point → return `true`.
+ *    If `> 1`, a concurrent worker already executed it → return `false`.
+ *
+ * This provides **distributed idempotency** for side effects across
+ * replays and concurrent worker instances.
+ *
  * @private
  * @param {HotMesh} hotMeshClient - The HotMesh client.
- * @param {string} prefix - A unique prefix representing the action (e.g., 'trace', 'emit', etc.)
- * @returns {Promise<boolean>} True if the side effect can run, false otherwise.
+ * @param {string} prefix - Operation type (`'trace'`, `'emit'`, `'signal'`, `'hook'`, `'interrupt'`).
+ * @returns {Promise<boolean>} `true` if the side effect should execute, `false` if it already ran.
  */
 async function isSideEffectAllowed(hotMeshClient, prefix) {
     const store = common_1.asyncLocalStorage.getStore();