aws-durable-execution-sdk-python 2.0.1__tar.gz → 3.0.0__tar.gz

{aws_durable_execution_sdk_python-2.0.1 → aws_durable_execution_sdk_python-3.0.0}/.gitignore

@@ -34,6 +34,7 @@ dist/
 **/build/
 **/*.zip
 .aws-sam/
+.microvm-image-build/
 **/template.generated.json
 
 .env

aws_durable_execution_sdk_python-3.0.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.5
+Name: aws-durable-execution-sdk-python
+Version: 3.0.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: AWS durable-execution-dev <durable-execution-dev@amazon.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.43.114
+Description-Content-Type: text/markdown
+
+# AWS Durable Execution SDK for Python
+
+[![Build](https://github.com/aws/aws-durable-execution-sdk-python/actions/workflows/ci.yml/badge.svg)](https://github.com/aws/aws-durable-execution-sdk-python/actions/workflows/ci.yml)
+[![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)](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/LICENSE)
+
+-----
+
+Build reliable, long-running AWS Lambda workflows with checkpointed steps, waits, callbacks, and parallel execution.
+
+## ✨ Key Features
+
+- **Automatic checkpointing** - Resume execution after Lambda pauses or restarts
+- **Durable steps** - Run work with retry strategies and deterministic replay
+- **Waits and callbacks** - Pause for time or external signals without blocking Lambda
+- **Parallel and map operations** - Fan out work with configurable completion criteria
+- **Child contexts** - Structure complex workflows into isolated subflows
+- **Replay-safe logging** - Use `context.logger` for structured, de-duplicated logs
+- **Local and cloud testing** - Validate workflows with the testing SDK
+
+## 📦 Packages
+
+| Package | Description | Version |
+| --- | --- | --- |
+| `aws-durable-execution-sdk-python` | Execution SDK for Lambda durable functions | [![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python) |
+| `aws-durable-execution-sdk-python-testing` | Local/cloud test runner and pytest helpers | [![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python-testing.svg)](https://pypi.org/project/aws-durable-execution-sdk-python-testing) |
+
+## Dynamic instrumentation plugins
+
+Upgrading an existing application? Follow the [2.x to 3.0 migration guide](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/docs/migration-2.x-to-3.0.md)
+for dependency versions, before/after examples, provider packaging, and validation.
+
+Instrumentation plugins can be selected at Lambda cold start without importing
+them in the function artifact. Install a provider package in the function or a
+Lambda layer, then set an ordered allow-list:
+
+```text
+DURABLE_EXECUTION_PLUGINS=otel-invocation,example_audit
+```
+
+The SDK resolves those names from the `aws_durable_execution.plugins` Python
+entry-point group when the decorated handler is initialized. An unset or blank
+variable preserves the existing behavior. The decorator's `plugins` argument
+remains supported; explicit factories run first, and a factory passed to the
+decorator is not registered a second time through the environment.
+
+A plugin is registered as a *factory*, not as an instance. A factory is an object
+with a `create_plugin(info)` method taking the invocation's `InvocationStartInfo`
+and returning a `DurableInstrumentationPlugin`; the SDK calls that method once per
+invocation, so the instance it returns serves that one invocation only and can
+hold **per-invocation** state in ordinary attributes.
+
+Per-invocation is narrower than per-execution, and the difference matters. A
+durable execution spans as many invocations as it waits, retries or resumes, and
+the instance is dropped when each of those returns — so anything a plugin keeps in
+its attributes is gone by the next invocation of the same execution. State that
+has to survive that has two honest homes: rebuild it from the operation map the
+invocation hooks carry (`InvocationStartInfo.operations` is a full snapshot,
+which is how the bundled Telemetry exporter reports operations that completed in an
+earlier invocation), or put it on the factory, which outlives every invocation —
+keyed by execution ARN, and pruned by the owner, because the SDK will not tell the
+factory when an execution ends for good.
+
+A factory is an object with a method rather than a plain callable so the
+registration type can grow a second, optional member later -- a process-level
+flush on execution-environment shutdown, for example -- without a second breaking
+change to this surface.
+
+Write a small factory class and construct the plugin in its `create_plugin`. The
+factory holds what outlives an invocation, such as an exporter or a resolved
+configuration, and setup work that can fail belongs in the factory's own
+constructor rather than the plugin's:
+
+```python
+class AuditPluginFactory:
+    def __init__(self, sink):
+        self._sink = sink
+
+    def create_plugin(self, info):
+        return AuditPlugin(self._sink)
+
+
+plugins=[AuditPluginFactory(sink)]
+```
+
+A plugin class is not a factory, and neither is a bare callable. `plugins=[MyPlugin]`
+and `plugins=[lambda info: MyPlugin(sink)]` raise `PluginLoadError` during handler
+initialization, because neither carries `create_plugin`. A class that declares
+`create_plugin` as a `@classmethod` is accepted, since the requirement is the
+member and not the kind of object.
+
+Provider packages expose such a factory:
+
+```python
+from aws_durable_execution_sdk_python.plugin import (
+    DurableInstrumentationPlugin,
+    InvocationStartInfo,
+)
+
+
+class AuditPlugin(DurableInstrumentationPlugin):
+    pass
+
+
+class AuditPluginFactory:
+    def create_plugin(self, info: InvocationStartInfo) -> AuditPlugin:
+        return AuditPlugin()
+
+
+AUDIT_PLUGIN_FACTORY = AuditPluginFactory()
+```
+
+Register the factory instance in the package's `pyproject.toml`:
+
+```toml
+[project.entry-points."aws_durable_execution.plugins"]
+example_audit = "example_audit:AUDIT_PLUGIN_FACTORY"
+```
+
+Provider names must be unique across installed distributions. Missing,
+ambiguous, or wrongly shaped providers raise `PluginLoadError` during handler
+initialization with the provider and distribution details.
+
+### Selecting an OpenTelemetry view
+
+Enable at most one of `InvocationOtelPluginFactory` and
+`ExecutionOtelPluginFactory`. This
+constraint applies to the combined `plugins=[...]` argument and
+`DURABLE_EXECUTION_PLUGINS=otel-invocation` or `otel-execution` selection.
+Core 3 with OTel 2 rejects both at cold start with `PluginLoadError` naming the
+conflicting views; keep only one. Choose Invocation for work within each Lambda
+invocation or Execution for logical operations across the durable execution.
+Unrelated instrumentation plugin factories can run alongside either view.
+OTel 2 requires core 3.x and the per-invocation factory contract. Release the
+coordinated core version before releasing OTel 2.
+
+Plugin authors explicitly opt in by declaring
+`__durable_registration_api__ = 1` on a factory class. That class and its subclasses
+have their optional `exclusive_group` metadata validated and their
+optional `on_registration_result(registered)` callback invoked. A missing group
+or `None` adds no exclusivity constraint. The callback can release rejected
+constructor resources and must preserve resources from earlier accepted use.
+
+The first class declaring the marker in the method resolution order gates
+registration and selects the callback contract. An explicit marker other than
+the integer `1` shadows an ancestor's opt-in and disables this capability.
+Once enabled, every class in the MRO explicitly declaring the integer `1`
+contributes its resolved `exclusive_group`. These constraints accumulate:
+repeating the marker with a new group adds to inherited groups rather than
+replacing them, and `None` does not erase an inherited constraint. A group is
+counted once per factory registration even if several ancestors declare it.
+Unmarked classes' coincidental same-named legacy fields/helpers remain inert.
+Subclasses of the bundled OTel factories therefore retain the view group when they
+add their own group. Repeat the marker to add a group or customize the callback;
+the callback is still notified once per factory. Factories with no marker anywhere
+in their hierarchy retain their existing attributes/helpers. The generic plugin
+base defines neither attribute nor hook. The registration API remains independent
+of the removed provider API version 1 contract.
+
+### Invocation worker lifecycle
+
+The existing `on_invocation_start` and `on_invocation_end` hooks run on the
+handler's invocation worker, both in registration order. Start hooks finish
+before background checkpoint processing begins. The same worker runs the handler
+(including its `finally` blocks), prepares the existing serialized output or
+error, checkpoints large results when necessary, joins registered branches while
+checkpointing is available, stops and waits for checkpoint processing, then calls
+End before returning the outcome. The caller shuts down the handler executor.
+There is no separate handler-context hook or context-manager plugin API.
+
+When plugins are registered, the worker begins with a copy of the caller's
+context-variable bindings. Start hooks, the handler, serialization, resource
+cleanup and End hooks use that same Context. Changes made by a Start hook remain
+visible to later hooks and handler code even if that hook raises; the SDK contains
+the exception and retains the plugin without rolling back its bindings. A later
+Start hook may replace an earlier binding. Plugins are responsible for restoring
+partial bindings themselves when needed, either before raising or during End.
+End runs in the same Context as Start, so context-variable tokens retain their
+owner. End hooks retain forward registration order, not reverse stack order,
+so they must not rely on observing a stack-like unwind of other plugins' contexts.
+Each SDK-managed `map` or `parallel` branch admission, including an in-process
+resume, receives a fresh copy of the coordinator's bindings when plugins are
+registered. Branch changes remain local even when pool threads are reused.
+User-created threads retain normal Python context-variable behavior; without
+registered plugins, SDK branch submission keeps its existing behavior.
+The worker's invocation context is discarded on return, including after plugin
+cleanup failures, leaving the host's bindings unchanged. This isolates bindings,
+not mutations to shared objects or external side effects. Without plugins, the
+handler retains its existing fresh-worker context behavior.
+
+Core 3 creates a fresh plugin instance per invocation through each registered
+factory. OTel 2 requires core 3.x and uses the existing Start/End hooks on those
+instances. Upgrade both packages together; core 3 rejects OTel 1.x registrations
+and the removed provider API version 1 contract. The independent registration
+API remains unchanged.
+
+### Chained-invoke propagation
+
+A new invoke START collects synchronous plugin metadata after resolving its
+operation and target identity, before checkpointing. The SDK writes a non-blank
+`x_amzn_trace_id` contribution to the flat
+`ChainedInvokeOptions.XAmznTraceId` member. Function, tenant, payload, operation
+name and identity remain unchanged. The member is omitted without a contribution.
+Each invoke in a batch has its own metadata; this is not a request-wide header.
+
+The SDK-owned frozen `PropagationInput` carries `execution_arn`, `operation_id`,
+optional `parent_operation_id`, and `target_function_name`. Frozen
+`PropagationMetadata` has optional `x_amzn_trace_id`. Neither type depends on
+OpenTelemetry or generated service models. The optional synchronous plugin
+`provide_propagation_metadata(info)` hook defaults to no contribution.
+
+The collector keeps the first non-blank opaque value in configured order without
+trimming it. Equal values do not conflict; different later values log both plugin
+identities and a conflict count. Ordinary hook/getter/result/diagnostic failures
+are isolated; cancellation and other `BaseException` control signals keep their
+existing behavior. Replaying a checkpointed START, pending operation or terminal
+result does not call the hook. If a START was never committed, a later attempt
+can collect again; the callback is not exactly-once.
+
+This requires boto3 1.43.114 or newer, whose botocore dependency includes the
+published optional `ChainedInvokeOptions.XAmznTraceId` string field. The real
+botocore tests exercise its parameter validation and wire serialization without
+field removal, validation bypass or a model-capability fallback. Deployed backend
+delivery and downstream topology still require separate validation.
+Python has no `DistributedMapOptions` wrapper
+or distributed-map START API: its existing map/parallel operations use CONTEXT.
+The design's corresponding distributed-map field awaits that future modeled path.
+
+This release pairs core 3 with OTel 2 and its per-invocation factories. Custom
+plugins that omit the optional hook retain their existing tracing behavior.
+Backend rollout and deployed downstream trace-topology validation remain pending.
+
+## 🚀 Quick Start
+
+Install the execution SDK:
+
+```console
+pip install aws-durable-execution-sdk-python
+```
+
+Create a durable Lambda handler:
+
+```python
+from aws_durable_execution_sdk_python import (
+    DurableContext,
+    StepContext,
+    durable_execution,
+    durable_step,
+)
+from aws_durable_execution_sdk_python.config import Duration
+
+@durable_step
+def validate_order(step_ctx: StepContext, order_id: str) -> dict:
+    step_ctx.logger.info("Validating order", extra={"order_id": order_id})
+    return {"order_id": order_id, "valid": True}
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    order_id = event["order_id"]
+    context.logger.info("Starting workflow", extra={"order_id": order_id})
+
+    validation = context.step(validate_order(order_id), name="validate_order")
+    if not validation["valid"]:
+        return {"status": "rejected", "order_id": order_id}
+
+    # simulate approval (real world: use wait_for_callback)
+    context.wait(duration=Duration.from_seconds(5), name="await_confirmation")
+
+    return {"status": "approved", "order_id": order_id}
+```
+
+## 📚 Documentation
+
+The complete documentation for the AWS Durable Execution SDK for Python lives on the AWS Documentation site:
+
+- **[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
+
+- [Bug report](https://github.com/aws/aws-durable-execution-sdk-python/issues/new?template=bug_report.yml)
+- [Feature request](https://github.com/aws/aws-durable-execution-sdk-python/issues/new?template=feature_request.yml)
+- [Documentation feedback](https://github.com/aws/aws-durable-execution-sdk-python/issues/new?template=documentation.yml)
+- [Contributing guide](CONTRIBUTING.md)
+
+## 📄 License
+
+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-3.0.0/README.md

@@ -0,0 +1,290 @@
+# AWS Durable Execution SDK for Python
+
+[![Build](https://github.com/aws/aws-durable-execution-sdk-python/actions/workflows/ci.yml/badge.svg)](https://github.com/aws/aws-durable-execution-sdk-python/actions/workflows/ci.yml)
+[![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)](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/LICENSE)
+
+-----
+
+Build reliable, long-running AWS Lambda workflows with checkpointed steps, waits, callbacks, and parallel execution.
+
+## ✨ Key Features
+
+- **Automatic checkpointing** - Resume execution after Lambda pauses or restarts
+- **Durable steps** - Run work with retry strategies and deterministic replay
+- **Waits and callbacks** - Pause for time or external signals without blocking Lambda
+- **Parallel and map operations** - Fan out work with configurable completion criteria
+- **Child contexts** - Structure complex workflows into isolated subflows
+- **Replay-safe logging** - Use `context.logger` for structured, de-duplicated logs
+- **Local and cloud testing** - Validate workflows with the testing SDK
+
+## 📦 Packages
+
+| Package | Description | Version |
+| --- | --- | --- |
+| `aws-durable-execution-sdk-python` | Execution SDK for Lambda durable functions | [![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python.svg)](https://pypi.org/project/aws-durable-execution-sdk-python) |
+| `aws-durable-execution-sdk-python-testing` | Local/cloud test runner and pytest helpers | [![PyPI - Version](https://img.shields.io/pypi/v/aws-durable-execution-sdk-python-testing.svg)](https://pypi.org/project/aws-durable-execution-sdk-python-testing) |
+
+## Dynamic instrumentation plugins
+
+Upgrading an existing application? Follow the [2.x to 3.0 migration guide](https://github.com/aws/aws-durable-execution-sdk-python/blob/main/docs/migration-2.x-to-3.0.md)
+for dependency versions, before/after examples, provider packaging, and validation.
+
+Instrumentation plugins can be selected at Lambda cold start without importing
+them in the function artifact. Install a provider package in the function or a
+Lambda layer, then set an ordered allow-list:
+
+```text
+DURABLE_EXECUTION_PLUGINS=otel-invocation,example_audit
+```
+
+The SDK resolves those names from the `aws_durable_execution.plugins` Python
+entry-point group when the decorated handler is initialized. An unset or blank
+variable preserves the existing behavior. The decorator's `plugins` argument
+remains supported; explicit factories run first, and a factory passed to the
+decorator is not registered a second time through the environment.
+
+A plugin is registered as a *factory*, not as an instance. A factory is an object
+with a `create_plugin(info)` method taking the invocation's `InvocationStartInfo`
+and returning a `DurableInstrumentationPlugin`; the SDK calls that method once per
+invocation, so the instance it returns serves that one invocation only and can
+hold **per-invocation** state in ordinary attributes.
+
+Per-invocation is narrower than per-execution, and the difference matters. A
+durable execution spans as many invocations as it waits, retries or resumes, and
+the instance is dropped when each of those returns — so anything a plugin keeps in
+its attributes is gone by the next invocation of the same execution. State that
+has to survive that has two honest homes: rebuild it from the operation map the
+invocation hooks carry (`InvocationStartInfo.operations` is a full snapshot,
+which is how the bundled Telemetry exporter reports operations that completed in an
+earlier invocation), or put it on the factory, which outlives every invocation —
+keyed by execution ARN, and pruned by the owner, because the SDK will not tell the
+factory when an execution ends for good.
+
+A factory is an object with a method rather than a plain callable so the
+registration type can grow a second, optional member later -- a process-level
+flush on execution-environment shutdown, for example -- without a second breaking
+change to this surface.
+
+Write a small factory class and construct the plugin in its `create_plugin`. The
+factory holds what outlives an invocation, such as an exporter or a resolved
+configuration, and setup work that can fail belongs in the factory's own
+constructor rather than the plugin's:
+
+```python
+class AuditPluginFactory:
+    def __init__(self, sink):
+        self._sink = sink
+
+    def create_plugin(self, info):
+        return AuditPlugin(self._sink)
+
+
+plugins=[AuditPluginFactory(sink)]
+```
+
+A plugin class is not a factory, and neither is a bare callable. `plugins=[MyPlugin]`
+and `plugins=[lambda info: MyPlugin(sink)]` raise `PluginLoadError` during handler
+initialization, because neither carries `create_plugin`. A class that declares
+`create_plugin` as a `@classmethod` is accepted, since the requirement is the
+member and not the kind of object.
+
+Provider packages expose such a factory:
+
+```python
+from aws_durable_execution_sdk_python.plugin import (
+    DurableInstrumentationPlugin,
+    InvocationStartInfo,
+)
+
+
+class AuditPlugin(DurableInstrumentationPlugin):
+    pass
+
+
+class AuditPluginFactory:
+    def create_plugin(self, info: InvocationStartInfo) -> AuditPlugin:
+        return AuditPlugin()
+
+
+AUDIT_PLUGIN_FACTORY = AuditPluginFactory()
+```
+
+Register the factory instance in the package's `pyproject.toml`:
+
+```toml
+[project.entry-points."aws_durable_execution.plugins"]
+example_audit = "example_audit:AUDIT_PLUGIN_FACTORY"
+```
+
+Provider names must be unique across installed distributions. Missing,
+ambiguous, or wrongly shaped providers raise `PluginLoadError` during handler
+initialization with the provider and distribution details.
+
+### Selecting an OpenTelemetry view
+
+Enable at most one of `InvocationOtelPluginFactory` and
+`ExecutionOtelPluginFactory`. This
+constraint applies to the combined `plugins=[...]` argument and
+`DURABLE_EXECUTION_PLUGINS=otel-invocation` or `otel-execution` selection.
+Core 3 with OTel 2 rejects both at cold start with `PluginLoadError` naming the
+conflicting views; keep only one. Choose Invocation for work within each Lambda
+invocation or Execution for logical operations across the durable execution.
+Unrelated instrumentation plugin factories can run alongside either view.
+OTel 2 requires core 3.x and the per-invocation factory contract. Release the
+coordinated core version before releasing OTel 2.
+
+Plugin authors explicitly opt in by declaring
+`__durable_registration_api__ = 1` on a factory class. That class and its subclasses
+have their optional `exclusive_group` metadata validated and their
+optional `on_registration_result(registered)` callback invoked. A missing group
+or `None` adds no exclusivity constraint. The callback can release rejected
+constructor resources and must preserve resources from earlier accepted use.
+
+The first class declaring the marker in the method resolution order gates
+registration and selects the callback contract. An explicit marker other than
+the integer `1` shadows an ancestor's opt-in and disables this capability.
+Once enabled, every class in the MRO explicitly declaring the integer `1`
+contributes its resolved `exclusive_group`. These constraints accumulate:
+repeating the marker with a new group adds to inherited groups rather than
+replacing them, and `None` does not erase an inherited constraint. A group is
+counted once per factory registration even if several ancestors declare it.
+Unmarked classes' coincidental same-named legacy fields/helpers remain inert.
+Subclasses of the bundled OTel factories therefore retain the view group when they
+add their own group. Repeat the marker to add a group or customize the callback;
+the callback is still notified once per factory. Factories with no marker anywhere
+in their hierarchy retain their existing attributes/helpers. The generic plugin
+base defines neither attribute nor hook. The registration API remains independent
+of the removed provider API version 1 contract.
+
+### Invocation worker lifecycle
+
+The existing `on_invocation_start` and `on_invocation_end` hooks run on the
+handler's invocation worker, both in registration order. Start hooks finish
+before background checkpoint processing begins. The same worker runs the handler
+(including its `finally` blocks), prepares the existing serialized output or
+error, checkpoints large results when necessary, joins registered branches while
+checkpointing is available, stops and waits for checkpoint processing, then calls
+End before returning the outcome. The caller shuts down the handler executor.
+There is no separate handler-context hook or context-manager plugin API.
+
+When plugins are registered, the worker begins with a copy of the caller's
+context-variable bindings. Start hooks, the handler, serialization, resource
+cleanup and End hooks use that same Context. Changes made by a Start hook remain
+visible to later hooks and handler code even if that hook raises; the SDK contains
+the exception and retains the plugin without rolling back its bindings. A later
+Start hook may replace an earlier binding. Plugins are responsible for restoring
+partial bindings themselves when needed, either before raising or during End.
+End runs in the same Context as Start, so context-variable tokens retain their
+owner. End hooks retain forward registration order, not reverse stack order,
+so they must not rely on observing a stack-like unwind of other plugins' contexts.
+Each SDK-managed `map` or `parallel` branch admission, including an in-process
+resume, receives a fresh copy of the coordinator's bindings when plugins are
+registered. Branch changes remain local even when pool threads are reused.
+User-created threads retain normal Python context-variable behavior; without
+registered plugins, SDK branch submission keeps its existing behavior.
+The worker's invocation context is discarded on return, including after plugin
+cleanup failures, leaving the host's bindings unchanged. This isolates bindings,
+not mutations to shared objects or external side effects. Without plugins, the
+handler retains its existing fresh-worker context behavior.
+
+Core 3 creates a fresh plugin instance per invocation through each registered
+factory. OTel 2 requires core 3.x and uses the existing Start/End hooks on those
+instances. Upgrade both packages together; core 3 rejects OTel 1.x registrations
+and the removed provider API version 1 contract. The independent registration
+API remains unchanged.
+
+### Chained-invoke propagation
+
+A new invoke START collects synchronous plugin metadata after resolving its
+operation and target identity, before checkpointing. The SDK writes a non-blank
+`x_amzn_trace_id` contribution to the flat
+`ChainedInvokeOptions.XAmznTraceId` member. Function, tenant, payload, operation
+name and identity remain unchanged. The member is omitted without a contribution.
+Each invoke in a batch has its own metadata; this is not a request-wide header.
+
+The SDK-owned frozen `PropagationInput` carries `execution_arn`, `operation_id`,
+optional `parent_operation_id`, and `target_function_name`. Frozen
+`PropagationMetadata` has optional `x_amzn_trace_id`. Neither type depends on
+OpenTelemetry or generated service models. The optional synchronous plugin
+`provide_propagation_metadata(info)` hook defaults to no contribution.
+
+The collector keeps the first non-blank opaque value in configured order without
+trimming it. Equal values do not conflict; different later values log both plugin
+identities and a conflict count. Ordinary hook/getter/result/diagnostic failures
+are isolated; cancellation and other `BaseException` control signals keep their
+existing behavior. Replaying a checkpointed START, pending operation or terminal
+result does not call the hook. If a START was never committed, a later attempt
+can collect again; the callback is not exactly-once.
+
+This requires boto3 1.43.114 or newer, whose botocore dependency includes the
+published optional `ChainedInvokeOptions.XAmznTraceId` string field. The real
+botocore tests exercise its parameter validation and wire serialization without
+field removal, validation bypass or a model-capability fallback. Deployed backend
+delivery and downstream topology still require separate validation.
+Python has no `DistributedMapOptions` wrapper
+or distributed-map START API: its existing map/parallel operations use CONTEXT.
+The design's corresponding distributed-map field awaits that future modeled path.
+
+This release pairs core 3 with OTel 2 and its per-invocation factories. Custom
+plugins that omit the optional hook retain their existing tracing behavior.
+Backend rollout and deployed downstream trace-topology validation remain pending.
+
+## 🚀 Quick Start
+
+Install the execution SDK:
+
+```console
+pip install aws-durable-execution-sdk-python
+```
+
+Create a durable Lambda handler:
+
+```python
+from aws_durable_execution_sdk_python import (
+    DurableContext,
+    StepContext,
+    durable_execution,
+    durable_step,
+)
+from aws_durable_execution_sdk_python.config import Duration
+
+@durable_step
+def validate_order(step_ctx: StepContext, order_id: str) -> dict:
+    step_ctx.logger.info("Validating order", extra={"order_id": order_id})
+    return {"order_id": order_id, "valid": True}
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    order_id = event["order_id"]
+    context.logger.info("Starting workflow", extra={"order_id": order_id})
+
+    validation = context.step(validate_order(order_id), name="validate_order")
+    if not validation["valid"]:
+        return {"status": "rejected", "order_id": order_id}
+
+    # simulate approval (real world: use wait_for_callback)
+    context.wait(duration=Duration.from_seconds(5), name="await_confirmation")
+
+    return {"status": "approved", "order_id": order_id}
+```
+
+## 📚 Documentation
+
+The complete documentation for the AWS Durable Execution SDK for Python lives on the AWS Documentation site:
+
+- **[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
+
+- [Bug report](https://github.com/aws/aws-durable-execution-sdk-python/issues/new?template=bug_report.yml)
+- [Feature request](https://github.com/aws/aws-durable-execution-sdk-python/issues/new?template=feature_request.yml)
+- [Documentation feedback](https://github.com/aws/aws-durable-execution-sdk-python/issues/new?template=documentation.yml)
+- [Contributing guide](CONTRIBUTING.md)
+
+## 📄 License
+
+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-2.0.1 → aws_durable_execution_sdk_python-3.0.0}/pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
-dependencies = ["boto3>=1.42.1"]
+dependencies = ["boto3>=1.43.114"]
 
 [project.urls]
 Documentation = "https://github.com/aws/aws-durable-execution-sdk-python#readme"

{aws_durable_execution_sdk_python-2.0.1 → aws_durable_execution_sdk_python-3.0.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__ = "2.0.1"
+__version__ = "3.0.0"