@aws/durable-execution-sdk-js 1.1.1 → 2.0.0-alpha.1

package/dist/index.mjs

@@ -4,7 +4,17 @@ import { AsyncLocalStorage } from 'async_hooks';
 import { createHash } from 'crypto';
 import { Console } from 'node:console';
 import util from 'node:util';
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 
+
+// -- Shims --
+import cjsUrl from 'node:url';
+import cjsPath from 'node:path';
+import cjsModule from 'node:module';
+const __filename = cjsUrl.fileURLToPath(import.meta.url);
+const __dirname = cjsPath.dirname(__filename);
+const require = cjsModule.createRequire(import.meta.url);
 /**
  * @internal
  */
@@ -233,6 +243,35 @@ var JitterStrategy;
     JitterStrategy["HALF"] = "HALF";
 })(JitterStrategy || (JitterStrategy = {}));
 
+/**
+ * Nesting type for batch operations (map and parallel)
+ *
+ * Controls how child contexts are created for each branch/iteration, affecting
+ * observability, cost, and scale limits.
+ *
+ * @public
+ */
+var NestingType;
+(function (NestingType) {
+    /**
+     * Create CONTEXT operations for each branch/iteration with full checkpointing.
+     * Operations within each branch/iteration are wrapped in their own context.
+     *
+     * - **Observability**: High - each branch/iteration appears as separate operation in execution history
+     * - **Cost**: Higher - consumes more operations due to CONTEXT creation overhead
+     * - **Scale**: Lower maximum iterations due to operation limits
+     */
+    NestingType["NESTED"] = "NESTED";
+    /**
+     * Skip CONTEXT operations for branches/iterations using virtual contexts.
+     * Operations execute directly without individual context wrapping.
+     *
+     * - **Observability**: Lower - branches/iterations don't appear as separate operations
+     * - **Cost**: ~30% lower - reduces operation consumption by skipping CONTEXT overhead
+     * - **Scale**: Higher maximum iterations possible within operation limits
+     */
+    NestingType["FLAT"] = "FLAT";
+})(NestingType || (NestingType = {}));
 /**
  * The status of a batch item
  * @public
@@ -557,15 +596,39 @@ const createRetryStrategy = (config = {}) => {
     };
 };
 
+/**
+ * Creates a linear backoff retry strategy
+ * @param maxAttempts - Maximum number of attempts (default: 6)
+ * @param initialDelay - Initial delay in seconds (default: 1)
+ * @param increment - Linear increment per attempt in seconds (default: 1)
+ * @returns Retry strategy with linear backoff
+ */
+const createLinearRetryStrategy = (maxAttempts = 6, initialDelay = 1, increment = 1) => {
+    return (error, attemptsMade) => {
+        if (attemptsMade >= maxAttempts) {
+            return { shouldRetry: false };
+        }
+        return {
+            shouldRetry: true,
+            delay: { seconds: initialDelay + increment * (attemptsMade - 1) },
+        };
+    };
+};
+
 /**
  * Pre-configured retry strategies for common use cases
  * @example
  * ```typescript
- * // Use default retry preset (3 attempts with exponential backoff)
+ * // Use default retry preset (6 attempts with exponential backoff)
  * await context.step('my-step', async () => {
  *   return await someOperation();
  * }, { retryStrategy: retryPresets.default });
  *
+ * // Use linear retry preset (1s, 2s, 3s, 4s, 5s delays)
+ * await context.step('linear-step', async () => {
+ *   return await someOperation();
+ * }, { retryStrategy: retryPresets.linear });
+ *
  * // Use no-retry preset (fail immediately on error)
  * await context.step('critical-step', async () => {
  *   return await criticalOperation();
@@ -591,6 +654,13 @@ const retryPresets = {
         backoffRate: 2,
         jitter: JitterStrategy.FULL,
     }),
+    /**
+     * Linear retry strategy with fixed increment
+     * - 6 total attempts (1 initial + 5 retries)
+     * - Delays: 1s, 2s, 3s, 4s, 5s
+     * - Total max wait time: 15 seconds
+     */
+    linear: createLinearRetryStrategy(6, 1, 1),
     /**
      * No retry strategy - fails immediately on first error
      * - 1 total attempt (no retries)
@@ -631,6 +701,12 @@ const CHECKPOINT_TERMINATION_COOLDOWN_MS = 20;
  * and limit polling duration for long-running operations
  */
 const MAX_POLL_DURATION_MS = 15 * 60 * 1000;
