aws-durable-execution-sdk-python 1.4.0__tar.gz → 1.6.0__tar.gz

{aws_durable_execution_sdk_python-1.4.0 → aws_durable_execution_sdk_python-1.6.0}/.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 *$py.class
 *.egg-info/
 
+*.coverage
 /.coverage
 /.coverage.*
 /.cache
@@ -28,4 +29,9 @@ dist/
 
 .idea
 
-.kiro/
+.kiro/
+
+**/build/
+**/*.zip
+
+.env

{aws_durable_execution_sdk_python-1.4.0 → aws_durable_execution_sdk_python-1.6.0}/PKG-INFO

@@ -1,14 +1,12 @@
 Metadata-Version: 2.4
 Name: aws-durable-execution-sdk-python
-Version: 1.4.0
+Version: 1.6.0
 Summary: AWS Durable Execution SDK for Python
 Project-URL: Documentation, https://github.com/aws/aws-durable-execution-sdk-python#readme
 Project-URL: Issues, https://github.com/aws/aws-durable-execution-sdk-python/issues
 Project-URL: Source, https://github.com/aws/aws-durable-execution-sdk-python
-Author-email: yaythomas <tgaigher@amazon.com>
+Author-email: AWS durable-execution-dev <durable-execution-dev@amazon.com>
 License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.11
@@ -27,7 +25,7 @@ Description-Content-Type: text/markdown
 [![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/aws/aws-durable-execution-sdk-python/badge)](https://scorecard.dev/viewer/?uri=github.com/aws/aws-durable-execution-sdk-python)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/LICENSE)
 
 -----
 
@@ -91,33 +89,10 @@ def handler(event: dict, context: DurableContext) -> dict:
 
 ## 📚 Documentation
 
-- **[AWS Documentation](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html)** - Official AWS Lambda durable functions guide
-- **[Documentation index](docs/index.md)** - SDK Overview and navigation
+The complete documentation for the AWS Durable Execution SDK for Python lives on the AWS Documentation site:
 
-**New to durable functions?**
-- [Getting started guide](docs/getting-started.md) - Build your first durable function
-
-**Core operations:**
-- [Steps](docs/core/steps.md) - Execute code with automatic checkpointing and retry support
-- [Wait operations](docs/core/wait.md) - Pause execution without blocking Lambda resources
-- [Callbacks](docs/core/callbacks.md) - Wait for external systems to respond
-- [Invoke operations](docs/core/invoke.md) - Call other durable functions and compose workflows
-- [Child contexts](docs/core/child-contexts.md) - Organize complex workflows into isolated units
-- [Parallel operations](docs/core/parallel.md) - Run multiple operations concurrently
-- [Map operations](docs/core/map.md) - Process collections in parallel with batching
-- [Logger integration](docs/core/logger.md) - Add structured logging to track execution
-
-**Advanced topics:**
-- [Error handling](docs/advanced/error-handling.md) - Handle failures and implement retry strategies
-- [Testing modes](docs/advanced/testing-modes.md) - Run tests locally or against deployed Lambda functions
-- [Testing patterns](docs/testing-patterns/basic-tests.md) - Practical testing examples
-- [Serialization](docs/advanced/serialization.md) - Customize how data is serialized in checkpoints
-
-**Architecture:**
-- [Architecture diagrams](docs/architecture.md) - Class diagrams and concurrency flows
-
-**API reference:**
-- API reference docs are in progress. Use the core operation docs above for now.
+- **[AWS Durable Execution Documentation](https://docs.aws.amazon.com/durable-execution/)** - Concepts, getting started, core operations, advanced topics, and API reference
+- **[AWS Lambda Durable Functions Guide](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html)** - How durable functions work on Lambda
 
 ## 💬 Feedback & Support
 
@@ -128,4 +103,4 @@ def handler(event: dict, context: DurableContext) -> dict:
 
 ## 📄 License
 
-See the [LICENSE](LICENSE) file for our project's licensing.
+See the [LICENSE](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/LICENSE) file for our project's licensing.

{aws_durable_execution_sdk_python-1.4.0 → aws_durable_execution_sdk_python-1.6.0}/README.md

@@ -4,7 +4,7 @@
 [![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/aws/aws-durable-execution-sdk-python/badge)](https://scorecard.dev/viewer/?uri=github.com/aws/aws-durable-execution-sdk-python)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/LICENSE)
 
 -----
 
@@ -68,33 +68,10 @@ def handler(event: dict, context: DurableContext) -> dict:
 
 ## 📚 Documentation
 
-- **[AWS Documentation](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html)** - Official AWS Lambda durable functions guide
-- **[Documentation index](docs/index.md)** - SDK Overview and navigation
+The complete documentation for the AWS Durable Execution SDK for Python lives on the AWS Documentation site:
 
-**New to durable functions?**
-- [Getting started guide](docs/getting-started.md) - Build your first durable function
-
-**Core operations:**
-- [Steps](docs/core/steps.md) - Execute code with automatic checkpointing and retry support
-- [Wait operations](docs/core/wait.md) - Pause execution without blocking Lambda resources
-- [Callbacks](docs/core/callbacks.md) - Wait for external systems to respond
-- [Invoke operations](docs/core/invoke.md) - Call other durable functions and compose workflows
-- [Child contexts](docs/core/child-contexts.md) - Organize complex workflows into isolated units
-- [Parallel operations](docs/core/parallel.md) - Run multiple operations concurrently
-- [Map operations](docs/core/map.md) - Process collections in parallel with batching
-- [Logger integration](docs/core/logger.md) - Add structured logging to track execution
-
-**Advanced topics:**
-- [Error handling](docs/advanced/error-handling.md) - Handle failures and implement retry strategies
-- [Testing modes](docs/advanced/testing-modes.md) - Run tests locally or against deployed Lambda functions
-- [Testing patterns](docs/testing-patterns/basic-tests.md) - Practical testing examples
-- [Serialization](docs/advanced/serialization.md) - Customize how data is serialized in checkpoints
-
-**Architecture:**
-- [Architecture diagrams](docs/architecture.md) - Class diagrams and concurrency flows
-
-**API reference:**
-- API reference docs are in progress. Use the core operation docs above for now.
+- **[AWS Durable Execution Documentation](https://docs.aws.amazon.com/durable-execution/)** - Concepts, getting started, core operations, advanced topics, and API reference
+- **[AWS Lambda Durable Functions Guide](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html)** - How durable functions work on Lambda
 
 ## 💬 Feedback & Support
 
@@ -105,4 +82,4 @@ def handler(event: dict, context: DurableContext) -> dict:
 
 ## 📄 License
 
-See the [LICENSE](LICENSE) file for our project's licensing.
+See the [LICENSE](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/LICENSE) file for our project's licensing.

{aws_durable_execution_sdk_python-1.4.0 → aws_durable_execution_sdk_python-1.6.0}/pyproject.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
 keywords = []
-authors = [{ name = "yaythomas", email = "tgaigher@amazon.com" }]
+authors = [{ name = "AWS durable-execution-dev", email = "durable-execution-dev@amazon.com" }]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Programming Language :: Python",
@@ -28,23 +28,20 @@ Documentation = "https://github.com/aws/aws-durable-execution-sdk-python#readme"
 Issues = "https://github.com/aws/aws-durable-execution-sdk-python/issues"
 Source = "https://github.com/aws/aws-durable-execution-sdk-python"
 
+[tool.hatch.build.targets.sdist.force-include]
+"../../LICENSE" = "LICENSE"
+"../../NOTICE" = "NOTICE"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/aws_durable_execution_sdk_python"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"../../LICENSE" = "aws_durable_execution_sdk_python/LICENSE"
+"../../NOTICE" = "aws_durable_execution_sdk_python/NOTICE"
+
 [tool.hatch.version]
 path = "src/aws_durable_execution_sdk_python/__about__.py"
 
-[tool.hatch.envs.test]
-dependencies = ["coverage[toml]", "pytest", "pytest-cov"]
-
-[tool.hatch.envs.test.scripts]
-cov = "pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=src/aws_durable_execution_sdk_python --cov-fail-under=98"
-
-[tool.hatch.envs.types]
-extra-dependencies = ["mypy>=1.0.0", "pytest", "boto3-stubs[lambda]"]
-[tool.hatch.envs.types.scripts]
-check = "mypy --install-types --non-interactive {args:src/aws_durable_execution_sdk_python tests}"
-
 [tool.coverage.run]
 source_pkgs = ["aws_durable_execution_sdk_python"]
 branch = true

{aws_durable_execution_sdk_python-1.4.0 → aws_durable_execution_sdk_python-1.6.0}/src/aws_durable_execution_sdk_python/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Amazon.com, Inc. or its affiliates.
 #
 # SPDX-License-Identifier: Apache-2.0
-__version__ = "1.4.0"
+__version__ = "1.6.0"

{aws_durable_execution_sdk_python-1.4.0 → aws_durable_execution_sdk_python-1.6.0}/src/aws_durable_execution_sdk_python/__init__.py

@@ -7,8 +7,10 @@ from aws_durable_execution_sdk_python.__about__ import __version__
 # Helper decorators - commonly used for step functions
 # Concurrency
 from aws_durable_execution_sdk_python.concurrency.models import BatchResult
+from aws_durable_execution_sdk_python.config import ParallelBranch
 from aws_durable_execution_sdk_python.context import (
     DurableContext,
+    durable_parallel_branch,
     durable_step,
     durable_wait_for_callback,
     durable_with_child_context,
@@ -23,20 +25,26 @@ from aws_durable_execution_sdk_python.exceptions import (
 
 # Core decorator - used in every durable function
 from aws_durable_execution_sdk_python.execution import durable_execution
+from aws_durable_execution_sdk_python.retries import WithRetryConfig, with_retry
 
 # Essential context types - passed to user functions
 from aws_durable_execution_sdk_python.types import StepContext
 
+
 __all__ = [
     "BatchResult",
     "DurableContext",
     "DurableExecutionsError",
     "InvocationError",
+    "ParallelBranch",
     "StepContext",
     "ValidationError",
+    "WithRetryConfig",
     "__version__",
     "durable_execution",
+    "durable_parallel_branch",
     "durable_step",
     "durable_wait_for_callback",
     "durable_with_child_context",
+    "with_retry",
 ]

{aws_durable_execution_sdk_python-1.4.0 → aws_durable_execution_sdk_python-1.6.0}/src/aws_durable_execution_sdk_python/concurrency/executor.py

@@ -20,14 +20,17 @@ from aws_durable_execution_sdk_python.concurrency.models import (
     ExecutionCounters,
     SuspendResult,
 )
-from aws_durable_execution_sdk_python.config import ChildConfig
+from aws_durable_execution_sdk_python.config import (
+    ChildConfig,
+    NestingType,
+)
 from aws_durable_execution_sdk_python.exceptions import (
     OrphanedChildException,
     SuspendExecution,
     TimedSuspendExecution,
 )
 from aws_durable_execution_sdk_python.identifier import OperationIdentifier
-from aws_durable_execution_sdk_python.lambda_service import ErrorObject
+from aws_durable_execution_sdk_python.lambda_service import ErrorObject, OperationType
 from aws_durable_execution_sdk_python.operation.child import child_handler
 
 
@@ -56,7 +59,7 @@ class TimerScheduler:
     """Manage timed suspend tasks with a background timer thread."""
 
     def __init__(
-        self, resubmit_callback: Callable[[ExecutableWithState], None]
+        self, resubmit_callback: Callable[[list[ExecutableWithState]], None]
     ) -> None:
         self.resubmit_callback = resubmit_callback
         self._pending_resumes: list[tuple[float, int, ExecutableWithState]] = []
@@ -111,18 +114,31 @@ class TimerScheduler:
 
             current_time = time.time()
             if current_time >= next_resume_time:
-                # Time to resume
+                # Drain every due resume under the lock, transitioning each to
+                # PENDING atomically with the pop. Keeping pop+reset_to_pending
+                # together is required: should_execution_suspend reads branch
+                # status without this lock, so an item that is removed from the
+                # heap but still SUSPENDED_WITH_TIMEOUT could trigger a spurious
+                # parent suspend.
+                ready: list[ExecutableWithState] = []
                 with self._lock:
-                    # no branch cover because hard to test reliably - this is a double-safety check if heap mutated
-                    # since the first peek on next_resume_time further up
-                    if (  # pragma: no branch
+                    while (
                         self._pending_resumes
                         and self._pending_resumes[0][0] <= current_time
                     ):
                         _, _, exe_state = heapq.heappop(self._pending_resumes)
                         if exe_state.can_resume:
                             exe_state.reset_to_pending()
-                            self.resubmit_callback(exe_state)
+                            ready.append(exe_state)
+                # Resubmit outside the lock. Only the heap pop and the PENDING
+                # transition need the lock. The checkpoint refresh is a blocking
+                # network call and the submit hands work to the pool, so running
+                # them off the lock keeps timed resumes from serializing behind
+                # the network round trip and keeps the timer thread from
+                # re-entering this non-reentrant lock when a submitted future
+                # completes inline and its done-callback calls schedule_resume.
+                if ready:
+                    self.resubmit_callback(ready)
             else:
                 # Wait until next resume time
                 wait_time = min(next_resume_time - current_time, 0.1)
@@ -143,6 +159,7 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
         serdes: SerDes | None,
         item_serdes: SerDes | None = None,
         summary_generator: SummaryGenerator | None = None,
+        nesting_type: NestingType = NestingType.NESTED,
     ):
         """Initialize ConcurrentExecutor.
 
@@ -160,10 +177,12 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
         self.sub_type_iteration = sub_type_iteration
         self.name_prefix = name_prefix
         self.summary_generator = summary_generator
+        self.nesting_type = nesting_type
 
         # Event-driven state tracking for when the executor is done
         self._completion_event = threading.Event()
         self._suspend_exception: SuspendExecution | None = None
+        self._resume_error: Exception | None = None
 
         # ExecutionCounters will keep track of completion criteria and on-going counters
         min_successful = self.completion_config.min_successful or len(self.executables)
@@ -189,6 +208,14 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
         """Execute a single executable in a child context and return the result."""
         raise NotImplementedError
 
+    def get_iteration_name(self, index: int) -> str:
+        """Get the display name for an iteration/branch at the given index.
+
+        Subclasses can override this to provide custom naming (e.g., from item_namer
+        or branch names). The default returns "{name_prefix}{index}".
+        """
+        return f"{self.name_prefix}{index}"
+
     def execute(
         self, execution_state: ExecutionState, executor_context: DurableContext
     ) -> BatchResult[ResultType]:
@@ -209,11 +236,32 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
         ]
         self._completion_event.clear()
         self._suspend_exception = None
-
-        def resubmitter(executable_with_state: ExecutableWithState) -> None:
-            """Resubmit a timed suspended task."""
-            execution_state.create_checkpoint()
-            submit_task(executable_with_state)
+        self._resume_error = None
+
+        def resubmitter(ready: list[ExecutableWithState]) -> None:
+            """Resubmit a wave of timed-suspended tasks.
+
+            One checkpoint refresh serves the whole due wave: the fetch returns
+            all operations, so every resumed branch reads fresh state. The
+            refresh only raises when the background checkpoint subsystem has
+            failed, which is terminal for the whole execution, so record the
+            error and wake the parent to re-raise it. Catching here keeps the
+            single timer thread alive so a failure does not strand the other
+            pending resumes.
+            """
+            try:
+                execution_state.create_checkpoint()
+            except Exception as exc:  # noqa: BLE001
+                # resubmitter runs only on the single timer thread, so this
+                # check-then-set needs no lock. First error wins: keep the
+                # earliest failure if several waves fail before execute() reads
+                # it (they are the same terminal checkpoint failure anyway).
+                if self._resume_error is None:  # pragma: no branch
+                    self._resume_error = exc
+                self._completion_event.set()
+                return
+            for executable_with_state in ready:
+                submit_task(executable_with_state)
 
         thread_executor = ThreadPoolExecutor(max_workers=max_workers)
         try:
@@ -246,6 +294,12 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
                 for future in futures:
                     future.cancel()
 
+                # A timed resume failed to refresh state (terminal checkpoint
+                # subsystem failure). Re-raise so the invocation fails and the
+                # backend retries from the last durable checkpoint.
+                if self._resume_error is not None:
+                    raise self._resume_error
+
                 # Suspend execution if everything done and at least one of the tasks raised a suspend exception.
                 if self._suspend_exception:
                     raise self._suspend_exception
@@ -391,29 +445,37 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
         """
         Execute a single item in a derived child context.
 
-        instead of relying on `executor_context.run_in_child_context`
-        we generate an operation_id for the child, and then call `child_handler`
-        directly. This avoids the hidden mutation of the context's internal counter.
-        we can do this because we explicitly control the generation of step_id and do it
-        using executable.index.
-
+        Instead of relying on `executor_context.run_in_child_context` we
+        generate an operation_id for the child, then call `child_handler`
+        directly. This avoids the hidden mutation of the context's
+        internal counter. We explicitly derive the child's operation_id
+        from `executable.index` so that the same input always produces
+        the same id regardless of the order branches actually run in.
 
-        invariant: `operation_id` for a given executable is deterministic,
-            and execution order invariant.
+        Invariant: `operation_id` for a given executable is deterministic
+        and execution-order invariant.
         """
 
-        operation_id = executor_context._create_step_id_for_logical_step(  # noqa: SLF001
+        operation_id: str = executor_context._create_step_id_for_logical_step(  # noqa: SLF001
             executable.index
         )
-        name = f"{self.name_prefix}{executable.index}"
-        child_context = executor_context.create_child_context(operation_id)
+        name: str = self.get_iteration_name(executable.index)
+        is_virtual: bool = self.nesting_type is NestingType.FLAT
+
+        child_context: DurableContext = executor_context.create_child_context(
+            operation_id, is_virtual=is_virtual
+        )
+        # For NESTED this is for branch's START/SUCCEED/FAIL checkpoints (not the children of the branch).
+        # For FLAT `child_handler` skips checkpoints, so not used.
+        # Construct it unconditionally to keep the call simple.
         operation_identifier = OperationIdentifier(
-            operation_id,
-            executor_context._parent_id,  # noqa: SLF001
-            name,
+            operation_id=operation_id,
+            sub_type=self.sub_type_iteration,
+            parent_id=executor_context._parent_id,  # noqa: SLF001
+            name=name,
         )
 
-        def run_in_child_handler():
+        def run_in_child_handler() -> ResultType:
             return self.execute_item(child_context, executable)
 
         result: ResultType = child_handler(
@@ -424,6 +486,7 @@ class ConcurrentExecutor(ABC, Generic[CallableType, ResultType]):
                 serdes=self.item_serdes or self.serdes,
                 sub_type=self.sub_type_iteration,
                 summary_generator=self.summary_generator,
+                is_virtual=is_virtual,
             ),
         )
         child_context.state.track_replay(operation_id=operation_id)

{aws_durable_execution_sdk_python-1.4.0 → aws_durable_execution_sdk_python-1.6.0}/src/aws_durable_execution_sdk_python/config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import math
 import random
 from dataclasses import dataclass, field
 from enum import Enum, StrEnum
@@ -9,6 +10,7 @@ from typing import TYPE_CHECKING, Generic, TypeVar
 
 from aws_durable_execution_sdk_python.exceptions import ValidationError
 
+
 P = TypeVar("P")  # Payload type
 R = TypeVar("R")  # Result type
 T = TypeVar("T")
@@ -76,6 +78,42 @@ class TerminationMode(Enum):
     ABANDON = "ABANDON"
 
 
+class NestingType(Enum):
+    """Control how child contexts are created for batch operations.
+
+    Applies to `map` and `parallel`. Each branch or iteration runs inside a
+    child context.
+
+        - NESTED: full checkpointed context
+        - FLAT: a virtual context that skips checkpoints for the branch/iteration.
+
+    """
+
+    NESTED = "NESTED"
+    """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 a separate
+      operation in execution history.
+    - Cost: higher — consumes more operations due to CONTEXT creation
+      overhead.
+    - Scale: lower maximum iterations due to operation limits.
+    """
+
+    FLAT = "FLAT"
+    """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 in execution history.
+    - Cost: ~30% lower — reduces operation consumption by skipping CONTEXT
+      overhead.
+    - Scale: higher maximum iterations possible within operation limits.
+    """
+
+
 @dataclass(frozen=True)
 class CompletionConfig:
     """Configuration for determining when parallel/map operations complete.
@@ -187,6 +225,10 @@ class ParallelConfig:
             Used internally by map/parallel operations to handle large BatchResult payloads.
             Signature: (result: T) -> str
 
+        nesting_type: How child operations should inherit context from their parent.
+            - NESTED: Each branch runs in its own isolated context (default)
+            - FLAT: All branches share the same parent context
+
     Example:
         # Run at most 3 branches concurrently, succeed if any one succeeds
         config = ParallelConfig(
@@ -202,6 +244,42 @@ class ParallelConfig:
     serdes: SerDes | None = None
     item_serdes: SerDes | None = None
     summary_generator: SummaryGenerator | None = None
+    nesting_type: NestingType = NestingType.NESTED
+
+
+@dataclass(frozen=True)
+class ParallelBranch(Generic[T]):
+    """A named branch for parallel execution.
+
+    Use this to provide custom names for parallel branches, improving
+    observability in execution history.
+
+    Type Parameters:
+        T: The return type of the branch function.
+
+    Args:
+        func: The callable to execute in this branch. Receives a DurableContext.
+        name: Optional custom name for this branch. When provided, replaces
+            the default "parallel-branch-{index}" naming in execution history.
+            This affects observability but not replay determinism.
+
+    Example:
+        context.parallel(
+            functions=[
+                ParallelBranch(func=lambda ctx: fetch_user(ctx), name="fetch-user-data"),
+                ParallelBranch(func=lambda ctx: fetch_orders(ctx), name="fetch-order-history"),
+            ],
+            name="load-data",
+            config=ParallelConfig(max_concurrency=2),
+        )
+    """
+
+    func: Callable
+    name: str | None = None
+
+    def __call__(self, *args, **kwargs):
+        """Delegate to the wrapped function, making ParallelBranch itself callable."""
+        return self.func(*args, **kwargs)
 
 
 class StepSemantics(Enum):
@@ -218,12 +296,6 @@ class StepConfig:
     serdes: SerDes | None = None
 
 
-class CheckpointMode(Enum):
-    NO_CHECKPOINT = ("NO_CHECKPOINT",)
-    CHECKPOINT_AT_FINISH = ("CHECKPOINT_AT_FINISH",)
-    CHECKPOINT_AT_START_AND_FINISH = "CHECKPOINT_AT_START_AND_FINISH"
-
-
 @dataclass(frozen=True)
 class ChildConfig(Generic[T]):
     """Configuration options for child context operations.
@@ -259,21 +331,23 @@ class ChildConfig(Generic[T]):
 
             Used internally by map/parallel operations to handle large BatchResult payloads.
             Signature: (result: T) -> str
-    Note:
-        checkpoint_mode field is commented out as it's not currently implemented.
-        When implemented, it will control when checkpoints are created:
-        - CHECKPOINT_AT_START_AND_FINISH: Checkpoint at both start and completion (default)
-        - CHECKPOINT_AT_FINISH: Only checkpoint when operation completes
-        - NO_CHECKPOINT: No automatic checkpointing
+
+        is_virtual: When True, skip all checkpoints (START, SUCCEED,
+            FAIL) for this child context and propagate the caller's reporting
+            parent id through to operations created inside the child. The
+            branch is a logical scope for step-id prefixing but does not
+            appear in the execution history. Used internally by
+            NestingType.FLAT branches. Use this to group operations without
+            adding a CONTEXT entry to the execution history.
 
     See TypeScript reference: aws-durable-execution-sdk-js/src/types/index.ts
     """
 
-    # checkpoint_mode: CheckpointMode = CheckpointMode.CHECKPOINT_AT_START_AND_FINISH
     serdes: SerDes | None = None
     item_serdes: SerDes | None = None
     sub_type: OperationSubType | None = None
     summary_generator: SummaryGenerator | None = None
+    is_virtual: bool = False
 
 
 class ItemsPerBatchUnit(Enum):
@@ -317,12 +391,15 @@ class ItemBatcher(Generic[T]):
 
 
 @dataclass(frozen=True)
-class MapConfig:
+class MapConfig(Generic[T]):
     """Configuration options for map operations over collections.
 
     This class configures how map operations process collections of items,
     including concurrency, batching, completion criteria, and serialization.
 
+    Type Parameters:
+        T: The type of items being processed in the map operation.
+
     Args:
         max_concurrency: Maximum number of items to process concurrently.
             If None, no limit is imposed and all items are processed concurrently.
@@ -361,6 +438,16 @@ class MapConfig:
             Used internally by map/parallel operations to handle large BatchResult payloads.
             Signature: (result: T) -> str
 
+        nesting_type: How child operations should inherit context from their parent.
+            - NESTED: Each item runs in its own isolated context (default)
+            - FLAT: All items share the same parent context
+
+        item_namer: Optional callable to generate custom names for each map iteration.
+            When provided, replaces the default "map-item-{index}" naming scheme.
+            Receives the item and its index, and returns a string name for that iteration.
+            This affects observability (execution history names) but not replay determinism.
+            If None, uses the default naming: "map-item-{index}".
+
     Example:
         # Process 5 items at a time, batch by count, require all to succeed
         config = MapConfig(
@@ -368,6 +455,12 @@ class MapConfig:
             item_batcher=ItemBatcher(max_items_per_batch=10),
             completion_config=CompletionConfig.all_successful()
         )
+
+        # With custom iteration names
+        config = MapConfig(
+            max_concurrency=5,
+            item_namer=lambda item, index: f"process-order-{item.id}"
+        )
     """
 
     max_concurrency: int | None = None
@@ -376,6 +469,8 @@ class MapConfig:
     serdes: SerDes | None = None
     item_serdes: SerDes | None = None
     summary_generator: SummaryGenerator | None = None
+    nesting_type: NestingType = NestingType.NESTED
+    item_namer: Callable[[T, int], str] | None = None
 
 
 @dataclass(frozen=True)
@@ -495,5 +590,16 @@ class JitterStrategy(StrEnum):
                 # Full jitter: random(0, delay)
                 return random.random() * delay  # noqa: S311
 
+    def finalize_delay(self, base_delay: float) -> int:
+        """Apply jitter, round up, and clamp to a minimum of 1 second.
+
+        Args:
+            base_delay: The base delay value before jitter is applied
+
+        Returns:
+            The final delay in whole seconds, at least 1
+        """
+        return max(1, math.ceil(self.apply_jitter(base_delay)))
+
 
 # endregion Jitter