@aws/durable-execution-sdk-js 1.0.1 → 1.0.3

package/README.md

@@ -285,17 +285,37 @@ Control execution guarantees:
 ```typescript
 import { StepSemantics } from "@aws/durable-execution-sdk-js";
 
-// At-most-once per retry (default)
+// At-least-once per retry (default)
+await context.step("retriable-operation", async () => sendNotification(), {
+  semantics: StepSemantics.AtLeastOncePerRetry,
+});
+
+// At-most-once per retry
 await context.step("idempotent-operation", async () => updateDatabase(), {
   semantics: StepSemantics.AtMostOncePerRetry,
 });
+```
 
-// At-least-once per retry
-await context.step("retriable-operation", async () => sendNotification(), {
-  semantics: StepSemantics.AtLeastOncePerRetry,
-});
+**Important**: These semantics apply _per retry_, not per overall execution:
+
+- **AtLeastOncePerRetry**: The step will execute at least once on each retry attempt. If the step succeeds but the checkpoint fails (e.g., sandbox crash), the step will re-execute on replay.
+- **AtMostOncePerRetry**: The step will execute at most once per retry attempt. A checkpoint is created before execution, so if a failure occurs after the checkpoint but before step completion, the previous step retry attempt is skipped on replay.
+
+**To achieve at-most-once semantics on a step-level**, use a custom retry strategy:
+
+```typescript
+await context.step(
+  "truly-once-only",
+  async () => callThatCannotTolerateDuplicates(),
+  {
+    semantics: StepSemantics.AtMostOncePerRetry,
+    retryStrategy: () => ({ shouldRetry: false }), // No retries
+  },
+);
 ```
 
+Without this, a step using `AtMostOncePerRetry` with retries enabled could still execute multiple times across different retry attempts.
+
 ### Jitter Strategies
 
 Prevent thundering herd:

package/dist/index.mjs

@@ -165,11 +165,56 @@ var DurableLogLevel;
 })(DurableLogLevel || (DurableLogLevel = {}));
 
 /**
+ * Execution semantics for step operations.
+ *
+ * @remarks
+ * These semantics control how step execution is checkpointed and replayed. **Important**: The guarantees apply *per
+ * retry attempt*, not per overall workflow execution.
+ *
+ * With retries enabled (the default), a step could execute multiple times across different retry attempts even when
+ * using `AtMostOncePerRetry`. To achieve step-level at-most-once execution, combine `AtMostOncePerRetry` with a retry
+ * strategy that disables retries (`shouldRetry: false`).
+ *
+ * @example
+ * ```typescript
+ * // At-least-once per retry (default) - safe for idempotent operations
+ * await context.step("send-notification", async () => sendEmail(), {
+ *   semantics: StepSemantics.AtLeastOncePerRetry,
+ * });
+ *
+ * // At-most-once per retry - for non-idempotent operations
+ * await context.step("charge-payment", async () => processPayment(), {
+ *   semantics: StepSemantics.AtMostOncePerRetry,
+ *   retryStrategy: () => ({ shouldRetry: false }),
+ * });
+ * ```
+ *
  * @public
  */
 var StepSemantics;
 (function (StepSemantics) {
+    /**
+     * At-most-once execution per retry attempt.
+     *
+     * @remarks
+     * A checkpoint is created before step execution. If a failure occurs after the checkpoint
+     * but before step completion, the previous step retry attempt is skipped on replay.
+     *
+     * **Note**: This is "at-most-once *per retry*". With multiple retry attempts, the step
+     * could still execute multiple times across different retries. To guarantee the step
+     * executes at most once, disable retries by returning
+     * `{ shouldRetry: false }` from your retry strategy.
+     */
     StepSemantics["AtMostOncePerRetry"] = "AT_MOST_ONCE_PER_RETRY";
+    /**
+     * At-least-once execution per retry attempt (default).
+     *
+     * @remarks
+     * The step will execute at least once on each retry attempt. If the step succeeds
+     * but the checkpoint fails (e.g., due to a sandbox crash), the step will re-execute
+     * on replay. This is the safer default for operations that are idempotent or can
+     * tolerate duplicate execution.
+     */
     StepSemantics["AtLeastOncePerRetry"] = "AT_LEAST_ONCE_PER_RETRY";
 })(StepSemantics || (StepSemantics = {}));
 /**
@@ -567,6 +612,26 @@ class StepInterruptedError extends Error {
     }
 }
 
+/**
+ * Shared constants to avoid circular dependencies
+ */
+/**
+ * Controls whether stack traces are stored in error objects
+ * TODO: Accept this as configuration parameter in the future
+ */
+/**
+ * Checkpoint manager termination cooldown in milliseconds
+ * After the last operation completes, the checkpoint manager waits this duration
+ * before terminating to allow for any final checkpoint operations
+ */
+const CHECKPOINT_TERMINATION_COOLDOWN_MS = 20;
+/**
+ * Maximum polling duration in milliseconds (15 minutes)
+ * Used to cap setTimeout delays to prevent 32-bit signed integer overflow
+ * and limit polling duration for long-running operations
+ */
+const MAX_POLL_DURATION_MS = 15 * 60 * 1000;
+
 /**
  * Base class for all durable operation errors
  * @public
@@ -1355,6 +1420,7 @@ const createInvokeHandler = (context, checkpoint, createStepId, parentId, checkA
                     Payload: serializedPayload,
                     ChainedInvokeOptions: {
                         FunctionName: funcId,
+                        ...(config?.tenantId && { TenantId: config.tenantId }),
                     },
                 });
             }
@@ -2485,6 +2551,10 @@ class BatchResultImpl {
  * Restores methods to deserialized BatchResult data
  */
 function restoreBatchResult(data) {
+    // If data is already a BatchResultImpl instance, return it as-is
+    if (data instanceof BatchResultImpl) {
+        return data;
+    }
     if (data &&
         typeof data === "object" &&
         "all" in data &&
@@ -2794,7 +2864,13 @@ class ConcurrencyController {
                     tryStartNext();
                 }
             };
-            tryStartNext();
+            if (items.length === 0) {
+                log("🎉", `${this.operationName} completed with no items`);
+                resolve(new BatchResultImpl([], getCompletionReason(0)));
+            }
+            else {
+                tryStartNext();
+            }
         });
     }
 }