+/**
+ * Maximum checkpoint payload size in bytes (256KB).
+ * Payloads exceeding this limit trigger ReplayChildren mode in child contexts,
+ * and overflow-to-file behavior in FileSystemSerdes.
+ */
+const CHECKPOINT_SIZE_LIMIT_BYTES = 256 * 1024;
 
 /**
  * Base class for all durable operation errors
@@ -659,6 +735,10 @@ class DurableOperationError extends Error {
                 return new StepError(errorObject.ErrorMessage || "Step failed", cause, errorObject.ErrorData);
             case "CallbackError":
                 return new CallbackError(errorObject.ErrorMessage || "Callback failed", cause, errorObject.ErrorData);
+            case "CallbackTimeoutError":
+                return new CallbackTimeoutError(errorObject.ErrorMessage || "Callback timed out", cause, errorObject.ErrorData);
+            case "CallbackSubmitterError":
+                return new CallbackSubmitterError(errorObject.ErrorMessage || "Callback submitter failed", cause, errorObject.ErrorData);
             case "InvokeError":
                 return new InvokeError(errorObject.ErrorMessage || "Invoke failed", cause, errorObject.ErrorData);
             case "ChildContextError":
@@ -701,6 +781,26 @@ class CallbackError extends DurableOperationError {
         super(message || "Callback failed", cause, errorData);
     }
 }
+/**
+ * Error thrown when a callback operation times out
+ * @public
+ */
+class CallbackTimeoutError extends DurableOperationError {
+    errorType = "CallbackTimeoutError";
+    constructor(message, cause, errorData) {
+        super(message || "Callback timed out", cause, errorData);
+    }
+}
+/**
+ * Error thrown when a callback submitter fails
+ * @public
+ */
+class CallbackSubmitterError extends DurableOperationError {
+    errorType = "CallbackSubmitterError";
+    constructor(message, cause, errorData) {
+        super(message || "Callback submitter failed", cause, errorData);
+    }
+}
 /**
  * Error thrown when an invoke operation fails
  * @public
@@ -721,6 +821,16 @@ class ChildContextError extends DurableOperationError {
         super(message || "Child context failed", cause, errorData);
     }
 }
+/**
+ * Error thrown when a promise combinator operation fails
+ * @public
+ */
+class PromiseCombinatorError extends DurableOperationError {
+    errorType = "PromiseCombinatorError";
+    constructor(message, cause, errorData) {
+        super(message || "Promise combinator failed", cause, errorData);
+    }
+}
 /**
  * Error thrown when a wait for condition operation fails
  * @public
@@ -1120,7 +1230,7 @@ const validateReplayConsistency = (stepId, currentOperation, checkpointData, con
     }
 };
 
-const createStepHandler = (context, checkpoint, parentContext, createStepId, logger, parentId) => {
+const createStepHandler = (context, checkpoint, parentContext, createStepId, logger, parentId, getDefaultSerdes) => {
     return (nameOrFn, fnOrOptions, maybeOptions) => {
         let name;
         let fn;
@@ -1136,7 +1246,8 @@ const createStepHandler = (context, checkpoint, parentContext, createStepId, log
         }
         const stepId = createStepId();
         const semantics = options?.semantics || StepSemantics.AtLeastOncePerRetry;
-        const serdes = options?.serdes || defaultSerdes;
+        const serdes = options?.serdes ||
+            (getDefaultSerdes ? getDefaultSerdes() : defaultSerdes);
         // Phase 1: Execute step
         const phase1Promise = (async () => {
             let stepData = context.getStepData(stepId);
@@ -1351,7 +1462,7 @@ const createStepHandler = (context, checkpoint, parentContext, createStepId, log
     };
 };
 
-const createInvokeHandler = (context, checkpoint, createStepId, parentId, checkAndUpdateReplayMode) => {
+const createInvokeHandler = (context, checkpoint, createStepId, parentId, checkAndUpdateReplayMode, getDefaultSerdes) => {
     function invokeHandler(nameOrFuncId, funcIdOrInput, inputOrConfig, maybeConfig) {
         const isNameFirst = typeof funcIdOrInput === "string";
         const name = isNameFirst ? nameOrFuncId : undefined;
@@ -1409,7 +1520,8 @@ const createInvokeHandler = (context, checkpoint, createStepId, parentId, checkA
             }
             // Start invoke if not already started
             if (!stepData) {
-                const serializedPayload = await safeSerialize(config?.payloadSerdes || defaultSerdes, input, stepId, name, context.terminationManager, context.durableExecutionArn);
+                const serializedPayload = await safeSerialize(config?.payloadSerdes ||
+                    (getDefaultSerdes ? getDefaultSerdes() : defaultSerdes), input, stepId, name, context.terminationManager, context.durableExecutionArn);
                 await checkpoint.checkpoint(stepId, {
                     Id: stepId,
                     ParentId: parentId,
@@ -1444,7 +1556,8 @@ const createInvokeHandler = (context, checkpoint, createStepId, parentId, checkA
                 const stepData = context.getStepData(stepId);
                 if (stepData?.Status === OperationStatus.SUCCEEDED) {
                     const invokeDetails = stepData.ChainedInvokeDetails;
-                    return await safeDeserialize(config?.resultSerdes || defaultSerdes, invokeDetails?.Result, stepId, name, context.terminationManager, context.durableExecutionArn);
+                    return await safeDeserialize(config?.resultSerdes ||
+                        (getDefaultSerdes ? getDefaultSerdes() : defaultSerdes), invokeDetails?.Result, stepId, name, context.terminationManager, context.durableExecutionArn);
                 }
                 // Handle failure
                 const invokeDetails = stepData?.ChainedInvokeDetails;
@@ -1466,7 +1579,8 @@ const createInvokeHandler = (context, checkpoint, createStepId, parentId, checkA
                 checkAndUpdateReplayMode?.();
                 checkpoint.markOperationState(stepId, OperationLifecycleState.COMPLETED);
                 const invokeDetails = stepData.ChainedInvokeDetails;
-                return await safeDeserialize(config?.resultSerdes || defaultSerdes, invokeDetails?.Result, stepId, name, context.terminationManager, context.durableExecutionArn);
+                return await safeDeserialize(config?.resultSerdes ||
+                    (getDefaultSerdes ? getDefaultSerdes() : defaultSerdes), invokeDetails?.Result, stepId, name, context.terminationManager, context.durableExecutionArn);
             }
             // Handle failure
             log("❌", "Invoke failed:", { stepId, status: stepData?.Status });
@@ -1485,8 +1599,6 @@ const createInvokeHandler = (context, checkpoint, createStepId, parentId, checkA
     return invokeHandler;
 };
 
-// Checkpoint size limit in bytes (256KB)
-const CHECKPOINT_SIZE_LIMIT = 256 * 1024;
 const determineChildReplayMode = (context, stepId) => {
     const stepData = context.getStepData(stepId);
     if (!stepData) {
@@ -1502,7 +1614,7 @@ const determineChildReplayMode = (context, stepId) => {
     }
     return DurableExecutionMode.ExecutionMode;
 };
-const createRunInChildContextHandler = (context, checkpoint, parentContext, createStepId, getParentLogger, createChildContext, parentId) => {
+const createRunInChildContextHandler = (context, checkpoint, parentContext, createStepId, getParentLogger, createChildContext, parentId, getDefaultSerdes) => {
     return (nameOrFn, fnOrOptions, maybeOptions) => {
         let name;
         let fn;
@@ -1540,10 +1652,10 @@ const createRunInChildContextHandler = (context, checkpoint, parentContext, crea
                 currentStepData?.Status === OperationStatus.FAILED) {
                 // Mark this run-in-child-context as finished to prevent descendant operations
                 checkpoint.markAncestorFinished(entityId);
-                return handleCompletedChildContext(context, parentContext, entityId, name, fn, options, getParentLogger, createChildContext);
+                return handleCompletedChildContext(context, parentContext, entityId, name, fn, options, getParentLogger, createChildContext, getDefaultSerdes);
             }
             // Execute if not completed
-            return executeChildContext(context, checkpoint, parentContext, entityId, name, fn, options, getParentLogger, createChildContext, parentId);
+            return executeChildContext(context, checkpoint, parentContext, entityId, name, fn, options, getParentLogger, createChildContext, parentId, getDefaultSerdes);
         })()
             .then((result) => {
             phase1Result = result;
@@ -1561,14 +1673,19 @@ const createRunInChildContextHandler = (context, checkpoint, parentContext, crea
         });
     };
 };
-const handleCompletedChildContext = async (context, parentContext, entityId, stepName, fn, options, getParentLogger, createChildContext) => {
-    const serdes = options?.serdes || defaultSerdes;
+const handleCompletedChildContext = async (context, parentContext, entityId, stepName, fn, options, getParentLogger, createChildContext, getDefaultSerdes) => {
+    const serdes = options?.serdes || (getDefaultSerdes ? getDefaultSerdes() : defaultSerdes);
+    const errorMapper = options?.errorMapper;
     const stepData = context.getStepData(entityId);
     const result = stepData?.ContextDetails?.Result;
     // Handle failed child context
     if (stepData?.Status === OperationStatus.FAILED) {
         if (stepData.ContextDetails?.Error) {
             const originalError = DurableOperationError.fromErrorObject(stepData.ContextDetails.Error);
+            // Use errorMapper if provided, otherwise wrap in ChildContextError
+            if (errorMapper) {
+                throw errorMapper(originalError);
+            }
             throw new ChildContextError(originalError.message, originalError);
         }
         else {
@@ -1587,10 +1704,12 @@ const handleCompletedChildContext = async (context, parentContext, entityId, ste
     });
     return await safeDeserialize(serdes, result, entityId, stepName, context.terminationManager, context.durableExecutionArn);
 };
-const executeChildContext = async (context, checkpoint, parentContext, entityId, name, fn, options, getParentLogger, createChildContext, parentId) => {
-    const serdes = options?.serdes || defaultSerdes;
-    // Checkpoint at start if not already started (fire-and-forget for performance)
-    if (context.getStepData(entityId) === undefined) {
+const executeChildContext = async (context, checkpoint, parentContext, entityId, name, fn, options, getParentLogger, createChildContext, parentId, getDefaultSerdes) => {
+    const serdes = options?.serdes || (getDefaultSerdes ? getDefaultSerdes() : defaultSerdes);
+    const errorMapper = options?.errorMapper;
+    const isVirtual = options?.virtualContext === true;
+    // Checkpoint at start if not already started and not virtual (fire-and-forget for performance)
+    if (!isVirtual && context.getStepData(entityId) === undefined) {
         const subType = options?.subType || OperationSubType.RUN_IN_CHILD_CONTEXT;
         checkpoint.checkpoint(entityId, {
             Id: entityId,
@@ -1602,8 +1721,14 @@ const executeChildContext = async (context, checkpoint, parentContext, entityId,
         });
     }
     const childReplayMode = determineChildReplayMode(context, entityId);
-    // Create a child context with the entity ID as prefix
-    const durableChildContext = createChildContext(context, parentContext, childReplayMode, getParentLogger(), entityId, undefined, entityId);
+    // Create a child context with appropriate parentId and stepPrefix
+    const durableChildContext = createChildContext(context, parentContext, childReplayMode, getParentLogger(), entityId, // stepPrefix: use entityId for unique step IDs
+    undefined, 
+    // parentId: this parameter is used for checkpointing, and should point to
+    // valid parentId tthat is already checkpointed.
+    // If this runInChildContext is a virtual, then we will use the parentId  (the ancestor)
+    // But if this runInChildContext is a virtual, then it's entityId can be used
+    isVirtual ? parentId : entityId);
     try {
         // Execute the child context function with context tracking
         const result = await runWithContext(entityId, parentId, () => fn(durableChildContext), undefined, childReplayMode);
@@ -1613,7 +1738,7 @@ const executeChildContext = async (context, checkpoint, parentContext, entityId,
         let payloadToCheckpoint = serializedResult;
         let replayChildren = false;
         if (serializedResult &&
-            Buffer.byteLength(serializedResult, "utf8") > CHECKPOINT_SIZE_LIMIT) {
+            Buffer.byteLength(serializedResult, "utf8") > CHECKPOINT_SIZE_LIMIT_BYTES) {
             replayChildren = true;
             // Use summary generator if provided, otherwise use empty string
             if (options?.summaryGenerator) {
@@ -1626,50 +1751,63 @@ const executeChildContext = async (context, checkpoint, parentContext, entityId,
                 entityId,
                 name,
                 payloadSize: Buffer.byteLength(serializedResult, "utf8"),
-                limit: CHECKPOINT_SIZE_LIMIT,
+                limit: CHECKPOINT_SIZE_LIMIT_BYTES,
+            });
+        }
+        // Mark this run-in-child-context as finished to prevent descendant operations (only for non-virtual)
+        if (!isVirtual) {
+            checkpoint.markAncestorFinished(entityId);
+            const subType = options?.subType || OperationSubType.RUN_IN_CHILD_CONTEXT;
+            checkpoint.checkpoint(entityId, {
+                Id: entityId,
+                ParentId: parentId,
+                Action: OperationAction.SUCCEED,
+                SubType: subType,
+                Type: OperationType.CONTEXT,
+                Payload: payloadToCheckpoint,
+                ContextOptions: replayChildren ? { ReplayChildren: true } : undefined,
+                Name: name,
+            });
+            log("✅", "Child context completed successfully:", {
+                entityId,
+                name,
+            });
+        }
+        else {
+            log("✅", "Virtual child context completed successfully:", {
+                entityId,
+                name,
             });
         }
-        // Mark this run-in-child-context as finished to prevent descendant operations
-        checkpoint.markAncestorFinished(entityId);
-        const subType = options?.subType || OperationSubType.RUN_IN_CHILD_CONTEXT;
-        checkpoint.checkpoint(entityId, {
-            Id: entityId,
-            ParentId: parentId,
-            Action: OperationAction.SUCCEED,
-            SubType: subType,
-            Type: OperationType.CONTEXT,
-            Payload: payloadToCheckpoint,
-            ContextOptions: replayChildren ? { ReplayChildren: true } : undefined,
-            Name: name,
-        });
-        log("✅", "Child context completed successfully:", {
-            entityId,
-            name,
-        });
         return result;
     }
     catch (error) {
-        log("❌", "Child context failed:", {
+        log("❌", isVirtual ? "Virtual child context failed:" : "Child context failed:", {
             entityId,
             name,
             error,
         });
-        // Mark this run-in-child-context as finished to prevent descendant operations
-        checkpoint.markAncestorFinished(entityId);
-        // Always checkpoint failures
-        const subType = options?.subType || OperationSubType.RUN_IN_CHILD_CONTEXT;
-        checkpoint.checkpoint(entityId, {
-            Id: entityId,
-            ParentId: parentId,
-            Action: OperationAction.FAIL,
-            SubType: subType,
-            Type: OperationType.CONTEXT,
-            Error: createErrorObjectFromError(error),
-            Name: name,
-        });
-        // Reconstruct error from ErrorObject for deterministic behavior
+        // Mark this run-in-child-context as finished and checkpoint failure (only for non-virtual)
+        if (!isVirtual) {
+            checkpoint.markAncestorFinished(entityId);
+            const subType = options?.subType || OperationSubType.RUN_IN_CHILD_CONTEXT;
+            checkpoint.checkpoint(entityId, {
+                Id: entityId,
+                ParentId: parentId,
+                Action: OperationAction.FAIL,
+                SubType: subType,
+                Type: OperationType.CONTEXT,
+                Error: createErrorObjectFromError(error),
+                Name: name,
+            });
+        }
+        // Always wrap in ChildContextError for consistent error handling
         const errorObject = createErrorObjectFromError(error);
         const reconstructedError = DurableOperationError.fromErrorObject(errorObject);
+        // Use errorMapper if provided, otherwise wrap in ChildContextError
+        if (errorMapper) {
+            throw errorMapper(reconstructedError);
+        }
         throw new ChildContextError(reconstructedError.message, reconstructedError);
     }
 };
@@ -1776,7 +1914,7 @@ const createWaitHandler = (context, checkpoint, createStepId, parentId, checkAnd
     return waitHandler;
 };
 
-const createWaitForConditionHandler = (context, checkpoint, createStepId, logger, parentId) => {
+const createWaitForConditionHandler = (context, checkpoint, createStepId, logger, parentId, getDefaultSerdes) => {
     return (nameOrCheck, checkOrConfig, maybeConfig) => {
         let name;
         let check;
@@ -1794,7 +1932,7 @@ const createWaitForConditionHandler = (context, checkpoint, createStepId, logger
             throw new Error("waitForCondition requires config with waitStrategy and initialState");
         }
         const stepId = createStepId();
-        const serdes = config.serdes || defaultSerdes;
+        const serdes = config.serdes || (getDefaultSerdes ? getDefaultSerdes() : defaultSerdes);
         const phase1Promise = (async () => {
             let stepData = context.getStepData(stepId);
             // Check if already completed
@@ -1999,7 +2137,7 @@ const createPassThroughSerdes = () => ({
     serialize: async (value) => value,
     deserialize: async (data) => data,
 });
-const createCallback = (context, checkpoint, createStepId, checkAndUpdateReplayMode, parentId) => {
+const createCallback = (context, checkpoint, createStepId, checkAndUpdateReplayMode, parentId, getDefaultCallbackDeserializer) => {
     return (nameOrConfig, maybeConfig) => {
         let name;
         let config;
@@ -2011,7 +2149,10 @@ const createCallback = (context, checkpoint, createStepId, checkAndUpdateReplayM
             config = nameOrConfig;
         }
         const stepId = createStepId();
-        const serdes = config?.serdes || createPassThroughSerdes();
+        const serdes = config?.serdes ||
+            (getDefaultCallbackDeserializer
+                ? getDefaultCallbackDeserializer()
+                : createPassThroughSerdes());
         // Phase 1: Setup and checkpoint
         let isCompleted = false;
         const phase1Promise = (async () => {
@@ -2103,16 +2244,22 @@ const createCallback = (context, checkpoint, createStepId, checkAndUpdateReplayM
                     const resolvedPromise = new DurablePromise(async () => deserializedResult);
                     return [resolvedPromise, callbackData.CallbackId];
                 }
-                // Handle failure
+                // Handle failure or timeout
                 const error = stepData?.CallbackDetails?.Error;
+                const isTimeout = stepData?.Status === OperationStatus.TIMED_OUT;
                 const callbackError = error
                     ? (() => {
                         const cause = new Error(error.ErrorMessage);
                         cause.name = error.ErrorType || "Error";
                         cause.stack = error.StackTrace?.join("\n");
+                        if (isTimeout) {
+                            return new CallbackTimeoutError(error.ErrorMessage || "Callback timed out", cause, error.ErrorData);
+                        }
                         return new CallbackError(error.ErrorMessage || "Callback failed", cause, error.ErrorData);
                     })()
-                    : new CallbackError("Callback failed");
+                    : isTimeout
+                        ? new CallbackTimeoutError("Callback timed out")
+                        : new CallbackError("Callback failed");
                 const rejectedPromise = new DurablePromise(async () => {
                     throw callbackError;
                 });
@@ -2132,7 +2279,7 @@ const createCallback = (context, checkpoint, createStepId, checkAndUpdateReplayM
     };
 };
 
-const createWaitForCallbackHandler = (context, getNextStepId, runInChildContext) => {
+const createWaitForCallbackHandler = (context, getNextStepId, runInChildContext, getDefaultCallbackDeserializer) => {
     return (nameOrSubmitter, submitterOrConfig, maybeConfig) => {
         let name;
         let submitter;
@@ -2167,11 +2314,16 @@ const createWaitForCallbackHandler = (context, getNextStepId, runInChildContext)
             });
             // Use runInChildContext to ensure proper ID generation and isolation
             const childFunction = async (childCtx) => {
-                // Convert WaitForCallbackConfig to CreateCallbackConfig
-                const createCallbackConfig = config
+                // Convert WaitForCallbackConfig to CreateCallbackConfig.
+                // When a defaultCallbackDeserializer is configured, force passthrough serdes
+                // on the inner createCallback so the raw string is preserved for phase 2.
+                const createCallbackConfig = config || getDefaultCallbackDeserializer
                     ? {
-                        timeout: config.timeout,
-                        heartbeatTimeout: config.heartbeatTimeout,
+                        timeout: config?.timeout,
+                        heartbeatTimeout: config?.heartbeatTimeout,
+                        ...(getDefaultCallbackDeserializer && {
+                            serdes: createPassThroughSerdes(),
+                        }),
                     }
                     : undefined;
                 // Create callback and get the promise + callbackId
@@ -2209,6 +2361,26 @@ const createWaitForCallbackHandler = (context, getNextStepId, runInChildContext)
             return {
                 result: await runInChildContext(name, childFunction, {
                     subType: OperationSubType.WAIT_FOR_CALLBACK,
+                    // When a defaultCallbackDeserializer is configured, use passthrough serdes
+                    // so the raw callback string is preserved through the runInChildContext
+                    // round-trip and phase 2 can apply the deserializer exactly once.
+                    // Without this, defaultSerdes (JSON) would add an extra encode/decode layer.
+                    ...(getDefaultCallbackDeserializer && {
+                        serdes: createPassThroughSerdes(),
+                    }),
+                    errorMapper: (originalError) => {
+                        // Pass through callback errors directly (both timeout and failure)
+                        if (originalError.errorType === "CallbackTimeoutError" ||
+                            originalError.errorType === "CallbackError") {
+                            return originalError;
+                        }
+                        // Map step errors to CallbackSubmitterError
+                        if (originalError.errorType === "StepError") {
+                            return new CallbackSubmitterError(originalError.message, originalError);
+                        }
+                        // Wrap other errors in ChildContextError
+                        return new ChildContextError(originalError.message, originalError);
+                    },
                 }),
                 stepId,
             };
@@ -2220,7 +2392,10 @@ const createWaitForCallbackHandler = (context, getNextStepId, runInChildContext)
         return new DurablePromise(async () => {
             const { result, stepId } = await phase1Promise;
             // Always deserialize the result since it's a string
-            return (await safeDeserialize(config?.serdes ?? createPassThroughSerdes(), result, stepId, name, context.terminationManager, context.durableExecutionArn));
+            return (await safeDeserialize(config?.serdes ??
+                (getDefaultCallbackDeserializer
+                    ? getDefaultCallbackDeserializer()
+                    : createPassThroughSerdes()), result, stepId, name, context.terminationManager, context.durableExecutionArn));
         });
     };
 };
@@ -2304,6 +2479,7 @@ const createMapHandler = (context, executeConcurrently) => {
                 completionConfig: config?.completionConfig,
                 serdes: config?.serdes,
                 itemSerdes: config?.itemSerdes,
+                nesting: config?.nesting,
             });
             log("🗺️", "Map operation completed successfully:", {
                 resultCount: result.totalCount,
@@ -2384,6 +2560,7 @@ const createParallelHandler = (context, executeConcurrently) => {
                 completionConfig: config?.completionConfig,
                 serdes: config?.serdes,
                 itemSerdes: config?.itemSerdes,
+                nesting: config?.nesting,
             });
             log("🔀", "Parallel operation completed successfully:", {
                 resultCount: result.totalCount,
@@ -2445,13 +2622,7 @@ function createErrorAwareSerdes() {
             : undefined,
     };
 }
-// No-retry strategy for promise combinators
-const stepConfig = {
-    retryStrategy: () => ({
-        shouldRetry: false,
-    }),
-};
-const createPromiseHandler = (step) => {
+const createPromiseHandler = (runInChildContext) => {
     const parseParams = (nameOrPromises, maybePromises) => {
         if (typeof nameOrPromises === "string" || nameOrPromises === undefined) {
             return { name: nameOrPromises, promises: maybePromises };
@@ -2461,32 +2632,38 @@ const createPromiseHandler = (step) => {
     const all = (nameOrPromises, maybePromises) => {
         return new DurablePromise(async () => {
             const { name, promises } = parseParams(nameOrPromises, maybePromises);
-            // Wrap Promise.all execution in a step for persistence
-            return await step(name, () => Promise.all(promises), stepConfig);
+            // Wrap Promise.all execution in a child context for persistence
+            return await runInChildContext(name, () => Promise.all(promises), {
+                errorMapper: (error) => new PromiseCombinatorError(error.message, error),
+            });
         });
     };
     const allSettled = (nameOrPromises, maybePromises) => {
         return new DurablePromise(async () => {
             const { name, promises } = parseParams(nameOrPromises, maybePromises);
-            // Wrap Promise.allSettled execution in a step for persistence
-            return await step(name, () => Promise.allSettled(promises), {
-                ...stepConfig,
+            // Wrap Promise.allSettled execution in a child context for persistence
+            return await runInChildContext(name, () => Promise.allSettled(promises), {
                 serdes: createErrorAwareSerdes(),
+                errorMapper: (error) => new PromiseCombinatorError(error.message, error),
             });
         });
     };
     const any = (nameOrPromises, maybePromises) => {
         return new DurablePromise(async () => {
             const { name, promises } = parseParams(nameOrPromises, maybePromises);
-            // Wrap Promise.any execution in a step for persistence
-            return await step(name, () => Promise.any(promises), stepConfig);
+            // Wrap Promise.any execution in a child context for persistence
+            return await runInChildContext(name, () => Promise.any(promises), {
+                errorMapper: (error) => new PromiseCombinatorError(error.message, error),
+            });
         });
     };
     const race = (nameOrPromises, maybePromises) => {
         return new DurablePromise(async () => {
             const { name, promises } = parseParams(nameOrPromises, maybePromises);
-            // Wrap Promise.race execution in a step for persistence
-            return await step(name, () => Promise.race(promises), stepConfig);
+            // Wrap Promise.race execution in a child context for persistence
+            return await runInChildContext(name, () => Promise.race(promises), {
+                errorMapper: (error) => new PromiseCombinatorError(error.message, error),
+            });
         });
     };
     return {
@@ -2576,9 +2753,11 @@ function restoreBatchResult(data) {
 class ConcurrencyController {
     operationName;
     skipNextOperation;
-    constructor(operationName, skipNextOperation) {
+    getDefaultSerdes;
+    constructor(operationName, skipNextOperation, getDefaultSerdes) {
         this.operationName = operationName;
         this.skipNextOperation = skipNextOperation;
+        this.getDefaultSerdes = getDefaultSerdes;
     }
     isChildEntityCompleted(executionContext, parentEntityId, completedCount) {
         const childEntityId = `${parentEntityId}-${completedCount + 1}`;
@@ -2636,7 +2815,8 @@ class ConcurrencyController {
                 const summaryPayload = stepData?.ContextDetails?.Result;
                 if (summaryPayload) {
                     try {
-                        const serdes = config.serdes || defaultSerdes;
+                        const serdes = config.serdes ||
+                            (this.getDefaultSerdes ? this.getDefaultSerdes() : defaultSerdes);
                         const parsedSummary = await serdes.deserialize(summaryPayload, {
                             entityId: entityId,
                             durableExecutionArn: executionContext.durableExecutionArn,
@@ -2699,7 +2879,11 @@ class ConcurrencyController {
                 continue;
             }
             try {
-                const result = await parentContext.runInChildContext(item.name || item.id, (childContext) => executor(item, childContext), { subType: config.iterationSubType, serdes: config.itemSerdes });
+                const result = await parentContext.runInChildContext(item.name || item.id, (childContext) => executor(item, childContext), {
+                    subType: config.iterationSubType,
+                    serdes: config.itemSerdes,
+                    virtualContext: config.nesting === NestingType.FLAT,
+                });
                 resultItems.push({
                     result,
                     index: item.index,
@@ -2804,7 +2988,11 @@ class ConcurrencyController {
                         itemName: item.name,
                     });
                     parentContext
-                        .runInChildContext(item.name || item.id, (childContext) => executor(item, childContext), { subType: config.iterationSubType, serdes: config.itemSerdes })
+                        .runInChildContext(item.name || item.id, (childContext) => executor(item, childContext), {
+                        subType: config.iterationSubType,
+                        serdes: config.itemSerdes,
+                        virtualContext: config.nesting === NestingType.FLAT,
+                    })
                         .then((result) => {
                         resultItems[index] = {
                             result,
@@ -2874,7 +3062,7 @@ class ConcurrencyController {
         });
     }
 }
-const createConcurrentExecutionHandler = (context, runInChildContext, skipNextOperation) => {
+const createConcurrentExecutionHandler = (context, runInChildContext, skipNextOperation, getDefaultSerdes) => {
     return (nameOrItems, itemsOrExecutor, executorOrConfig, maybeConfig) => {
         // Phase 1: Start execution immediately
         const phase1Promise = (async () => {
@@ -2910,7 +3098,7 @@ const createConcurrentExecutionHandler = (context, runInChildContext, skipNextOp
                 throw new Error(`Invalid maxConcurrency: ${config.maxConcurrency}. Must be a positive number or undefined for unlimited concurrency.`);
             }
             const executeOperation = async (executionContext) => {
-                const concurrencyController = new ConcurrencyController("concurrent-execution", skipNextOperation);
+                const concurrencyController = new ConcurrencyController("concurrent-execution", skipNextOperation, getDefaultSerdes);
                 // Access durableExecutionMode from the context - it's set by runInChildContext
                 // based on determineChildReplayMode logic
                 const durableExecutionMode = executionContext.durableExecutionMode;
@@ -3033,6 +3221,9 @@ class DurableContextImpl {
     _parentId;
     modeManagement;
     durableExecution;
+    _defaultSerdes = defaultSerdes;
+    _defaultCallbackDeserializer = createPassThroughSerdes();
+    _customCallbackDeserializerSet = false;
     logger;
     executionContext;
     constructor(_executionContext, lambdaContext, durableExecutionMode, inheritedLogger, stepPrefix, durableExecution, parentId) {
@@ -3173,14 +3364,14 @@ class DurableContextImpl {
     step(nameOrFn, fnOrOptions, maybeOptions) {
         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, () => this._defaultSerdes);
             return stepHandler(nameOrFn, fnOrOptions, maybeOptions);
         });
     }
     invoke(nameOrFuncId, funcIdOrInput, inputOrConfig, maybeConfig) {
         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), () => this._defaultSerdes);
             return invokeHandler(...[
                 nameOrFuncId,
                 funcIdOrInput,
@@ -3194,7 +3385,17 @@ class DurableContextImpl {
         return this.withDurableModeManagement(() => {
             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);
+            (executionContext, parentContext, durableExecutionMode, inheritedLogger, stepPrefix, _checkpointToken, parentId) => {
+                const childCtx = createDurableContext(executionContext, parentContext, durableExecutionMode, inheritedLogger, stepPrefix, this.durableExecution, parentId);
+                // Propagate serdes config to child context
+                childCtx.configureSerdes({
+                    defaultSerdes: this._defaultSerdes,
+                    ...(this._customCallbackDeserializerSet && {
+                        defaultCallbackDeserializer: this._defaultCallbackDeserializer,
+                    }),
+                });
+                return childCtx;
+            }, this._parentId, () => this._defaultSerdes);
             return blockHandler(nameOrFn, fnOrOptions, maybeOptions);
         });
     }
@@ -3232,24 +3433,39 @@ class DurableContextImpl {
             this.modeAwareLoggingEnabled = config.modeAware;
         }
     }
+    configureSerdes(config) {
+        if (config.defaultSerdes !== undefined) {
+            this._defaultSerdes = config.defaultSerdes;
+        }
+        if (config.defaultCallbackDeserializer !== undefined) {
+            this._defaultCallbackDeserializer = config.defaultCallbackDeserializer;
+            this._customCallbackDeserializerSet = true;
+        }
+    }
     createCallback(nameOrConfig, maybeConfig) {
         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, () => this._defaultCallbackDeserializer);
             return callbackFactory(nameOrConfig, maybeConfig);
         });
     }
     waitForCallback(nameOrSubmitter, submitterOrConfig, maybeConfig) {
         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), 
+            // Only pass the getter when the user has explicitly configured a custom
+            // deserializer. The default is createPassThroughSerdes() which matches
+            // the original behavior, so no injection is needed in that case.
+            this._customCallbackDeserializerSet
+                ? () => this._defaultCallbackDeserializer
+                : undefined);
             return waitForCallbackHandler(nameOrSubmitter, submitterOrConfig, maybeConfig);
         });
     }
     waitForCondition(nameOrCheckFunc, checkFuncOrConfig, maybeConfig) {
         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, () => this._defaultSerdes);
             return typeof nameOrCheckFunc === "string" ||
                 nameOrCheckFunc === undefined
                 ? waitForConditionHandler(nameOrCheckFunc, checkFuncOrConfig, maybeConfig)
@@ -3273,7 +3489,7 @@ class DurableContextImpl {
     _executeConcurrently(nameOrItems, itemsOrExecutor, executorOrConfig, maybeConfig) {
         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), () => this._defaultSerdes);
             const promise = concurrentExecutionHandler(nameOrItems, itemsOrExecutor, executorOrConfig, maybeConfig);
             // Prevent unhandled promise rejections
             promise?.catch(() => { });
@@ -3281,7 +3497,7 @@ class DurableContextImpl {
         });
     }
     get promise() {
-        return createPromiseHandler(this.step.bind(this));
+        return createPromiseHandler(this.runInChildContext.bind(this));
     }
 }
 const createDurableContext = (executionContext, parentContext, durableExecutionMode, inheritedLogger, stepPrefix, durableExecution, parentId) => {
@@ -3311,6 +3527,22 @@ class CheckpointUnrecoverableExecutionError extends UnrecoverableExecutionError
     }
 }
 
+// KMS errors from Lambda that indicate customer-caused key misconfiguration.
+// These arrive as 502 errors but are non-retryable.
+const NON_RETRYABLE_CUSTOMER_ERRORS = new Set([
+    "KMSAccessDeniedException",
+    "KMSDisabledException",
+    "KMSInvalidStateException",
+    "KMSNotFoundException",
+]);
+/**
+ * Returns true if the error is a non-retryable customer error (e.g., KMS key misconfiguration).
+ */
+function isNonRetryableCustomerError(error) {
+    const name = error?.name;
+    return !!name && NON_RETRYABLE_CUSTOMER_ERRORS.has(name);
+}
+
 const STEP_DATA_UPDATED_EVENT = "stepDataUpdated";
 const TERMINAL_STATUSES = [
     OperationStatus.SUCCEEDED,
@@ -3476,6 +3708,11 @@ class CheckpointManager {
             statusCode !== 429) {
             return new CheckpointUnrecoverableExecutionError(`Checkpoint failed: ${errorMessage}`, originalError);
         }
+        // For example: KMS errors from Lambda arrive as 502 errors. These indicate customer-caused
+        // KMS key misconfiguration and should not be retried — treat as execution error.
+        if (isNonRetryableCustomerError(error)) {
+            return new CheckpointUnrecoverableExecutionError(`Checkpoint failed: ${errorMessage}`, originalError);
+        }
         return new CheckpointUnrecoverableInvocationError(`Checkpoint failed: ${errorMessage}`, originalError);
     }
     async processQueue() {
@@ -4243,17 +4480,27 @@ const createDefaultLogger = (executionContext) => {
 
 /**
  * SDK metadata injected by Rollup at build time from package.json.
+ * These values are inserted into UserAgent headers.
+ *
+ * At build time, Rollup replaces "2.0.0-alpha.1"
+ * with actual values from package.json.
  *
- * At build time, Rollup replaces "@aws/durable-execution-sdk-js" and
- * "1.1.1" with actual values from package.json.
+ * SDK_NAME is a fixed string matching the cross-SDK convention:
+ * aws-durable-execution-sdk-\{language\}
+ * Alternate version if SDK path is within the Lambda bundled runtime.
  *
  * 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.1.1";
+const runtimeDir = process.env.LAMBDA_RUNTIME_DIR || "/var/runtime";
+const isRuntimeBundled = typeof __dirname !== "undefined" && __dirname.startsWith(runtimeDir);
+const SDK_NAME = "aws-durable-execution-sdk-js";
+const baseVersion = "2.0.0-alpha.1";
+const SDK_VERSION = isRuntimeBundled
+    ? `${baseVersion}-bundled`
+    : baseVersion;
 
 let defaultLambdaClient;
 /**
@@ -4697,11 +4944,293 @@ function validateDurableExecutionEvent(event) {
 const withDurableExecution = (handler, config) => {
     return async (event, context) => {
         validateDurableExecutionEvent(event);
-        const { executionContext, durableExecutionMode, checkpointToken } = await initializeExecutionContext(event, context, config?.client);
-        return runHandler(event, context, executionContext, durableExecutionMode, checkpointToken, handler);
+        try {
+            const { executionContext, durableExecutionMode, checkpointToken } = await initializeExecutionContext(event, context, config?.client);
+            return await runHandler(event, context, executionContext, durableExecutionMode, checkpointToken, handler);
+        }
+        catch (error) {
+            // Non-retryable customer errors (e.g., KMS key misconfiguration) should
+            // fail the execution immediately rather than retrying the invocation.
+            if (isNonRetryableCustomerError(error)) {
+                return {
+                    Status: InvocationStatus.FAILED,
+                    Error: createErrorObjectFromError(error),
+                };
+            }
+            throw error;
+        }
     };
 };
 
+/**
+ * Controls whether a preview field is matched by name anywhere in the object
+ * tree, or by exact dot-notation path from the root.
+ *
+ * @public
+ */
+var FieldMatchMode;
+(function (FieldMatchMode) {
+    /** Match the field name at any depth in the object tree (default). */
+    FieldMatchMode["ANYWHERE"] = "ANYWHERE";
+    /**
+     * Match by exact dot-notation path from root.
+     * A single segment (e.g. `"email"`) matches only the root-level field.
+     * A dotted path (e.g. `"user.email"`) matches that exact nested location.
+     */
+    FieldMatchMode["PATH"] = "PATH";
+})(FieldMatchMode || (FieldMatchMode = {}));
+/**
+ * Controls which fields are included in the preview by default.
+ *
+ * @public
+ */
+var PreviewMode;
+(function (PreviewMode) {
+    /** Include all fields, then apply `exclude` and `mask` rules. */
+    PreviewMode["INCLUDE_ALL"] = "INCLUDE_ALL";
+    /** Exclude all fields, then apply `include` and `mask` rules. */
+    PreviewMode["EXCLUDE_ALL"] = "EXCLUDE_ALL";
+})(PreviewMode || (PreviewMode = {}));
+/** Returns true if the field at `path` (dot-notation) matches the given PreviewField rule. */
+function fieldMatches(path, field) {
+    const mode = field.match ?? FieldMatchMode.ANYWHERE;
+    if (mode === FieldMatchMode.PATH) {
+        return path === field.name;
+    }
+    return path.split(".").includes(field.name);
+}
+function isMatched(path, fields) {
+    return fields?.some((f) => fieldMatches(path, f)) ?? false;
+}
+/**
+ * Builds a preview object from `value` according to `config`.
+ *
+ * Traverses the object tree and collects fields based on the include/exclude/mask
+ * rules in `config`. The result is a nested object mirroring the original structure,
+ * capped at `config.maxPreviewBytes` (default 4096 bytes).
+ *
+ * Priority rules:
+ * - `exclude` always wins — excluded fields are never shown, even if in `mask`
+ * - `mask` implies visibility — masked fields are shown (with `maskString`) unless excluded
+ *
+ * Limitations:
+ * - Field names containing dots are not supported (indistinguishable from path separators)
+ * - Array structure is not preserved — fields from array elements are merged into a plain object
+ * - When array elements have heterogeneous shapes at the same field path, later elements
+ *   overwrite earlier primitives in the preview (e.g. `[{ user: "arb" }, { user: { email: "x" } }]`
+ *   produces `{ user: { email: "x" } }` — `"arb"` is lost)
+ *
+ * @example
+ * ```typescript
+ * const preview = buildPreview(order, {
+ *   mode: PreviewMode.EXCLUDE_ALL,
+ *   include: [{ name: "id" }, { name: "status" }],
+ *   mask: [{ name: "email" }],
+ * });
+ * // { id: "order-123", status: "pending", user: { email: "***" } }
+ * ```
+ *
+ * @public
+ */
+function buildPreview(value, config) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+    const maskString = config.maskString ?? "***";
+    const maxBytes = config.maxPreviewBytes ?? 4096;
+    const pairs = [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    function collect(obj, pathPrefix) {
+        if (obj === null || typeof obj !== "object")
+            return;
+        if (Array.isArray(obj)) {
+            for (const item of obj) {
+                collect(item, pathPrefix);
+            }
+            return;
+        }
+        for (const key of Object.keys(obj)) {
+            if (DANGEROUS_KEYS.has(key))
+                continue;
+            if (key.includes("."))
+                continue;
+            const path = pathPrefix ? `${pathPrefix}.${key}` : key;
+            const masked = isMatched(path, config.mask);
+            const excluded = isMatched(path, config.exclude);
+            const visible = !excluded &&
+                (masked ||
+                    (config.mode === PreviewMode.INCLUDE_ALL
+                        ? true
+                        : isMatched(path, config.include)));
+            if (!visible) {
+                collect(obj[key], path);
+                continue;
+            }
+            if (masked) {
+                pairs.push([path, maskString]);
+                continue;
+            }
+            if (obj[key] !== null && typeof obj[key] === "object") {
+                collect(obj[key], path);
+            }
+            else {
+                pairs.push([path, obj[key]]);
+            }
+        }
+    }
+    collect(value, "");
+    if (pairs.length === 0)
+        return undefined;
+    const accepted = [];
+    let estimatedSize = 2; // "{}"
+    for (const [path, val] of pairs) {
+        const entrySize = Buffer.byteLength(`"${path}":${JSON.stringify(val)},`, "utf-8");
+        if (estimatedSize + entrySize > maxBytes)
+            break;
+        accepted.push([path, val]);
+        estimatedSize += entrySize;
+    }
+    if (accepted.length === 0)
+        return undefined;
+    const result = {};
+    for (const [path, val] of accepted) {
+        const parts = path.split(".");
+        let node = result;
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (typeof node[parts[i]] !== "object" || node[parts[i]] === null) {
+                node[parts[i]] = {};
+            }
+            node = node[parts[i]];
+        }
+        node[parts[parts.length - 1]] = val;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+
+// Subtract 1KB headroom for the envelope wrapper and other checkpoint metadata
+const OVERFLOW_THRESHOLD_BYTES = CHECKPOINT_SIZE_LIMIT_BYTES - 1024;
+/**
+ * Controls when data is written to the filesystem.
+ *
+ * - `ALWAYS`: Every value is written to a file; the checkpoint stores only a file pointer.
+ *   Best for consistently large payloads or when you want predictable checkpoint sizes.
+ *
+ * - `OVERFLOW`: Data is written inline (as JSON) unless it exceeds the durable function
+ *   checkpoint size limit (~256KB), in which case it overflows to a file.
+ *   Best for mixed workloads where most payloads are small.
+ *
+ * @public
+ */
+var FileSystemSerdesMode;
+(function (FileSystemSerdesMode) {
+    FileSystemSerdesMode["ALWAYS"] = "ALWAYS";
+    FileSystemSerdesMode["OVERFLOW"] = "OVERFLOW";
+})(FileSystemSerdesMode || (FileSystemSerdesMode = {}));
+async function writeToFile(basePath, value, context) {
+    const dir = join(basePath, encodeURIComponent(context.durableExecutionArn));
+    await mkdir(dir, { recursive: true });
+    const filePath = join(dir, `${context.entityId}.json`);
+    await writeFile(filePath, JSON.stringify(value), "utf-8");
+    return filePath;
+}
+/**
+ * Creates a Serdes that stores serialized values on a durable filesystem.
+ *
+ * **⚠️ WARNING: Do NOT use with Lambda's ephemeral `/tmp` storage.**
+ * Lambda's `/tmp` filesystem is local to a single execution environment and is
+ * not shared across invocations or function instances. On replay, a different
+ * execution environment may be used and the file will not be found, causing
+ * deserialization to fail.
+ *
+ * **Use only with a durable, shared filesystem such as:**
+ * - **Amazon S3 Files** — mount an S3 bucket as a filesystem via the Lambda console or IaC
+ * - **Amazon EFS** — mount an EFS file system to your Lambda function
+ *
+ * Both options provide persistence across invocations and are accessible from
+ * multiple concurrent function instances, which is required for correct replay behavior.
+ *
+ * The checkpoint stores a JSON envelope that is either:
+ * - `{"data":"<inline JSON>"}` — value stored inline (OVERFLOW mode, under threshold)
+ * - `{"file":"<path>"}` — value stored in a file
+ * - `{"file":"<path>","preview":{...}}` — file pointer with inline preview (when preview is configured)
+ *
+ * @param basePath - Directory path where data files will be stored (e.g. `/mnt/s3` for S3 Files, `/mnt/efs` for EFS)
+ * @param config - Optional configuration options
+ * @returns A Serdes that reads/writes JSON files under basePath
+ *
+ * @example
+ * ```typescript
+ * // Always write to S3 Files mount (default)
+ * context.configureSerdes({
+ *   defaultSerdes: createFileSystemSerdes("/mnt/s3"),
+ * });
+ *
+ * // Only overflow to filesystem when payload exceeds ~256KB
+ * context.configureSerdes({
+ *   defaultSerdes: createFileSystemSerdes("/mnt/s3", { storageMode: FileSystemSerdesMode.OVERFLOW }),
+ * });
+ *
+ * // With preview: show id and masked email in checkpoint
+ * context.configureSerdes({
+ *   defaultSerdes: createFileSystemSerdes("/mnt/s3", {
+ *     generatePreview: (value) => buildPreview(value, {
+ *       mode: PreviewMode.EXCLUDE_ALL,
+ *       include: [{ name: "id" }, { name: "status" }],
+ *       mask: [{ name: "email" }],
+ *     }),
+ *   }),
+ * });
+ * ```
+ *
+ * Limitations:
+ * - Field names containing dots are not supported in preview field selectors.
+ *   A dot in a field name is indistinguishable from a path separator.
+ * - Array structure is not preserved in preview output — fields from array
+ *   elements are merged into a plain object at the array's path.
+ *
+ * @public
+ */
+function createFileSystemSerdes(basePath, config = {}) {
+    const storageMode = config.storageMode ?? FileSystemSerdesMode.ALWAYS;
+    return {
+        serialize: async (
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        value, context) => {
+            if (value === undefined)
+                return undefined;
+            if (storageMode === FileSystemSerdesMode.ALWAYS) {
+                const filePath = await writeToFile(basePath, value, context);
+                const preview = config.generatePreview?.(value);
+                const envelope = preview
+                    ? { file: filePath, preview }
+                    : { file: filePath };
+                return JSON.stringify(envelope);
+            }
+            // OVERFLOW mode: serialize inline first, overflow to file if too large
+            const inlineJson = JSON.stringify(value);
+            if (Buffer.byteLength(inlineJson, "utf-8") > OVERFLOW_THRESHOLD_BYTES) {
+                const filePath = await writeToFile(basePath, value, context);
+                const preview = config.generatePreview?.(value);
+                const envelope = preview
+                    ? { file: filePath, preview }
+                    : { file: filePath };
+                return JSON.stringify(envelope);
+            }
+            return JSON.stringify({ data: inlineJson });
+        },
+        deserialize: async (data, _context) => {
+            if (data === undefined)
+                return undefined;
+            const envelope = JSON.parse(data);
+            if ("file" in envelope) {
+                const contents = await readFile(envelope.file, "utf-8");
+                return JSON.parse(contents);
+            }
+            return JSON.parse(envelope.data);
+        },
+    };
+}
+
 const DEFAULT_CONFIG = {
     maxAttempts: 60,
     initialDelay: { seconds: 5 },
@@ -4751,5 +5280,42 @@ const createWaitStrategy = (config) => {
     };
 };
 
-export { BatchItemStatus, CallbackError, ChildContextError, DurableExecutionApiClient, DurableExecutionInvocationInputWithClient, DurableOperationError, DurablePromise, InvocationStatus, InvokeError, JitterStrategy, OperationSubType, StepError, StepInterruptedError, StepSemantics, WaitForConditionError, createClassSerdes, createClassSerdesWithDates, createRetryStrategy, createWaitStrategy, defaultSerdes, retryPresets, withDurableExecution };
+async function withRetry(context, nameOrFunc, funcOrConfig, maybeConfig) {
+    const hasName = typeof nameOrFunc === "string";
+    const name = hasName ? nameOrFunc : undefined;
+    const func = (hasName ? funcOrConfig : nameOrFunc);
+    const config = (hasName ? maybeConfig : funcOrConfig);
+    if (!config) {
+        throw new TypeError("withRetry: config is required");
+    }
+    const { retryStrategy, wrapWithRunInChildContext = true, childContextConfig, } = config;
+    const runLoop = async (ctx) => {
+        let attempt = 0;
+        while (true) {
+            attempt++;
+            try {
+                return await func(ctx, attempt);
+            }
+            catch (err) {
+                const decision = retryStrategy(err, attempt);
+                if (!decision.shouldRetry)
+                    throw err;
+                const delay = decision.delay ?? { seconds: 1 };
+                if (name) {
+                    await ctx.wait(`${name}-backoff-${attempt}`, delay);
+                }
+                else {
+                    await ctx.wait(delay);
+                }
+            }
+        }
+    };
+    return wrapWithRunInChildContext
+        ? name
+            ? await context.runInChildContext(name, runLoop, childContextConfig)
+            : await context.runInChildContext(runLoop, childContextConfig)
+        : await runLoop(context);
+}
+
+export { BatchItemStatus, CallbackError, CallbackSubmitterError, CallbackTimeoutError, ChildContextError, DurableExecutionApiClient, DurableExecutionInvocationInputWithClient, DurableOperationError, DurablePromise, FieldMatchMode, FileSystemSerdesMode, InvocationStatus, InvokeError, JitterStrategy, NestingType, OperationSubType, PreviewMode, StepError, StepInterruptedError, StepSemantics, WaitForConditionError, buildPreview, createClassSerdes, createClassSerdesWithDates, createFileSystemSerdes, createLinearRetryStrategy, createRetryStrategy, createWaitStrategy, defaultSerdes, retryPresets, withDurableExecution, withRetry };
 //# sourceMappingURL=index.mjs.map