@hotmeshio/hotmesh 0.12.1 → 0.14.0

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

@@ -1,66 +1,61 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowService = void 0;
-const context_1 = require("./context");
+const workflowInfo_1 = require("./workflowInfo");
 const didRun_1 = require("./didRun");
 const isSideEffectAllowed_1 = require("./isSideEffectAllowed");
 const trace_1 = require("./trace");
 const enrich_1 = require("./enrich");
 const emit_1 = require("./emit");
-const execChild_1 = require("./execChild");
+const executeChild_1 = require("./executeChild");
 const execHook_1 = require("./execHook");
 const execHookBatch_1 = require("./execHookBatch");
 const proxyActivities_1 = require("./proxyActivities");
 const searchMethods_1 = require("./searchMethods");
 const random_1 = require("./random");
+const uuid4_1 = require("./uuid4");
 const signal_1 = require("./signal");
 const hook_1 = require("./hook");
-const interrupt_1 = require("./interrupt");
+const terminate_1 = require("./terminate");
 const interruption_1 = require("./interruption");
 const all_1 = require("./all");
-const sleepFor_1 = require("./sleepFor");
-const waitFor_1 = require("./waitFor");
+const sleep_1 = require("./sleep");
+const condition_1 = require("./condition");
+const continueAsNew_1 = require("./continueAsNew");
+const patched_1 = require("./patched");
+const cancellationScope_1 = require("./cancellationScope");
 const common_1 = require("./common");
 const entityMethods_1 = require("./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.
+ * In-workflow API surface, exposed as `Durable.workflow`. Every method
+ * is called **inside** a workflow function and participates in
+ * deterministic replay — results are persisted and returned instantly
+ * on recovery without re-executing side effects.
  *
- * ## Core Primitives
+ * ## 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 |
+ * | {@link proxyActivities} | Execute activities with automatic retry |
+ * | {@link sleep} | Durable timer (survives restarts) |
+ * | {@link condition} | Pause until a named signal arrives (optional timeout) |
+ * | {@link signal} | Deliver data to a waiting `condition` |
+ * | {@link executeChild} | Spawn a child workflow and await its result |
+ * | {@link startChild} | Fire-and-forget child workflow |
+ * | {@link continueAsNew} | Restart with new args (resets history) |
+ * | {@link patched} / {@link deprecatePatch} | Safe versioning for in-flight code changes |
+ * | {@link CancellationScope} | Shield cleanup code from cancellation |
+ * | {@link isCancellation} | Detect `CancelledFailure` errors |
  *
  * ## Utilities
  *
  * | Method | Purpose |
  * |--------|---------|
- * | {@link getContext} | Access workflow ID, namespace, replay state |
+ * | {@link workflowInfo} | Access workflow ID, namespace, replay state |
  * | {@link random} | Deterministic pseudo-random numbers |
+ * | {@link uuid4} | Deterministic UUID v4 generation |
  * | {@link all} | Workflow-safe `Promise.all` |
- * | {@link didInterrupt} | Type guard for engine control-flow errors |
+ * | {@link didInterrupt} | Detect engine control-flow errors |
  *
  * ## Example
  *
@@ -69,26 +64,20 @@ const entityMethods_1 = require("./entityMethods");
  * 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 },
+ *       retry: { maximumAttempts: 3 },
  *     });
  *
  *   await validateOrder(orderId);
- *
- *   // Durable sleep (survives restarts)
- *   await Durable.workflow.sleepFor('5 seconds');
- *
+ *   await Durable.workflow.sleep('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';
+ *   // Wait for external approval signal (with 1-hour timeout)
+ *   const approval = await Durable.workflow.condition<{ ok: boolean }>('approve', '1 hour');
+ *   if (!approval) return 'timed-out';
+ *   if (!approval.ok) return 'rejected';
  *
  *   await sendReceipt(orderId, receipt);
  *   return receipt;
@@ -117,26 +106,32 @@ class WorkflowService {
         });
     }
 }