@@ -2946,7 +3022,7 @@ const getStepData = (stepData, stepId) => {
 };
 
 class DurableContextImpl {
-    executionContext;
+    _executionContext;
     lambdaContext;
     _stepPrefix;
     _stepCounter = 0;
@@ -2958,8 +3034,9 @@ class DurableContextImpl {
     modeManagement;
     durableExecution;
     logger;
-    constructor(executionContext, lambdaContext, durableExecutionMode, inheritedLogger, stepPrefix, durableExecution, parentId) {
-        this.executionContext = executionContext;
+    executionContext;
+    constructor(_executionContext, lambdaContext, durableExecutionMode, inheritedLogger, stepPrefix, durableExecution, parentId) {
+        this._executionContext = _executionContext;
         this.lambdaContext = lambdaContext;
         this._stepPrefix = stepPrefix;
         this._parentId = parentId;
@@ -2967,6 +3044,9 @@ class DurableContextImpl {
         this.durableLogger = inheritedLogger;
         this.durableLogger.configureDurableLoggingContext?.(this.getDurableLoggingContext());
         this.logger = this.createModeAwareLogger(inheritedLogger);
+        this.executionContext = {
+            durableExecutionArn: _executionContext.durableExecutionArn,
+        };
         this.durableExecutionMode = durableExecutionMode;
         this.checkpoint = durableExecution.checkpointManager;
         this.modeManagement = new ModeManagement(this.captureExecutionState.bind(this), this.checkAndUpdateReplayMode.bind(this), this.checkForNonResolvingPromise.bind(this), () => this.durableExecutionMode, (mode) => {
@@ -2978,9 +3058,9 @@ class DurableContextImpl {
             getDurableLogData: () => {
                 const activeContext = getActiveContext();
                 const result = {
-                    executionArn: this.executionContext.durableExecutionArn,
-                    requestId: this.executionContext.requestId,
-                    tenantId: this.executionContext.tenantId,
+                    executionArn: this._executionContext.durableExecutionArn,
+                    requestId: this._executionContext.requestId,
+                    tenantId: this._executionContext.tenantId,
                     operationId: !activeContext || activeContext?.contextId === "root"
                         ? undefined
                         : hashId(activeContext.contextId),
@@ -3057,7 +3137,7 @@ class DurableContextImpl {
     checkAndUpdateReplayMode() {
         if (this.durableExecutionMode === DurableExecutionMode.ReplayMode) {
             const nextStepId = this.getNextStepId();
-            const nextStepData = this.executionContext.getStepData(nextStepId);
+            const nextStepData = this._executionContext.getStepData(nextStepId);
             if (!nextStepData) {
                 this.durableExecutionMode = DurableExecutionMode.ExecutionMode;
             }
@@ -3066,7 +3146,7 @@ class DurableContextImpl {
     captureExecutionState() {
         const wasInReplayMode = this.durableExecutionMode === DurableExecutionMode.ReplayMode;
         const nextStepId = this.getNextStepId();
-        const stepData = this.executionContext.getStepData(nextStepId);
+        const stepData = this._executionContext.getStepData(nextStepId);
         const wasNotFinished = !!(stepData &&
             stepData.Status !== OperationStatus.SUCCEEDED &&
             stepData.Status !== OperationStatus.FAILED);
@@ -3075,7 +3155,7 @@ class DurableContextImpl {
     checkForNonResolvingPromise() {
         if (this.durableExecutionMode === DurableExecutionMode.ReplaySucceededContext) {
             const nextStepId = this.getNextStepId();
-            const nextStepData = this.executionContext.getStepData(nextStepId);
+            const nextStepData = this._executionContext.getStepData(nextStepId);
             if (nextStepData &&
                 nextStepData.Status !== OperationStatus.SUCCEEDED &&
                 nextStepData.Status !== OperationStatus.FAILED) {
@@ -3091,16 +3171,16 @@ class DurableContextImpl {
         return this.modeManagement.withDurableModeManagement(operation);
     }
     step(nameOrFn, fnOrOptions, maybeOptions) {
-        validateContextUsage(this._stepPrefix, "step", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "step", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const stepHandler = createStepHandler(this.executionContext, this.checkpoint, this.lambdaContext, this.createStepId.bind(this), this.durableLogger, this._parentId);
+            const stepHandler = createStepHandler(this._executionContext, this.checkpoint, this.lambdaContext, this.createStepId.bind(this), this.durableLogger, this._parentId);
             return stepHandler(nameOrFn, fnOrOptions, maybeOptions);
         });
     }
     invoke(nameOrFuncId, funcIdOrInput, inputOrConfig, maybeConfig) {
-        validateContextUsage(this._stepPrefix, "invoke", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "invoke", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const invokeHandler = createInvokeHandler(this.executionContext, this.checkpoint, this.createStepId.bind(this), this._parentId, this.checkAndUpdateReplayMode.bind(this));
+            const invokeHandler = createInvokeHandler(this._executionContext, this.checkpoint, this.createStepId.bind(this), this._parentId, this.checkAndUpdateReplayMode.bind(this));
             return invokeHandler(...[
                 nameOrFuncId,
                 funcIdOrInput,
@@ -3110,18 +3190,18 @@ class DurableContextImpl {
         });
     }
     runInChildContext(nameOrFn, fnOrOptions, maybeOptions) {
-        validateContextUsage(this._stepPrefix, "runInChildContext", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "runInChildContext", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const blockHandler = createRunInChildContextHandler(this.executionContext, this.checkpoint, this.lambdaContext, this.createStepId.bind(this), () => this.durableLogger, 
+            const blockHandler = createRunInChildContextHandler(this._executionContext, this.checkpoint, this.lambdaContext, this.createStepId.bind(this), () => this.durableLogger, 
             // Adapter function to maintain compatibility
             (executionContext, parentContext, durableExecutionMode, inheritedLogger, stepPrefix, _checkpointToken, parentId) => createDurableContext(executionContext, parentContext, durableExecutionMode, inheritedLogger, stepPrefix, this.durableExecution, parentId), this._parentId);
             return blockHandler(nameOrFn, fnOrOptions, maybeOptions);
         });
     }
     wait(nameOrDuration, maybeDuration) {
-        validateContextUsage(this._stepPrefix, "wait", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "wait", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const waitHandler = createWaitHandler(this.executionContext, this.checkpoint, this.createStepId.bind(this), this._parentId, this.checkAndUpdateReplayMode.bind(this));
+            const waitHandler = createWaitHandler(this._executionContext, this.checkpoint, this.createStepId.bind(this), this._parentId, this.checkAndUpdateReplayMode.bind(this));
             return typeof nameOrDuration === "string"
                 ? waitHandler(nameOrDuration, maybeDuration)
                 : waitHandler(nameOrDuration);
@@ -3153,23 +3233,23 @@ class DurableContextImpl {
         }
     }
     createCallback(nameOrConfig, maybeConfig) {
-        validateContextUsage(this._stepPrefix, "createCallback", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "createCallback", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const callbackFactory = createCallback(this.executionContext, this.checkpoint, this.createStepId.bind(this), this.checkAndUpdateReplayMode.bind(this), this._parentId);
+            const callbackFactory = createCallback(this._executionContext, this.checkpoint, this.createStepId.bind(this), this.checkAndUpdateReplayMode.bind(this), this._parentId);
             return callbackFactory(nameOrConfig, maybeConfig);
         });
     }
     waitForCallback(nameOrSubmitter, submitterOrConfig, maybeConfig) {
-        validateContextUsage(this._stepPrefix, "waitForCallback", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "waitForCallback", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const waitForCallbackHandler = createWaitForCallbackHandler(this.executionContext, this.getNextStepId.bind(this), this.runInChildContext.bind(this));
+            const waitForCallbackHandler = createWaitForCallbackHandler(this._executionContext, this.getNextStepId.bind(this), this.runInChildContext.bind(this));
             return waitForCallbackHandler(nameOrSubmitter, submitterOrConfig, maybeConfig);
         });
     }
     waitForCondition(nameOrCheckFunc, checkFuncOrConfig, maybeConfig) {
-        validateContextUsage(this._stepPrefix, "waitForCondition", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "waitForCondition", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const waitForConditionHandler = createWaitForConditionHandler(this.executionContext, this.checkpoint, this.createStepId.bind(this), this.durableLogger, this._parentId);
+            const waitForConditionHandler = createWaitForConditionHandler(this._executionContext, this.checkpoint, this.createStepId.bind(this), this.durableLogger, this._parentId);
             return typeof nameOrCheckFunc === "string" ||
                 nameOrCheckFunc === undefined
                 ? waitForConditionHandler(nameOrCheckFunc, checkFuncOrConfig, maybeConfig)
@@ -3177,23 +3257,23 @@ class DurableContextImpl {
         });
     }
     map(nameOrItems, itemsOrMapFunc, mapFuncOrConfig, maybeConfig) {
-        validateContextUsage(this._stepPrefix, "map", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "map", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const mapHandler = createMapHandler(this.executionContext, this._executeConcurrently.bind(this));
+            const mapHandler = createMapHandler(this._executionContext, this._executeConcurrently.bind(this));
             return mapHandler(nameOrItems, itemsOrMapFunc, mapFuncOrConfig, maybeConfig);
         });
     }
     parallel(nameOrBranches, branchesOrConfig, maybeConfig) {
-        validateContextUsage(this._stepPrefix, "parallel", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "parallel", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const parallelHandler = createParallelHandler(this.executionContext, this._executeConcurrently.bind(this));
+            const parallelHandler = createParallelHandler(this._executionContext, this._executeConcurrently.bind(this));
             return parallelHandler(nameOrBranches, branchesOrConfig, maybeConfig);
         });
     }
     _executeConcurrently(nameOrItems, itemsOrExecutor, executorOrConfig, maybeConfig) {
-        validateContextUsage(this._stepPrefix, "_executeConcurrently", this.executionContext.terminationManager);
+        validateContextUsage(this._stepPrefix, "_executeConcurrently", this._executionContext.terminationManager);
         return this.withDurableModeManagement(() => {
-            const concurrentExecutionHandler = createConcurrentExecutionHandler(this.executionContext, this.runInChildContext.bind(this), this.skipNextOperation.bind(this));
+            const concurrentExecutionHandler = createConcurrentExecutionHandler(this._executionContext, this.runInChildContext.bind(this), this.skipNextOperation.bind(this));
             const promise = concurrentExecutionHandler(nameOrItems, itemsOrExecutor, executorOrConfig, maybeConfig);
             // Prevent unhandled promise rejections
             promise?.catch(() => { });
@@ -3232,6 +3312,13 @@ class CheckpointUnrecoverableExecutionError extends UnrecoverableExecutionError
 }
 
 const STEP_DATA_UPDATED_EVENT = "stepDataUpdated";
+const TERMINAL_STATUSES = [
+    OperationStatus.SUCCEEDED,
+    OperationStatus.CANCELLED,
+    OperationStatus.FAILED,
+    OperationStatus.STOPPED,
+    OperationStatus.TIMED_OUT,
+];
 class CheckpointManager {
     durableExecutionArn;
     stepData;
@@ -3246,6 +3333,7 @@ class CheckpointManager {
     forceCheckpointPromises = [];
     queueCompletionResolver = null;
     MAX_PAYLOAD_SIZE = 750 * 1024; // 750KB in bytes
+    MAX_ITEMS_IN_BATCH = 250;
     isTerminating = false;
     static textEncoder = new TextEncoder();
     // Operation lifecycle tracking
@@ -3253,7 +3341,6 @@ class CheckpointManager {
     // Termination cooldown
     terminationTimer = null;
     terminationReason = null;
-    TERMINATION_COOLDOWN_MS = 50;
     constructor(durableExecutionArn, stepData, storage, terminationManager, initialTaskToken, stepDataEmitter, logger, finishedAncestors) {
         this.durableExecutionArn = durableExecutionArn;
         this.stepData = stepData;
@@ -3407,7 +3494,9 @@ class CheckpointManager {
         while (this.queue.length > 0) {
             const nextItem = this.queue[0];
             const itemSize = CheckpointManager.textEncoder.encode(JSON.stringify(nextItem)).length;
-            if (currentSize + itemSize > this.MAX_PAYLOAD_SIZE && batch.length > 0) {
+            if ((currentSize + itemSize > this.MAX_PAYLOAD_SIZE ||
+                batch.length >= this.MAX_ITEMS_IN_BATCH) &&
+                batch.length > 0) {
                 break;
             }
             this.queue.shift();
@@ -3589,6 +3678,11 @@ class CheckpointManager {
         if (op.state !== OperationLifecycleState.RETRY_WAITING) {
             throw new Error(`Operation ${stepId} must be in RETRY_WAITING state, got ${op.state}`);
         }
+        // Resolve immediately if the step was completed already
+        const stepData = this.stepData[hashId(stepId)];
+        if (stepData?.Status && TERMINAL_STATUSES.includes(stepData.Status)) {
+            return Promise.resolve();
+        }
         // Start timer with polling
         this.startTimerWithPolling(stepId, op.endTimestamp);
         // Return promise that resolves when status changes
@@ -3604,6 +3698,11 @@ class CheckpointManager {
         if (op.state !== OperationLifecycleState.IDLE_AWAITED) {
             throw new Error(`Operation ${stepId} must be in IDLE_AWAITED state, got ${op.state}`);
         }
+        // Resolve immediately if the step was completed already
+        const stepData = this.stepData[hashId(stepId)];
+        if (stepData?.Status && TERMINAL_STATUSES.includes(stepData.Status)) {
+            return Promise.resolve();
+        }
         // Start timer with polling
         this.startTimerWithPolling(stepId, op.endTimestamp);
         // Return promise that resolves when status changes
@@ -3653,28 +3752,28 @@ class CheckpointManager {
             op.resolver = undefined;
         }
     }
-    checkAndTerminate() {
+    /**
+     * Determines if the function should terminate.
+     * @returns TerminationReason if the function should terminate, or undefined if the function should not terminate
+     */
+    shouldTerminate() {
         // Rule 1: Can't terminate if checkpoint queue is not empty
         if (this.queue.length > 0) {
-            this.abortTermination();
-            return;
+            return undefined;
         }
         // Rule 2: Can't terminate if checkpoint is currently processing
         if (this.isProcessing) {
-            this.abortTermination();
-            return;
+            return undefined;
         }
         // Rule 3: Can't terminate if there are pending force checkpoint promises
         if (this.forceCheckpointPromises.length > 0) {
-            this.abortTermination();
-            return;
+            return undefined;
         }
         const allOps = Array.from(this.operations.values());
         // Rule 4: Can't terminate if any operation is EXECUTING
         const hasExecuting = allOps.some((op) => op.state === OperationLifecycleState.EXECUTING);
         if (hasExecuting) {
-            this.abortTermination();
-            return;
+            return undefined;
         }
         // Rule 5: Clean up operations whose ancestors are complete or pending completion
         for (const op of allOps) {
@@ -3697,12 +3796,17 @@ class CheckpointManager {
             op.state === OperationLifecycleState.IDLE_NOT_AWAITED ||
             op.state === OperationLifecycleState.IDLE_AWAITED);
         if (hasWaiting) {
-            const reason = this.determineTerminationReason(remainingOps);
-            this.scheduleTermination(reason);
+            return this.determineTerminationReason(remainingOps);
         }
-        else {
-            this.abortTermination();
+        return undefined;
+    }
+    checkAndTerminate() {
+        const terminationReason = this.shouldTerminate();
+        if (terminationReason) {
+            this.scheduleTermination(terminationReason);
+            return;
         }
+        this.abortTermination();
     }
     abortTermination() {
         if (this.terminationTimer) {
@@ -3723,11 +3827,16 @@ class CheckpointManager {
         this.terminationReason = reason;
         log("⏱️", "Scheduling termination", {
             reason,
-            cooldownMs: this.TERMINATION_COOLDOWN_MS,
+            cooldownMs: CHECKPOINT_TERMINATION_COOLDOWN_MS,
         });
         this.terminationTimer = setTimeout(() => {
+            if (!this.shouldTerminate()) {
+                log("🔄", "Termination conditions no longer valid after cooldown, aborting termination");
+                this.abortTermination();
+                return;
+            }
             this.executeTermination(reason);
-        }, this.TERMINATION_COOLDOWN_MS);
+        }, CHECKPOINT_TERMINATION_COOLDOWN_MS);
     }
     executeTermination(reason) {
         log("🛑", "Executing termination after cooldown", { reason });
@@ -3762,6 +3871,10 @@ class CheckpointManager {
             const timestamp = endTimestamp instanceof Date ? endTimestamp : new Date(endTimestamp);
             // Wait until endTimestamp
             delay = Math.max(0, timestamp.getTime() - Date.now());
+            // Skip setTimeout if delay exceeds MAX_POLL_DURATION_MS (Lambda will timeout before it fires)
+            if (delay > MAX_POLL_DURATION_MS) {
+                return;
+            }
         }
         else {
             // No timestamp, start polling immediately (1 second delay)
@@ -3781,7 +3894,6 @@ class CheckpointManager {
         if (!op)
             return;
         // Check if we've exceeded max polling duration (15 minutes)
-        const MAX_POLL_DURATION_MS = 15 * 60 * 1000; // 15 minutes
         if (op.pollStartTime &&
             Date.now() - op.pollStartTime > MAX_POLL_DURATION_MS) {
             // Stop polling after 15 minutes to prevent indefinite resource consumption.
@@ -3893,6 +4005,13 @@ class TerminationManager extends EventEmitter {
 // align the default behaviour of how logs are emitted to match the RIC logging behaviour for consistency.
 // For custom logic, users can implement their own logger to log data differently.
 // See: https://github.com/aws/aws-lambda-nodejs-runtime-interface-client/blob/962ed28eefbc052389c4de4366b1c0c49ee08a13/src/LogPatch.js
+/**
+ * Format options for util.formatWithOptions.
+ * Using breakLength: Infinity prevents util.inspect from inserting newlines
+ * when formatting objects, regardless of object size (fixes issue #322).
+ * Defined at module level to avoid creating a new object on every function call.
+ */
+const FORMAT_OPTIONS = { breakLength: Infinity };
 /**
  * JSON.stringify replacer function for Error objects.
  * Based on AWS Lambda Runtime Interface Client LogPatch functionality.
@@ -3958,11 +4077,11 @@ function formatDurableLogData(level, logData, ...messageParams) {
             return JSON.stringify(result, jsonErrorReplacer);
         }
         catch (_) {
-            result.message = util.format(result.message);
+            result.message = util.formatWithOptions(FORMAT_OPTIONS, result.message);
             return JSON.stringify(result);
         }
     }
-    result.message = util.format(...messageParams);
+    result.message = util.formatWithOptions(FORMAT_OPTIONS, ...messageParams);
     for (const param of messageParams) {
         if (param instanceof Error) {
             result.errorType = param?.constructor?.name ?? "UnknownError";
@@ -4117,6 +4236,20 @@ const createDefaultLogger = (executionContext) => {
     return new DefaultLogger(executionContext);
 };
 
+/**
+ * SDK metadata injected by Rollup at build time from package.json.
+ *
+ * At build time, Rollup replaces "@aws/durable-execution-sdk-js" and
+ * "1.0.3" with actual values from package.json.
+ *
+ * Defaults are provided for test environments where Rollup doesn't run
+ * and process.env values are undefined.
+ *
+ * @internal
+ */
+const SDK_NAME = "@aws/durable-execution-sdk-js";
+const SDK_VERSION = "1.0.3";
+
 let defaultLambdaClient;
 /**
  * Durable execution client which uses an API-based LambdaClient
@@ -4131,6 +4264,7 @@ class DurableExecutionApiClient {
         if (!client) {
             if (!defaultLambdaClient) {
                 defaultLambdaClient = new LambdaClient({
+                    customUserAgent: [[SDK_NAME, SDK_VERSION]],
                     requestHandler: {
                         connectionTimeout: 5000,
                         socketTimeout: 50000,
@@ -4329,8 +4463,9 @@ async function runHandler(event, context, executionContext, durableExecutionMode
     const durableContext = createDurableContext(executionContext, context, durableExecutionMode, 
     // Default logger may not have the same type as Logger, but we should always provide a default logger even if the user overrides it
     createDefaultLogger(), undefined, durableExecution);
-    // Extract customerHandlerEvent from the original event
-    const initialExecutionEvent = event.InitialExecutionState.Operations?.[0];
+    // Extract customerHandlerEvent from the complete operations array (after pagination)
+    // This ensures we get the full payload even for large payloads that are paginated
+    const initialExecutionEvent = executionContext._stepData[Object.keys(executionContext._stepData)[0]];
     const customerHandlerEvent = JSON.parse(initialExecutionEvent?.ExecutionDetails?.InputPayload ?? "{}");
     try {
         log("🎯", `Starting handler execution, handler event: ${customerHandlerEvent}`);
@@ -4477,16 +4612,10 @@ async function runHandler(event, context, executionContext, durableExecutionMode
  * Validates that the event is a proper durable execution input
  */
 function validateDurableExecutionEvent(event) {
-    try {
-        const eventObj = event;
-        if (!eventObj?.DurableExecutionArn || !eventObj?.CheckpointToken) {
-            throw new Error("Missing required durable execution fields");
-        }
-    }
-    catch {
-        const msg = `Unexpected payload provided to start the durable execution. 
-Check your resource configurations to confirm the durability is set.`;
-        throw new Error(msg);
+    const eventObj = event;
+    if (!eventObj?.DurableExecutionArn || !eventObj?.CheckpointToken) {
+        throw new Error("Unexpected payload provided to start the durable execution.\n" +
+            "Check your resource configurations to confirm the durability is set.");
     }
 }
 /**
@@ -4564,14 +4693,7 @@ const withDurableExecution = (handler, config) => {
     return async (event, context) => {
         validateDurableExecutionEvent(event);
         const { executionContext, durableExecutionMode, checkpointToken } = await initializeExecutionContext(event, context, config?.client);
-        let response = null;
-        try {
-            response = await runHandler(event, context, executionContext, durableExecutionMode, checkpointToken, handler);
-            return response;
-        }
-        catch (err) {
-            throw err;
-        }
+        return runHandler(event, context, executionContext, durableExecutionMode, checkpointToken, handler);
     };
 };