@hotmeshio/hotmesh 0.7.0 → 0.9.0

package/build/services/memflow/workflow/execHookBatch.js

@@ -4,47 +4,99 @@ exports.execHookBatch = void 0;
 const hook_1 = require("./hook");
 const waitFor_1 = require("./waitFor");
 /**
- * Executes multiple hooks in parallel and awaits all their signal responses.
- * This solves the race condition where Promise.all() with execHook() would prevent
- * all waitFor() registrations from completing.
+ * Executes multiple hooks in parallel and awaits all their signal responses,
+ * returning a keyed object of results. This is the recommended way to run
+ * concurrent hooks — it solves a race condition where calling
+ * `Promise.all([execHook(), execHook()])` would throw before all `waitFor`
+ * registrations complete.
  *
- * The method ensures all waitFor() registrations happen before any hooks execute,
- * preventing signals from being sent before the framework is ready to receive them.
+ * ## Three-Phase Execution
  *
- * @template T - Object type with keys matching the batch hook keys and values as expected response types
- * @param {BatchHookConfig[]} hookConfigs - Array of hook configurations with unique keys
- * @returns {Promise<T>} Object with keys from hookConfigs and values as the signal responses
+ * 1. **Fire all hooks** via `Promise.all` (registers streams immediately).
+ * 2. **Await all signals** via `Promise.all` (all `waitFor` registrations
+ *    happen together before any `MemFlowWaitForError` is thrown).
+ * 3. **Combine results** into a `{ [key]: result }` map.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Fan-out to multiple AI agents, gather all perspectives
+ * export async function researchWorkflow(query: string): Promise<Summary> {
+ *   const perspectives = await MemFlow.workflow.execHookBatch<{
+ *     optimistic: PerspectiveResult;
+ *     skeptical: PerspectiveResult;
+ *     neutral: PerspectiveResult;
+ *   }>([
+ *     {
+ *       key: 'optimistic',
+ *       options: {
+ *         taskQueue: 'agents',
+ *         workflowName: 'analyzeOptimistic',
+ *         args: [query],
+ *       },
+ *     },
+ *     {
+ *       key: 'skeptical',
+ *       options: {
+ *         taskQueue: 'agents',
+ *         workflowName: 'analyzeSkeptical',
+ *         args: [query],
+ *       },
+ *     },
+ *     {
+ *       key: 'neutral',
+ *       options: {
+ *         taskQueue: 'agents',
+ *         workflowName: 'analyzeNeutral',
+ *         args: [query],
+ *       },
+ *     },
+ *   ]);
+ *
+ *   // All three results are available as typed properties
+ *   const { synthesize } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   return await synthesize(
+ *     perspectives.optimistic,
+ *     perspectives.skeptical,
+ *     perspectives.neutral,
+ *   );
+ * }
+ * ```
  *
- * @example
  * ```typescript
- * // Execute multiple research perspectives in parallel
- * const results = await MemFlow.workflow.execHookBatch<{
- *   optimistic: OptimisticResult;
- *   skeptical: SkepticalResult;
+ * // Parallel validation with different services
+ * const checks = await MemFlow.workflow.execHookBatch<{
+ *   fraud: { safe: boolean };
+ *   compliance: { approved: boolean };
  * }>([
  *   {
- *     key: 'optimistic',
+ *     key: 'fraud',
  *     options: {
- *       taskQueue: 'agents',
- *       workflowName: 'optimisticPerspective',
- *       args: [query],
- *       signalId: 'optimistic-complete'
- *     }
+ *       taskQueue: 'fraud-detection',
+ *       workflowName: 'checkFraud',
+ *       args: [transactionId],
+ *     },
  *   },
  *   {
- *     key: 'skeptical',
+ *     key: 'compliance',
  *     options: {
- *       taskQueue: 'agents',
- *       workflowName: 'skepticalPerspective',
- *       args: [query],
- *       signalId: 'skeptical-complete'
- *     }
- *   }
+ *       taskQueue: 'compliance',
+ *       workflowName: 'checkCompliance',
+ *       args: [transactionId],
+ *     },
+ *   },
  * ]);
  *
- * // results.optimistic contains the OptimisticResult
- * // results.skeptical contains the SkepticalResult
+ * if (checks.fraud.safe && checks.compliance.approved) {
+ *   // proceed with transaction
+ * }
  * ```
+ *
+ * @template T - Object type with keys matching the batch hook keys.
+ * @param {BatchHookConfig[]} hookConfigs - Array of hook configurations with unique keys.
+ * @returns {Promise<T>} Object mapping each config's `key` to its signal response.
  */
 async function execHookBatch(hookConfigs) {
     // Generate signal IDs for hooks that don't have them

package/build/services/memflow/workflow/hook.d.ts

@@ -1,9 +1,74 @@
 import { HookOptions } from './common';
 /**
- * Spawns a hook from the main thread or a hook thread.
- * If entity/workflowName are not provided, defaults to the current workflow.
+ * 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.
  *
- * @param {HookOptions} options - Hook configuration options.
+ * 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 { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Fire-and-forget: spawn a hook without waiting for its result
+ * export async function notifyWorkflow(userId: string): Promise<void> {
+ *   await MemFlow.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 MemFlow.workflow.hook({
+ *     taskQueue: 'processors',
+ *     workflowName: 'processItem',
+ *     args: [itemId, signalId],
+ *   });
+ *
+ *   // Manually wait for the hook to signal back
+ *   return await MemFlow.workflow.waitFor<string>(signalId);
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Hook with retry configuration
+ * await MemFlow.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.
  */
 export declare function hook(options: HookOptions): Promise<string>;

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

@@ -5,10 +5,75 @@ const common_1 = require("./common");
 const context_1 = require("./context");
 const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
 /**
- * Spawns a hook from the main thread or a hook thread.
- * If entity/workflowName are not provided, defaults to the current workflow.
+ * 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.
  *
- * @param {HookOptions} options - Hook configuration options.
+ * 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 { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Fire-and-forget: spawn a hook without waiting for its result
+ * export async function notifyWorkflow(userId: string): Promise<void> {
+ *   await MemFlow.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 MemFlow.workflow.hook({
+ *     taskQueue: 'processors',
+ *     workflowName: 'processItem',
+ *     args: [itemId, signalId],
+ *   });
+ *
+ *   // Manually wait for the hook to signal back
+ *   return await MemFlow.workflow.waitFor<string>(signalId);
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Hook with retry configuration
+ * await MemFlow.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) {
@@ -52,7 +117,7 @@ async function hook(options) {
             maximumAttempts: options.config?.maximumAttempts || common_1.HMSH_MEMFLOW_MAX_ATTEMPTS,
             maximumInterval: (0, common_1.s)(options?.config?.maximumInterval ?? common_1.HMSH_MEMFLOW_MAX_INTERVAL),
         };
-        return await hotMeshClient.hook(`${namespace}.flow.signal`, payload, common_1.StreamStatus.PENDING, 202);
+        return await hotMeshClient.signal(`${namespace}.flow.signal`, payload, common_1.StreamStatus.PENDING, 202);
     }
 }
 exports.hook = hook;

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

@@ -20,20 +20,75 @@ import { waitFor } from './waitFor';
 import { HotMesh } from './common';
 import { entity } from './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 `MemFlow.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 * as activities from './activities';
+ *
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   // Proxy activities for durable execution
+ *   const { validateOrder, processPayment, sendReceipt } =
+ *     MemFlow.workflow.proxyActivities<typeof activities>({
+ *       activities,
+ *       retryPolicy: { maximumAttempts: 3 },
+ *     });
+ *
+ *   await validateOrder(orderId);
+ *
+ *   // Durable sleep (survives restarts)
+ *   await MemFlow.workflow.sleepFor('5 seconds');
+ *
+ *   const receipt = await processPayment(orderId);
+ *
+ *   // Store searchable metadata
+ *   await MemFlow.workflow.enrich({ orderId, status: 'paid' });
+ *
+ *   // Wait for external approval signal
+ *   const approval = await MemFlow.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/memflow/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 `MemFlow.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 * as activities from './activities';
+ *
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   // Proxy activities for durable execution
+ *   const { validateOrder, processPayment, sendReceipt } =
+ *     MemFlow.workflow.proxyActivities<typeof activities>({
+ *       activities,
+ *       retryPolicy: { maximumAttempts: 3 },
+ *     });
+ *
+ *   await validateOrder(orderId);
+ *
+ *   // Durable sleep (survives restarts)
+ *   await MemFlow.workflow.sleepFor('5 seconds');
+ *
+ *   const receipt = await processPayment(orderId);
+ *
+ *   // Store searchable metadata
+ *   await MemFlow.workflow.enrich({ orderId, status: 'paid' });
+ *
+ *   // Wait for external approval signal
+ *   const approval = await MemFlow.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/memflow/workflow/interrupt.d.ts

@@ -1,9 +1,55 @@
 import { JobInterruptOptions } from './common';
 /**
- * Interrupts a running job by sending an interruption request.
+ * 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.
  *
- * @param {string} jobId - The ID of the job to interrupt.
- * @param {JobInterruptOptions} options - Additional interruption options.
- * @returns {Promise<string|void>} Result of the interruption, if any.
+ * 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 { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Cancel a child workflow from the parent
+ * export async function supervisorWorkflow(): Promise<void> {
+ *   const childId = await MemFlow.workflow.startChild({
+ *     taskQueue: 'workers',
+ *     workflowName: 'longTask',
+ *     args: [],
+ *   });
+ *
+ *   // Wait for a timeout, then cancel the child
+ *   await MemFlow.workflow.sleepFor('5 minutes');
+ *   await MemFlow.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 } = MemFlow.workflow.getContext();
+ *   const { validate } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *
+ *   const isValid = await validate(input);
+ *   if (!isValid) {
+ *     await MemFlow.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/memflow/workflow/interrupt.js

@@ -5,11 +5,57 @@ const common_1 = require("./common");
 const context_1 = require("./context");
 const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
 /**
- * Interrupts a running job by sending an interruption request.
+ * 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.
  *
- * @param {string} jobId - The ID of the job to interrupt.
- * @param {JobInterruptOptions} options - Additional interruption options.
- * @returns {Promise<string|void>} Result of the interruption, if any.
+ * 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 { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Cancel a child workflow from the parent
+ * export async function supervisorWorkflow(): Promise<void> {
+ *   const childId = await MemFlow.workflow.startChild({
+ *     taskQueue: 'workers',
+ *     workflowName: 'longTask',
+ *     args: [],
+ *   });
+ *
+ *   // Wait for a timeout, then cancel the child
+ *   await MemFlow.workflow.sleepFor('5 minutes');
+ *   await MemFlow.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 } = MemFlow.workflow.getContext();
+ *   const { validate } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *
+ *   const isValid = await validate(input);
+ *   if (!isValid) {
+ *     await MemFlow.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)();

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

@@ -1,28 +1,61 @@
 /**
- * Checks if an error is a HotMesh reserved error type that indicates
- * a HotMesh interruption rather than a true error condition.
+ * Type guard that returns `true` if an error is a MemFlow engine
+ * control-flow signal rather than a genuine application error.
  *
- * When this returns true, you can safely return rethrow the error.
- * The workflow engine will handle the interruption automatically.
+ * MemFlow 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
+ *
+ * `MemFlowChildError`, `MemFlowFatalError`, `MemFlowMaxedError`,
+ * `MemFlowProxyError`, `MemFlowRetryError`, `MemFlowSleepError`,
+ * `MemFlowTimeoutError`, `MemFlowWaitForError`, `MemFlowWaitForAllError`
+ *
+ * ## Examples
  *
- * @example
  * ```typescript
  * import { MemFlow } from '@hotmeshio/hotmesh';
  *
- * try {
- *   await someWorkflowOperation();
- * } catch (error) {
- *   // Check if this is a HotMesh interruption
- *   if (MemFlow.workflow.didInterrupt(error)) {
- *     // Rethrow the error
- *     throw error;
+ * export async function safeWorkflow(): Promise<string> {
+ *   const { riskyOperation } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *
+ *   try {
+ *     return await riskyOperation();
+ *   } catch (error) {
+ *     // CRITICAL: re-throw engine signals
+ *     if (MemFlow.workflow.didInterrupt(error)) {
+ *       throw error;
+ *     }
+ *     // Handle real application errors
+ *     return 'fallback-value';
  *   }
- *   // Handle actual error
- *   console.error('Workflow failed:', error);
  * }
  * ```
  *
- * @param error - The error to check
- * @returns true if the error is a HotMesh interruption
+ * ```typescript
+ * // Common pattern in interceptors
+ * const interceptor: WorkflowInterceptor = {
+ *   async execute(ctx, next) {
+ *     try {
+ *       return await next();
+ *     } catch (error) {
+ *       if (MemFlow.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 MemFlow engine interruption signal.
  */
 export declare function didInterrupt(error: Error): boolean;