-WorkflowService.getContext = context_1.getContext;
+WorkflowService.workflowInfo = workflowInfo_1.workflowInfo;
 WorkflowService.didRun = didRun_1.didRun;
 WorkflowService.isSideEffectAllowed = isSideEffectAllowed_1.isSideEffectAllowed;
 WorkflowService.trace = trace_1.trace;
 WorkflowService.enrich = enrich_1.enrich;
 WorkflowService.emit = emit_1.emit;
-WorkflowService.execChild = execChild_1.execChild;
-WorkflowService.executeChild = execChild_1.executeChild;
-WorkflowService.startChild = execChild_1.startChild;
+WorkflowService.executeChild = executeChild_1.executeChild;
+WorkflowService.startChild = executeChild_1.startChild;
 WorkflowService.execHook = execHook_1.execHook;
 WorkflowService.execHookBatch = execHookBatch_1.execHookBatch;
 WorkflowService.proxyActivities = proxyActivities_1.proxyActivities;
 WorkflowService.search = searchMethods_1.search;
 WorkflowService.entity = entityMethods_1.entity;
 WorkflowService.random = random_1.random;
+WorkflowService.uuid4 = uuid4_1.uuid4;
 WorkflowService.signal = signal_1.signal;
 WorkflowService.hook = hook_1.hook;
 WorkflowService.didInterrupt = interruption_1.didInterrupt;
-WorkflowService.interrupt = interrupt_1.interrupt;
+WorkflowService.terminate = terminate_1.terminate;
 WorkflowService.all = all_1.all;
-WorkflowService.sleepFor = sleepFor_1.sleepFor;
-WorkflowService.waitFor = waitFor_1.waitFor;
+WorkflowService.sleep = sleep_1.sleep;
+WorkflowService.condition = condition_1.condition;
+WorkflowService.continueAsNew = continueAsNew_1.continueAsNew;
+WorkflowService.patched = patched_1.patched;
+WorkflowService.deprecatePatch = patched_1.deprecatePatch;
+WorkflowService.CancellationScope = cancellationScope_1.CancellationScope;
+WorkflowService.CancelledFailure = cancellationScope_1.CancelledFailure;
+WorkflowService.isCancellation = cancellationScope_1.isCancellation;
 exports.WorkflowService = WorkflowService;

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

@@ -3,8 +3,8 @@
  * 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
+ * for durable operations like `sleep`, `condition`, `proxyActivities`,
+ * and `executeChild`. 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
@@ -12,9 +12,10 @@
  *
  * ## Recognized Error Types
  *
- * `DurableChildError`, `DurableFatalError`, `DurableMaxedError`,
- * `DurableProxyError`, `DurableRetryError`, `DurableSleepError`,
- * `DurableTimeoutError`, `DurableWaitForError`, `DurableWaitForAllError`
+ * `DurableChildError`, `DurableContinueAsNewError`, `DurableFatalError`,
+ * `DurableMaxedError`, `DurableProxyError`, `DurableRetryError`,
+ * `DurableSleepError`, `DurableTimeoutError`, `DurableWaitForError`,
+ * `DurableWaitForAllError`, `CancelledFailure`
  *
  * ## Examples
  *
@@ -39,7 +40,7 @@
  *
  * ```typescript
  * // Common pattern in interceptors
- * const interceptor: WorkflowInterceptor = {
+ * const interceptor: WorkflowInboundCallsInterceptor = {
  *   async execute(ctx, next) {
  *     try {
  *       return await next();

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

@@ -2,13 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.didInterrupt = void 0;
 const errors_1 = require("../../../modules/errors");
+const cancellationScope_1 = require("./cancellationScope");
 /**
  * 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
+ * for durable operations like `sleep`, `condition`, `proxyActivities`,
+ * and `executeChild`. 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
@@ -16,9 +17,10 @@ const errors_1 = require("../../../modules/errors");
  *
  * ## Recognized Error Types
  *
- * `DurableChildError`, `DurableFatalError`, `DurableMaxedError`,
- * `DurableProxyError`, `DurableRetryError`, `DurableSleepError`,
- * `DurableTimeoutError`, `DurableWaitForError`, `DurableWaitForAllError`
+ * `DurableChildError`, `DurableContinueAsNewError`, `DurableFatalError`,
+ * `DurableMaxedError`, `DurableProxyError`, `DurableRetryError`,
+ * `DurableSleepError`, `DurableTimeoutError`, `DurableWaitForError`,
+ * `DurableWaitForAllError`, `CancelledFailure`
  *
  * ## Examples
  *
@@ -43,7 +45,7 @@ const errors_1 = require("../../../modules/errors");
  *
  * ```typescript
  * // Common pattern in interceptors
