@hotmeshio/hotmesh 0.7.0 → 0.9.0

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

@@ -3,31 +3,64 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.didInterrupt = void 0;
 const errors_1 = require("../../../modules/errors");
 /**
- * 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.
  */
 function didInterrupt(error) {
     return (error instanceof errors_1.MemFlowChildError ||

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

@@ -1,10 +1,27 @@
 import { HotMesh } from './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.
  */
 export declare function isSideEffectAllowed(hotMeshClient: HotMesh, prefix: string): Promise<boolean>;

package/build/services/memflow/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();

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

@@ -11,81 +11,109 @@ declare function getProxyInterruptPayload(context: ReturnType<typeof getContext>
  */
 declare function wrapActivity<T>(activityName: string, options?: ActivityConfig): T;
 /**
- * Create proxies for activity functions with automatic retry and deterministic replay.
- * Activities execute via message queue, so they can run on different servers.
+ * Creates a typed proxy for calling activity functions with durable execution,
+ * automatic retry, and deterministic replay. This is the primary way to invoke
+ * side-effectful code (HTTP calls, database writes, file I/O) from within a
+ * workflow function.
  *
- * Without `taskQueue`, activities use the workflow's task queue (e.g., `my-workflow-activity`).
- * With `taskQueue`, activities use the specified queue (e.g., `payment-activity`).
+ * Activities execute on a **separate worker process** via message queue,
+ * isolating side effects from the deterministic workflow function. Each
+ * proxied call is assigned a unique execution index, and on replay the
+ * stored result is returned without re-executing the activity.
  *
- * The `activities` parameter is optional. If activities are already registered via
- * `registerActivityWorker()`, you can reference them by providing just the `taskQueue`
- * and a TypeScript interface.
+ * ## Routing
  *
- * @template ACT
- * @param {ActivityConfig} [options] - Activity configuration
- * @param {any} [options.activities] - (Optional) Activity functions to register inline
- * @param {string} [options.taskQueue] - (Optional) Task queue name (without `-activity` suffix)
- * @param {object} [options.retryPolicy] - Retry configuration
- * @returns {ProxyType<ACT>} Proxy for calling activities with durability and retry
+ * - **Default**: Activities route to `{workflowTaskQueue}-activity`.
+ * - **Explicit `taskQueue`**: Activities route to `{taskQueue}-activity`,
+ *   enabling shared/global activity worker pools across workflows.
+ *
+ * ## Retry Policy
+ *
+ * | Option               | Default | Description |
+ * |----------------------|---------|-------------|
+ * | `maximumAttempts`    | 50      | Max retries before the activity is marked as failed |
+ * | `backoffCoefficient` | 2       | Exponential backoff multiplier |
+ * | `maximumInterval`    | `'5m'`  | Cap on delay between retries |
+ * | `throwOnError`       | `true`  | Throw on activity failure (set `false` to return the error) |
+ *
+ * ## Examples
  *
- * @example
  * ```typescript
- * // Inline registration (activities in same codebase)
- * const activities = MemFlow.workflow.proxyActivities<typeof activities>({
- *   activities: { processData, validateData },
- *   retryPolicy: { maximumAttempts: 3 }
- * });
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ * import * as activities from './activities';
+ *
+ * // Standard pattern: register and proxy activities inline
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   const { validateOrder, chargePayment, sendConfirmation } =
+ *     MemFlow.workflow.proxyActivities<typeof activities>({
+ *       activities,
+ *       retryPolicy: {
+ *         maximumAttempts: 3,
+ *         backoffCoefficient: 2,
+ *         maximumInterval: '30s',
+ *       },
+ *     });
  *
- * await activities.processData('input');
+ *   await validateOrder(orderId);
+ *   const receipt = await chargePayment(orderId);
+ *   await sendConfirmation(orderId, receipt);
+ *   return receipt;
+ * }
  * ```
  *
- * @example
  * ```typescript
- * // Reference pre-registered activities (can be on different server)
+ * // Remote activities: reference a pre-registered worker pool by taskQueue
  * interface PaymentActivities {
  *   processPayment: (amount: number) => Promise<string>;
- *   sendEmail: (to: string, subject: string) => Promise<void>;
+ *   refundPayment: (txId: string) => Promise<void>;
  * }
  *
- * const { processPayment, sendEmail } =
- *   MemFlow.workflow.proxyActivities<PaymentActivities>({
- *     taskQueue: 'payment',
- *     retryPolicy: { maximumAttempts: 3 }
- *   });
+ * export async function refundWorkflow(txId: string): Promise<void> {
+ *   const { refundPayment } =
+ *     MemFlow.workflow.proxyActivities<PaymentActivities>({
+ *       taskQueue: 'payments',
+ *       retryPolicy: { maximumAttempts: 5 },
+ *     });
  *
- * const result = await processPayment(100.00);
- * await sendEmail('user@example.com', 'Payment processed');
+ *   await refundPayment(txId);
+ * }
  * ```
  *
- * @example
  * ```typescript
- * // Shared activities in interceptor
- * const interceptor: WorkflowInterceptor = {
+ * // Interceptor with shared activity pool
+ * const auditInterceptor: WorkflowInterceptor = {
  *   async execute(ctx, next) {
  *     const { auditLog } = MemFlow.workflow.proxyActivities<{
  *       auditLog: (id: string, action: string) => Promise<void>;
  *     }>({
- *       taskQueue: 'shared',
- *       retryPolicy: { maximumAttempts: 3 }
+ *       taskQueue: 'shared-audit',
+ *       retryPolicy: { maximumAttempts: 3 },
  *     });
  *
  *     await auditLog(ctx.get('workflowId'), 'started');
  *     const result = await next();
  *     await auditLog(ctx.get('workflowId'), 'completed');
  *     return result;
- *   }
+ *   },
  * };
  * ```
  *
- * @example
  * ```typescript
- * // Custom task queue for specific activities
- * const highPriority = MemFlow.workflow.proxyActivities<typeof activities>({
- *   activities: { criticalProcess },
- *   taskQueue: 'high-priority',
- *   retryPolicy: { maximumAttempts: 5 }
+ * // Graceful error handling (no throw)
+ * const { riskyOperation } = MemFlow.workflow.proxyActivities<typeof activities>({
+ *   activities,
+ *   retryPolicy: { maximumAttempts: 1, throwOnError: false },
  * });
+ *
+ * const result = await riskyOperation();
+ * if (result instanceof Error) {
+ *   // handle gracefully
+ * }
  * ```
+ *
+ * @template ACT - The activity type map (use `typeof activities` for inline registration).
+ * @param {ActivityConfig} [options] - Activity configuration including retry policy and routing.
+ * @returns {ProxyType<ACT>} A typed proxy object mapping activity names to their durable wrappers.
  */
 export declare function proxyActivities<ACT>(options?: ActivityConfig): ProxyType<ACT>;
 export { wrapActivity, getProxyInterruptPayload };

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

@@ -81,81 +81,109 @@ function wrapActivity(activityName, options) {
 }
 exports.wrapActivity = wrapActivity;
 /**
- * Create proxies for activity functions with automatic retry and deterministic replay.
- * Activities execute via message queue, so they can run on different servers.
+ * Creates a typed proxy for calling activity functions with durable execution,
+ * automatic retry, and deterministic replay. This is the primary way to invoke
+ * side-effectful code (HTTP calls, database writes, file I/O) from within a
+ * workflow function.
  *
- * Without `taskQueue`, activities use the workflow's task queue (e.g., `my-workflow-activity`).
- * With `taskQueue`, activities use the specified queue (e.g., `payment-activity`).
+ * Activities execute on a **separate worker process** via message queue,
+ * isolating side effects from the deterministic workflow function. Each
+ * proxied call is assigned a unique execution index, and on replay the
+ * stored result is returned without re-executing the activity.
  *
- * The `activities` parameter is optional. If activities are already registered via
- * `registerActivityWorker()`, you can reference them by providing just the `taskQueue`
- * and a TypeScript interface.
+ * ## Routing
  *
- * @template ACT
- * @param {ActivityConfig} [options] - Activity configuration
- * @param {any} [options.activities] - (Optional) Activity functions to register inline
- * @param {string} [options.taskQueue] - (Optional) Task queue name (without `-activity` suffix)
- * @param {object} [options.retryPolicy] - Retry configuration
- * @returns {ProxyType<ACT>} Proxy for calling activities with durability and retry
+ * - **Default**: Activities route to `{workflowTaskQueue}-activity`.
+ * - **Explicit `taskQueue`**: Activities route to `{taskQueue}-activity`,
+ *   enabling shared/global activity worker pools across workflows.
+ *
+ * ## Retry Policy
+ *
+ * | Option               | Default | Description |
+ * |----------------------|---------|-------------|
+ * | `maximumAttempts`    | 50      | Max retries before the activity is marked as failed |
+ * | `backoffCoefficient` | 2       | Exponential backoff multiplier |
+ * | `maximumInterval`    | `'5m'`  | Cap on delay between retries |
+ * | `throwOnError`       | `true`  | Throw on activity failure (set `false` to return the error) |
+ *
+ * ## Examples
  *
- * @example
  * ```typescript
- * // Inline registration (activities in same codebase)
- * const activities = MemFlow.workflow.proxyActivities<typeof activities>({
- *   activities: { processData, validateData },
- *   retryPolicy: { maximumAttempts: 3 }
- * });
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ * import * as activities from './activities';
+ *
+ * // Standard pattern: register and proxy activities inline
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   const { validateOrder, chargePayment, sendConfirmation } =
+ *     MemFlow.workflow.proxyActivities<typeof activities>({
+ *       activities,
+ *       retryPolicy: {
+ *         maximumAttempts: 3,
+ *         backoffCoefficient: 2,
+ *         maximumInterval: '30s',
+ *       },
+ *     });
  *
- * await activities.processData('input');
+ *   await validateOrder(orderId);
+ *   const receipt = await chargePayment(orderId);
+ *   await sendConfirmation(orderId, receipt);
+ *   return receipt;
+ * }
  * ```
  *
- * @example
  * ```typescript
- * // Reference pre-registered activities (can be on different server)
+ * // Remote activities: reference a pre-registered worker pool by taskQueue
  * interface PaymentActivities {
  *   processPayment: (amount: number) => Promise<string>;
- *   sendEmail: (to: string, subject: string) => Promise<void>;
+ *   refundPayment: (txId: string) => Promise<void>;
  * }
  *
- * const { processPayment, sendEmail } =
- *   MemFlow.workflow.proxyActivities<PaymentActivities>({
- *     taskQueue: 'payment',
- *     retryPolicy: { maximumAttempts: 3 }
- *   });
+ * export async function refundWorkflow(txId: string): Promise<void> {
+ *   const { refundPayment } =
+ *     MemFlow.workflow.proxyActivities<PaymentActivities>({
+ *       taskQueue: 'payments',
+ *       retryPolicy: { maximumAttempts: 5 },
+ *     });
  *
- * const result = await processPayment(100.00);
- * await sendEmail('user@example.com', 'Payment processed');
+ *   await refundPayment(txId);
+ * }
  * ```
  *
- * @example
  * ```typescript
- * // Shared activities in interceptor
- * const interceptor: WorkflowInterceptor = {
+ * // Interceptor with shared activity pool
+ * const auditInterceptor: WorkflowInterceptor = {
  *   async execute(ctx, next) {
  *     const { auditLog } = MemFlow.workflow.proxyActivities<{
  *       auditLog: (id: string, action: string) => Promise<void>;
  *     }>({
- *       taskQueue: 'shared',
- *       retryPolicy: { maximumAttempts: 3 }
+ *       taskQueue: 'shared-audit',
+ *       retryPolicy: { maximumAttempts: 3 },
  *     });
  *
  *     await auditLog(ctx.get('workflowId'), 'started');
  *     const result = await next();
  *     await auditLog(ctx.get('workflowId'), 'completed');
  *     return result;
- *   }
+ *   },
  * };
  * ```
  *
- * @example
  * ```typescript
- * // Custom task queue for specific activities
- * const highPriority = MemFlow.workflow.proxyActivities<typeof activities>({
- *   activities: { criticalProcess },
- *   taskQueue: 'high-priority',
- *   retryPolicy: { maximumAttempts: 5 }
+ * // Graceful error handling (no throw)
+ * const { riskyOperation } = MemFlow.workflow.proxyActivities<typeof activities>({
+ *   activities,
+ *   retryPolicy: { maximumAttempts: 1, throwOnError: false },
  * });
+ *
+ * const result = await riskyOperation();
+ * if (result instanceof Error) {
+ *   // handle gracefully
+ * }
  * ```
+ *
+ * @template ACT - The activity type map (use `typeof activities` for inline registration).
+ * @param {ActivityConfig} [options] - Activity configuration including retry policy and routing.
+ * @returns {ProxyType<ACT>} A typed proxy object mapping activity names to their durable wrappers.
  */
 function proxyActivities(options) {
     // Register activities if provided (optional - may already be registered remotely)

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

@@ -1,6 +1,36 @@
 /**
- * Returns a deterministic random number between 0 and 1. The number is derived from the
- * current execution index, ensuring deterministic replay.
- * @returns {number} A deterministic pseudo-random number between 0 and 1.
+ * Returns a deterministic pseudo-random number between 0 and 1. The value
+ * is derived from the current execution counter, so it produces the
+ * **same result** on every replay of the workflow at this execution point.
+ *
+ * Use this instead of `Math.random()` inside workflow functions.
+ * `Math.random()` is non-deterministic and would break replay correctness.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Generate a deterministic unique suffix
+ * export async function uniqueWorkflow(): Promise<string> {
+ *   const suffix = Math.floor(MemFlow.workflow.random() * 10000);
+ *   return `item-${suffix}`;
+ * }
+ * ```
+ *
+ * ```typescript
+ * // A/B test routing (deterministic per workflow execution)
+ * export async function experimentWorkflow(userId: string): Promise<string> {
+ *   const { variantA, variantB } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *
+ *   if (MemFlow.workflow.random() < 0.5) {
+ *     return await variantA(userId);
+ *   } else {
+ *     return await variantB(userId);
+ *   }
+ * }
+ * ```
+ *
+ * @returns {number} A deterministic pseudo-random number in [0, 1).
  */
 export declare function random(): number;

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

@@ -3,9 +3,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.random = void 0;
 const common_1 = require("./common");
 /**
- * Returns a deterministic random number between 0 and 1. The number is derived from the
- * current execution index, ensuring deterministic replay.
- * @returns {number} A deterministic pseudo-random number between 0 and 1.
+ * Returns a deterministic pseudo-random number between 0 and 1. The value
+ * is derived from the current execution counter, so it produces the
+ * **same result** on every replay of the workflow at this execution point.
+ *
+ * Use this instead of `Math.random()` inside workflow functions.
+ * `Math.random()` is non-deterministic and would break replay correctness.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * // Generate a deterministic unique suffix
+ * export async function uniqueWorkflow(): Promise<string> {
+ *   const suffix = Math.floor(MemFlow.workflow.random() * 10000);
+ *   return `item-${suffix}`;
+ * }
+ * ```
+ *
+ * ```typescript
+ * // A/B test routing (deterministic per workflow execution)
+ * export async function experimentWorkflow(userId: string): Promise<string> {
+ *   const { variantA, variantB } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *
+ *   if (MemFlow.workflow.random() < 0.5) {
+ *     return await variantA(userId);
+ *   } else {
+ *     return await variantB(userId);
+ *   }
+ * }
+ * ```
+ *
+ * @returns {number} A deterministic pseudo-random number in [0, 1).
  */
 function random() {
     const store = common_1.asyncLocalStorage.getStore();

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

@@ -1,6 +1,53 @@
 import { Search } from './common';
 /**
- * Returns a search session handle for interacting with the workflow's HASH storage.
- * @returns {Promise<Search>} A search session for workflow data.
+ * Returns a `Search` session handle for reading and writing key-value data
+ * on the workflow's backend HASH record. Search fields are flat string
+ * key-value pairs stored alongside the job state, making them queryable
+ * via `MemFlow.Client.workflow.search()` (FT.SEARCH).
+ *
+ * Each call produces a unique session ID tied to the deterministic
+ * execution counter, ensuring correct replay behavior.
+ *
+ * Use `search()` for flat, indexable key-value data. For structured
+ * JSON documents, use `entity()` instead.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * export async function orderWorkflow(orderId: string): Promise<void> {
+ *   const search = await MemFlow.workflow.search();
+ *
+ *   // Write searchable fields
+ *   await search.set({
+ *     orderId,
+ *     status: 'processing',
+ *     createdAt: new Date().toISOString(),
+ *   });
+ *
+ *   const { processOrder } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   await processOrder(orderId);
+ *
+ *   // Update status
+ *   await search.set({ status: 'completed' });
+ *
+ *   // Read a field back
+ *   const status = await search.get('status');
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Increment a numeric counter
+ * export async function counterWorkflow(): Promise<number> {
+ *   const search = await MemFlow.workflow.search();
+ *   await search.set({ count: '0' });
+ *   await search.incr('count', 1);
+ *   await search.incr('count', 1);
+ *   return Number(await search.get('count')); // 2
+ * }
+ * ```
+ *
+ * @returns {Promise<Search>} A search session scoped to the current workflow job.
  */
 export declare function search(): Promise<Search>;

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

@@ -3,8 +3,55 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.search = void 0;
 const common_1 = require("./common");
 /**
- * Returns a search session handle for interacting with the workflow's HASH storage.
- * @returns {Promise<Search>} A search session for workflow data.
+ * Returns a `Search` session handle for reading and writing key-value data
+ * on the workflow's backend HASH record. Search fields are flat string
+ * key-value pairs stored alongside the job state, making them queryable
+ * via `MemFlow.Client.workflow.search()` (FT.SEARCH).
+ *
+ * Each call produces a unique session ID tied to the deterministic
+ * execution counter, ensuring correct replay behavior.
+ *
+ * Use `search()` for flat, indexable key-value data. For structured
+ * JSON documents, use `entity()` instead.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { MemFlow } from '@hotmeshio/hotmesh';
+ *
+ * export async function orderWorkflow(orderId: string): Promise<void> {
+ *   const search = await MemFlow.workflow.search();
+ *
+ *   // Write searchable fields
+ *   await search.set({
+ *     orderId,
+ *     status: 'processing',
+ *     createdAt: new Date().toISOString(),
+ *   });
+ *
+ *   const { processOrder } = MemFlow.workflow.proxyActivities<typeof activities>();
+ *   await processOrder(orderId);
+ *
+ *   // Update status
+ *   await search.set({ status: 'completed' });
+ *
+ *   // Read a field back
+ *   const status = await search.get('status');
+ * }
+ * ```
+ *
+ * ```typescript
+ * // Increment a numeric counter
+ * export async function counterWorkflow(): Promise<number> {
+ *   const search = await MemFlow.workflow.search();
+ *   await search.set({ count: '0' });
+ *   await search.incr('count', 1);
+ *   await search.incr('count', 1);
+ *   return Number(await search.get('count')); // 2
+ * }
+ * ```
+ *
+ * @returns {Promise<Search>} A search session scoped to the current workflow job.
  */
 async function search() {
     const store = common_1.asyncLocalStorage.getStore();