- * const interceptor: WorkflowInterceptor = {
+ * const interceptor: WorkflowInboundCallsInterceptor = {
  *   async execute(ctx, next) {
  *     try {
  *       return await next();
@@ -64,6 +66,7 @@ const errors_1 = require("../../../modules/errors");
  */
 function didInterrupt(error) {
     return (error instanceof errors_1.DurableChildError ||
+        error instanceof errors_1.DurableContinueAsNewError ||
         error instanceof errors_1.DurableFatalError ||
         error instanceof errors_1.DurableMaxedError ||
         error instanceof errors_1.DurableProxyError ||
@@ -71,6 +74,7 @@ function didInterrupt(error) {
         error instanceof errors_1.DurableSleepError ||
         error instanceof errors_1.DurableTimeoutError ||
         error instanceof errors_1.DurableWaitForError ||
-        error instanceof errors_1.DurableWaitForAllError);
+        error instanceof errors_1.DurableWaitForAllError ||
+        error instanceof cancellationScope_1.CancelledFailure);
 }
 exports.didInterrupt = didInterrupt;

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

@@ -0,0 +1,72 @@
+/**
+ * Enables safe code changes to running workflows by branching on a named
+ * change marker. On first execution of a new workflow, `patched` records
+ * the marker and returns `true` — the workflow takes the new code path.
+ * On replay of a workflow that was started **before** the patch existed,
+ * no marker is found and `patched` returns `false` — the old code path
+ * is followed.
+ *
+ * Markers are accumulated in the workflow context and written to the job
+ * hash by the engine (via the YAML schema's `job.maps`) when the worker
+ * responds — no direct hash writes from the worker.
+ *
+ * `patched` does **not** increment the execution counter, so it can be
+ * inserted into existing workflow code without shifting the replay
+ * positions of other durable operations.
+ *
+ * ## Lifecycle
+ *
+ * 1. **Add the patch:** wrap the new behavior with `if (await patched('id'))`.
+ *    Keep the old behavior in the `else` branch.
+ * 2. **Wait for drain:** once all workflows started before the patch have
+ *    completed, the `else` branch is dead code.
+ * 3. **Deprecate:** replace `patched` with `deprecatePatch` and remove the
+ *    `else` branch.
+ * 4. **Clean up:** remove both `deprecatePatch` and the `if` wrapper,
+ *    leaving only the new code.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   const acts = Durable.workflow.proxyActivities<typeof activities>({
+ *     activities,
+ *     retry: { maximumAttempts: 3 },
+ *   });
+ *
+ *   if (await Durable.workflow.patched('v2-validation')) {
+ *     // New path: stricter validation
+ *     await acts.validateOrderV2(orderId);
+ *   } else {
+ *     // Old path: legacy validation (for in-flight workflows)
+ *     await acts.validateOrder(orderId);
+ *   }
+ *
+ *   return await acts.processOrder(orderId);
+ * }
+ * ```
+ *
+ * @param {string} changeId - A unique, stable identifier for this code change.
+ *   Must not be reused across different changes.
+ * @returns {Promise<boolean>} `true` for new workflows (take new path),
+ *   `false` for pre-patch workflows being replayed (take old path).
+ */
+export declare function patched(changeId: string): Promise<boolean>;
+/**
+ * Declares that all workflows started before a given patch have drained
+ * and the old code path can be removed. This is a **no-op** at runtime —
+ * it exists purely as a migration signal in source code.
+ *
+ * ## Migration Steps
+ *
+ * 1. Replace `if (await patched('id')) { new } else { old }` with
+ *    `deprecatePatch('id'); new`.
+ * 2. Deploy and verify.
+ * 3. In a subsequent release, remove both `deprecatePatch('id')` and
+ *    the surrounding wrapper, leaving only the new code.
+ *
+ * @param {string} _changeId - The change ID being deprecated (unused at runtime).
+ */
+export declare function deprecatePatch(_changeId: string): void;

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

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deprecatePatch = exports.patched = void 0;
+const common_1 = require("./common");
+/**
+ * Enables safe code changes to running workflows by branching on a named
+ * change marker. On first execution of a new workflow, `patched` records
+ * the marker and returns `true` — the workflow takes the new code path.
+ * On replay of a workflow that was started **before** the patch existed,
+ * no marker is found and `patched` returns `false` — the old code path
+ * is followed.
+ *
+ * Markers are accumulated in the workflow context and written to the job
+ * hash by the engine (via the YAML schema's `job.maps`) when the worker
+ * responds — no direct hash writes from the worker.
+ *
+ * `patched` does **not** increment the execution counter, so it can be
+ * inserted into existing workflow code without shifting the replay
+ * positions of other durable operations.
+ *
+ * ## Lifecycle
+ *
+ * 1. **Add the patch:** wrap the new behavior with `if (await patched('id'))`.
+ *    Keep the old behavior in the `else` branch.
+ * 2. **Wait for drain:** once all workflows started before the patch have
+ *    completed, the `else` branch is dead code.
+ * 3. **Deprecate:** replace `patched` with `deprecatePatch` and remove the
+ *    `else` branch.
+ * 4. **Clean up:** remove both `deprecatePatch` and the `if` wrapper,
+ *    leaving only the new code.
+ *
+ * ## Examples
+ *
+ * ```typescript
+ * import { Durable } from '@hotmeshio/hotmesh';
+ *
+ * export async function orderWorkflow(orderId: string): Promise<string> {
+ *   const acts = Durable.workflow.proxyActivities<typeof activities>({
+ *     activities,
+ *     retry: { maximumAttempts: 3 },
+ *   });
+ *
+ *   if (await Durable.workflow.patched('v2-validation')) {
+ *     // New path: stricter validation
+ *     await acts.validateOrderV2(orderId);
+ *   } else {
+ *     // Old path: legacy validation (for in-flight workflows)
+ *     await acts.validateOrder(orderId);
+ *   }
+ *
+ *   return await acts.processOrder(orderId);
+ * }
+ * ```
+ *
+ * @param {string} changeId - A unique, stable identifier for this code change.
+ *   Must not be reused across different changes.
+ * @returns {Promise<boolean>} `true` for new workflows (take new path),
+ *   `false` for pre-patch workflows being replayed (take old path).
+ */
+async function patched(changeId) {
+    const store = common_1.asyncLocalStorage.getStore();
+    const replay = store.get('replay');
+    const workflowDimension = store.get('workflowDimension') ?? '';
+    const patchKey = `-patch${workflowDimension}-${changeId}-`;
+    // Marker exists from a previous execution — take new path
+    if (patchKey in replay) {
+        return true;
+    }
+    // Marker not found. Distinguish first execution from pre-patch replay
+    // by checking for non-patch replay entries. On first execution, no
+    // durable operations have completed yet, so only patch markers (from
+    // earlier patched() calls in this same execution) can exist.
+    const patchPrefix = `-patch${workflowDimension}-`;
+    const hasNonPatchEntries = Object.keys(replay).some((key) => !key.startsWith(patchPrefix));
+    if (hasNonPatchEntries) {
+        // Pre-patch workflow: replay has entries from prior operations but
+        // no marker for this change — follow the old code path
+        return false;
+    }
+    // First execution of a new workflow: accumulate the marker in context.
+    // The engine writes it to the job hash via the YAML schema's job.maps
+    // when the worker responds (for any response code).
+    const patchMarkers = store.get('patchMarkers');
+    patchMarkers[patchKey] = common_1.SerializerService.toString(true);
+    // Update in-memory replay so subsequent patched() calls in this
+    // execution see the marker without waiting for the engine round-trip
+    replay[patchKey] = patchMarkers[patchKey];
+    return true;
+}
+exports.patched = patched;
+/**
+ * Declares that all workflows started before a given patch have drained
+ * and the old code path can be removed. This is a **no-op** at runtime —
+ * it exists purely as a migration signal in source code.
+ *
+ * ## Migration Steps
+ *
+ * 1. Replace `if (await patched('id')) { new } else { old }` with
+ *    `deprecatePatch('id'); new`.
+ * 2. Deploy and verify.
+ * 3. In a subsequent release, remove both `deprecatePatch('id')` and
+ *    the surrounding wrapper, leaving only the new code.
+ *
+ * @param {string} _changeId - The change ID being deprecated (unused at runtime).
+ */
+function deprecatePatch(_changeId) {
+    // No-op: all pre-patch workflows have completed.
+    // Safe to remove the old code path.
+}
+exports.deprecatePatch = deprecatePatch;

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

@@ -1,10 +1,10 @@
 import { ActivityConfig, ProxyType, DurableProxyErrorType } from './common';
-import { getContext } from './context';
+import { workflowInfo } from './workflowInfo';
 /**
  * Constructs payload for spawning a proxyActivity job.
  * @private
  */
-declare function getProxyInterruptPayload(context: ReturnType<typeof getContext>, activityName: string, execIndex: number, args: any[], options?: ActivityConfig): DurableProxyErrorType;
+declare function getProxyInterruptPayload(context: ReturnType<typeof workflowInfo>, activityName: string, execIndex: number, args: any[], options?: ActivityConfig): DurableProxyErrorType;
 /**
  * Wraps a single activity in a proxy, orchestrating its execution and replay.
  * @private
@@ -47,7 +47,7 @@ declare function wrapActivity<T>(activityName: string, options?: ActivityConfig)
  *   const { validateOrder, chargePayment, sendConfirmation } =
  *     Durable.workflow.proxyActivities<typeof activities>({
  *       activities,
- *       retryPolicy: {
+ *       retry: {
  *         maximumAttempts: 3,
  *         backoffCoefficient: 2,
  *         maximumInterval: '30s',
@@ -72,7 +72,7 @@ declare function wrapActivity<T>(activityName: string, options?: ActivityConfig)
  *   const { refundPayment } =
  *     Durable.workflow.proxyActivities<PaymentActivities>({
  *       taskQueue: 'payments',
- *       retryPolicy: { maximumAttempts: 5 },
+ *       retry: { maximumAttempts: 5 },
  *     });
  *
  *   await refundPayment(txId);
@@ -81,13 +81,13 @@ declare function wrapActivity<T>(activityName: string, options?: ActivityConfig)
  *
  * ```typescript
  * // Interceptor with shared activity pool
- * const auditInterceptor: WorkflowInterceptor = {
+ * const auditInterceptor: WorkflowInboundCallsInterceptor = {
  *   async execute(ctx, next) {
  *     const { auditLog } = Durable.workflow.proxyActivities<{
  *       auditLog: (id: string, action: string) => Promise<void>;
  *     }>({
  *       taskQueue: 'shared-audit',
- *       retryPolicy: { maximumAttempts: 3 },
+ *       retry: { maximumAttempts: 3 },
  *     });
  *
  *     await auditLog(ctx.get('workflowId'), 'started');
@@ -102,7 +102,7 @@ declare function wrapActivity<T>(activityName: string, options?: ActivityConfig)
  * // Graceful error handling (no throw)
  * const { riskyOperation } = Durable.workflow.proxyActivities<typeof activities>({
  *   activities,
- *   retryPolicy: { maximumAttempts: 1, throwOnError: false },
+ *   retry: { maximumAttempts: 1, throwOnError: false },
  * });
  *
  * const result = await riskyOperation();

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

@@ -2,7 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getProxyInterruptPayload = exports.wrapActivity = exports.proxyActivities = void 0;
 const common_1 = require("./common");
-const context_1 = require("./context");
+const cancellationScope_1 = require("./cancellationScope");
+const workflowInfo_1 = require("./workflowInfo");
 const didRun_1 = require("./didRun");
 /**
  * Constructs payload for spawning a proxyActivity job.
@@ -16,11 +17,20 @@ function getProxyInterruptPayload(context, activityName, execIndex, args, option
         : `${taskQueue}-activity`;
     const activityJobId = `-${workflowId}-$${activityName}${workflowDimension}-${execIndex}`;
     let maximumInterval;
-    if (options?.retryPolicy?.maximumInterval) {
-        maximumInterval = (0, common_1.s)(options.retryPolicy.maximumInterval);
+    if (options?.retry?.maximumInterval) {
+        maximumInterval = (0, common_1.s)(options.retry.maximumInterval);
+    }
+    let initialInterval;
+    if (options?.retry?.initialInterval) {
+        initialInterval = (0, common_1.s)(options.retry.initialInterval);
+    }
+    let startToCloseTimeout;
+    if (options?.startToCloseTimeout) {
+        startToCloseTimeout = (0, common_1.s)(options.startToCloseTimeout);
     }
     return {
         arguments: args,
+        headers: options?.headers ?? undefined,
         workflowDimension,
         index: execIndex,
         originJobId: originJobId || workflowId,
@@ -29,9 +39,11 @@ function getProxyInterruptPayload(context, activityName, execIndex, args, option
         workflowTopic: activityTopic,
         activityName,
         expire: options?.expire ?? expire,
-        backoffCoefficient: options?.retryPolicy?.backoffCoefficient ?? undefined,
-        maximumAttempts: options?.retryPolicy?.maximumAttempts ?? undefined,
+        backoffCoefficient: options?.retry?.backoffCoefficient ?? undefined,
+        initialInterval: initialInterval ?? undefined,
+        maximumAttempts: options?.retry?.maximumAttempts ?? undefined,
         maximumInterval: maximumInterval ?? undefined,
+        startToCloseTimeout: startToCloseTimeout ?? undefined,
     };
 }
 exports.getProxyInterruptPayload = getProxyInterruptPayload;
@@ -43,7 +55,9 @@ function wrapActivity(activityName, options) {
     return async function (...args) {
         // Increment counter first for deterministic replay ordering
         const [didRunAlready, execIndex, result] = await (0, didRun_1.didRun)('proxy');
-        const context = (0, context_1.getContext)();
+        // Check cancellation AFTER counter increment to preserve replay positions
+        (0, cancellationScope_1.checkCancellation)();
+        const context = (0, workflowInfo_1.workflowInfo)();
         const { interruptionRegistry } = context;
         // Build activityCtx so interceptors can inspect/modify args
         const activityCtx = { activityName, args, options };
@@ -52,8 +66,19 @@ function wrapActivity(activityName, options) {
         // from activityCtx so "before" interceptors can modify them.
         const coreFunction = async () => {
             if (didRunAlready) {
+                // Emit RETURN span in debug mode
+                if (common_1.DurableTelemetryService.isVerbose() && result) {
+                    const { workflowTrace, workflowSpan } = context;
+                    if (workflowTrace && workflowSpan && result.ac && result.au) {
+                        common_1.DurableTelemetryService.emitDurationSpan(workflowTrace, workflowSpan, `RETURN/proxy/${activityName}/${execIndex}`, common_1.DurableTelemetryService.parseTimestamp(result.ac), common_1.DurableTelemetryService.parseTimestamp(result.au), {
+                            'durable.operation.type': 'proxy',
+                            'durable.activity.name': activityName,
+                            'durable.exec.index': execIndex,
+                        });
+                    }
+                }
                 if (result?.$error) {
-                    if (options?.retryPolicy?.throwOnError !== false) {
+                    if (activityCtx.options?.retry?.throwOnError !== false) {
                         const code = result.$error.code;
                         const message = result.$error.message;
                         const stack = result.$error.stack;
@@ -74,7 +99,18 @@ function wrapActivity(activityName, options) {
                 }
                 return result.data;
             }
-            const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, activityCtx.args, options);
+            // Emit DISPATCH span in debug mode
+            if (common_1.DurableTelemetryService.isVerbose()) {
+                const { workflowTrace, workflowSpan } = context;
+                if (workflowTrace && workflowSpan) {
+                    common_1.DurableTelemetryService.emitPointSpan(workflowTrace, workflowSpan, `DISPATCH/proxy/${activityName}/${execIndex}`, {
+                        'durable.operation.type': 'proxy',
+                        'durable.activity.name': activityName,
+                        'durable.exec.index': execIndex,
+                    });
+                }
+            }
+            const interruptionMessage = getProxyInterruptPayload(context, activityName, execIndex, activityCtx.args, activityCtx.options);
             interruptionRegistry.push({
                 code: common_1.HMSH_CODE_DURABLE_PROXY,
                 type: 'DurableProxyError',
@@ -86,8 +122,8 @@ function wrapActivity(activityName, options) {
         // Run through interceptor chain if interceptors exist
         const store = common_1.asyncLocalStorage.getStore();
         const interceptorService = store?.get('activityInterceptorService');
-        if (interceptorService?.activityInterceptors?.length > 0) {
-            return await interceptorService.executeActivityChain(activityCtx, store, coreFunction);
+        if (interceptorService?.outbound?.length > 0) {
+            return await interceptorService.executeOutboundChain(activityCtx, store, coreFunction);
         }
         return await coreFunction();
     };
@@ -130,7 +166,7 @@ exports.wrapActivity = wrapActivity;
  *   const { validateOrder, chargePayment, sendConfirmation } =
  *     Durable.workflow.proxyActivities<typeof activities>({
  *       activities,
- *       retryPolicy: {
+ *       retry: {
  *         maximumAttempts: 3,
  *         backoffCoefficient: 2,
  *         maximumInterval: '30s',
@@ -155,7 +191,7 @@ exports.wrapActivity = wrapActivity;
  *   const { refundPayment } =
  *     Durable.workflow.proxyActivities<PaymentActivities>({
  *       taskQueue: 'payments',
- *       retryPolicy: { maximumAttempts: 5 },
+ *       retry: { maximumAttempts: 5 },
  *     });
  *
  *   await refundPayment(txId);
@@ -164,13 +200,13 @@ exports.wrapActivity = wrapActivity;
  *
  * ```typescript
  * // Interceptor with shared activity pool
- * const auditInterceptor: WorkflowInterceptor = {
+ * const auditInterceptor: WorkflowInboundCallsInterceptor = {
  *   async execute(ctx, next) {
  *     const { auditLog } = Durable.workflow.proxyActivities<{
  *       auditLog: (id: string, action: string) => Promise<void>;
  *     }>({
  *       taskQueue: 'shared-audit',
- *       retryPolicy: { maximumAttempts: 3 },
+ *       retry: { maximumAttempts: 3 },
  *     });
  *
  *     await auditLog(ctx.get('workflowId'), 'started');
@@ -185,7 +221,7 @@ exports.wrapActivity = wrapActivity;
  * // Graceful error handling (no throw)
  * const { riskyOperation } = Durable.workflow.proxyActivities<typeof activities>({
  *   activities,
- *   retryPolicy: { maximumAttempts: 1, throwOnError: false },
+ *   retry: { maximumAttempts: 1, throwOnError: false },
  * });
  *
  * const result = await riskyOperation();

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

@@ -48,6 +48,13 @@ import { Search } from './common';
  * }
  * ```
  *
+ * **Not available with `workerCredentials`.** This method writes directly
+ * to the `jobs` and `jobs_attributes` tables, bypassing the SECURITY
+ * DEFINER stored procedures that scoped worker roles are restricted to.
+ * Workers connecting with `workerCredentials` will receive a permission
+ * error. Use `search()` only in workflows running with full database
+ * credentials.
+ *
  * @returns {Promise<Search>} A search session scoped to the current workflow job.
  */
 export declare function search(): Promise<Search>;