### Build Examples

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Build all example projects, including their dependencies. Run from the repository root.

```bash
hatch run examples:build
```

--------------------------------

### List Available Examples

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Display a list of all available example projects in the repository. Run from the repository root.

```bash
hatch run examples:list
```

--------------------------------

### Install AWS Durable Execution Testing SDK

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-testing/README.md

Install the SDK using pip. This command installs the testing package for local durable function development.

```console
pip install aws-durable-execution-sdk-python-testing
```

--------------------------------

### Tagging Convention Examples

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/RELEASING.md

Examples of how to format tags for SDK-only, OTel-only, or combined releases.

```bash
sdk-v1.6.0
otel-v0.3.0
sdk-v1.6.0,otel-v0.3.0
```

--------------------------------

### Package-Level Command: Examples Deployment

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Build and deploy example applications. These commands are run from the repository root.

```bash
hatch run examples:build
hatch run examples:deploy "Hello World"
```

--------------------------------

### ExecutionAlreadyStartedException Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-testing/docs/error-responses.md

Example of an ExecutionAlreadyStartedException response, indicating an attempt to start an already running execution. This typically returns an HTTP 409 status code.

```json
{
  "message": "Execution is already started",
  "DurableExecutionArn": "arn:aws:states:us-east-1:123456789012:execution:MyExecution:abc123"
}
```

--------------------------------

### PyPI Release Testing: Examples

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Test the examples package against the published PyPI version of the core SDK. Run from the repository root.

```bash
hatch run test-pypi-examples:test
```

--------------------------------

### Install TypeScript Testing SDK

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Install the necessary testing SDK for TypeScript durable executions.

```bash
npm install --save-dev @aws/durable-execution-sdk-js-testing
```

--------------------------------

### Deploy Specific Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Deploy a specific example project, such as 'Hello World'. This command requires durable functions to be available. Run from the repository root.

```bash
hatch run examples:deploy "Hello World"
```

--------------------------------

### Run All Example Tests Locally

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-examples/test/README.md

Execute all example tests using the default local runner. This command is run from the repository root.

```bash
hatch run dev-examples:test
```

--------------------------------

### Generate SAM Template for Examples

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Generate the AWS Serverless Application Model (SAM) template for all example projects. Run from the repository root.

```bash
hatch run examples:generate-sam-template
```

--------------------------------

### Install OpenTelemetry Plugin

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Install the OpenTelemetry plugin for the AWS Durable Execution SDK for Python using pip.

```bash
pip install aws-durable-execution-sdk-python-otel
```

--------------------------------

### Conventional Commits - Docs Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Example of a conventional commit message for documentation changes.

```git
docs: update API documentation for context
```

--------------------------------

### Install AWS Durable Execution SDK

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python/README.md

Install the execution SDK for Python using pip. This is the first step to using the SDK in your project.

```console
pip install aws-durable-execution-sdk-python
```

--------------------------------

### Release Notes Format Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/RELEASING.md

A template for structuring release notes, with separate sections for each package and changelog categories.

```markdown
## aws-durable-execution-sdk-python v1.6.0

### Features
- Added support for X
- New `context.foo()` API

### Bug Fixes
- Fixed issue with Y under Z conditions

### Breaking Changes
- Removed deprecated `bar()` method

---

## aws-durable-execution-sdk-python-otel v0.3.0

### Features
- Added tracing for `map` operations

### Bug Fixes
- Fixed span context propagation in child contexts
```

--------------------------------

### OtelContextLogFilter / install_log_filter

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

The logging filter and its installer used to stamp trace context onto log records. Installed automatically when enrich_logger=True; exported for manual setups.

```APIDOC
## OtelContextLogFilter / install_log_filter

### Description

`OtelContextLogFilter` is a logging filter designed to enrich log records with current OpenTelemetry trace context (like trace ID and span ID). `install_log_filter` is a convenience function to automatically add this filter to the root logger or a specified logger.

### Usage

When `enrich_logger=True` is passed to `OtelPlugin`, this filter is automatically installed. It can also be installed manually for custom logging configurations.

**Manual Installation:**

```python
import logging
from aws_durable_execution_sdk_python_otel import install_log_filter

# Get a logger instance
logger = logging.getLogger(__name__)

# Install the log filter
install_log_filter(logger)

# Log messages will now be stamped with trace context if available
logger.info("This is a log message.")
```

**Automatic Installation (via OtelPlugin):**

```python
from aws_durable_execution_sdk_python_otel import OtelPlugin

# When OtelPlugin is initialized with enrich_logger=True, the filter is automatically applied.
plugin = OtelPlugin(enrich_logger=True)
```
```

--------------------------------

### ResourceNotFoundException Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-testing/docs/error-responses.md

Example of a ResourceNotFoundException response, indicating that a requested resource could not be found. This typically returns an HTTP 404 status code.

```json
{
  "Type": "ResourceNotFoundException",
  "Message": "Execution with ID 'exec-123' not found"
}
```

--------------------------------

### Conventional Commits - Feat Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Example of a conventional commit message for a new feature.

```git
feat: add retry mechanism for operations
```

--------------------------------

### Clean Build Artifacts

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Remove build artifacts generated by the examples. Run from the repository root.

```bash
hatch run examples:clean
```

--------------------------------

### Conventional Commits - Test Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Example of a conventional commit message for adding or updating tests.

```git
test: add integration tests for parallel exec
```

--------------------------------

### Conventional Commits - Scoped Fix Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Example of a conventional commit message for a fix within a specific scope (e.g., 'examples').

```git
fix(examples): correct timeout handling
```

--------------------------------

### Conventional Commits - Fix Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Example of a conventional commit message for a bug fix.

```git
fix: resolve memory leak in execution state
```

--------------------------------

### Conventional Commits - Scoped Feat Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Example of a conventional commit message for a feature within a specific scope (e.g., 'sdk').

```git
feat(sdk): implement new callback functionality
```

--------------------------------

### Run Example Tests with Explicit Local Mode

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-examples/test/README.md

Run example tests specifically in local mode using pytest with the `--runner-mode` flag. This command targets tests within the specified directory.

```bash
pytest --runner-mode=local -m example packages/aws-durable-execution-sdk-python-examples/test/
```

--------------------------------

### Full Conventional Commit Message Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

A comprehensive example of a conventional commit message, including a subject, body with bullet points, and a footer referencing a resolved issue.

```git
feat: add retry mechanism for operations

- Implement exponential backoff strategy for transient failures
- Add configurable retry limits and timeout settings
- Include comprehensive error logging for debugging
- Update documentation with retry configuration examples

Resolves issue with intermittent network failures causing
execution interruptions in production environments.
```

--------------------------------

### CallbackTimeoutException Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-testing/docs/error-responses.md

Example of a CallbackTimeoutException response, indicating that a callback operation timed out. This typically returns an HTTP 408 status code.

```json
{
  "Type": "CallbackTimeoutException",
  "message": "Callback operation timed out after 30 seconds"
}
```

--------------------------------

### Get Execution Details

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Retrieve detailed information about a specific durable function execution using its ARN. Run from the repository root.

```bash
hatch run examples:get execution-arn
```

--------------------------------

### ServiceException Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-testing/docs/error-responses.md

Example of a ServiceException response, indicating an internal service error occurred. This typically returns an HTTP 500 status code.

```json
{
  "Type": "ServiceException", 
  "Message": "An internal error occurred while processing the request"
}
```

--------------------------------

### Write a Durable Execution SDK Test

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-examples/test/README.md

Example of a Python test function using the `durable_runner` fixture and `@pytest.mark.durable_execution` marker. It demonstrates how to invoke an example handler and perform assertions on the result.

```python
import pytest
from aws_durable_execution_sdk_python.execution import InvocationStatus
from examples.src import my_example


@pytest.mark.example
@pytest.mark.durable_execution(
    handler=my_example.handler,
    lambda_function_name="my example",
)
def test_my_example(durable_runner):
    """Test my example in both local and cloud modes."""
    with durable_runner:
        result = durable_runner.run(input={"test": "data"}, timeout=10)
    
    # Assertions work in both modes
    assert result.status == InvocationStatus.SUCCEEDED
    assert result.result == "expected output"
    
    # Optional mode-specific validations
    if durable_runner.mode == "cloud":
        # Cloud-specific assertions
        pass
```

--------------------------------

### VS Code Settings for Ruff Linting

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Configure VS Code settings to enable format on save, automatic fixing of linting issues, and import organization using Ruff. Ensure the Ruff extension is installed.

```json
{
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    },
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "ruff.nativeServer": "on"
}
```

--------------------------------

### Test a Durable Function Locally

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-testing/README.md

Write test cases for your durable functions using the DurableFunctionTestRunner. This example demonstrates how to run the function, assert its final status and result, and inspect individual step outcomes.

```python
from aws_durable_execution_sdk_python.execution import InvocationStatus
from aws_durable_execution_sdk_python_testing.runner import (
    ContextOperation,
    DurableFunctionTestResult,
    DurableFunctionTestRunner,
    StepOperation,
)

def test_my_durable_functions():
    with DurableFunctionTestRunner(handler=function_under_test) as runner:
        result: DurableFunctionTestResult = runner.run(input="input str", timeout=10)

    assert result.status is InvocationStatus.SUCCEEDED
    assert result.result == '["1 2", "3 4 4 3", "5 6"]'

    one_result: StepOperation = result.get_step("one")
    assert one_result.result == '"1 2"'

    two_result: ContextOperation = result.get_context("two")
    assert two_result.result == '"3 4 4 3"'

    three_result: StepOperation = result.get_step("three")
    assert three_result.result == '"5 6"'

```

--------------------------------

### InvalidParameterValueException Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-testing/docs/error-responses.md

Example of an InvalidParameterValueException response, indicating an issue with provided parameter values. This typically returns an HTTP 400 status code.

```json
{
  "Type": "InvalidParameterValueException",
  "message": "The parameter 'executionName' cannot be empty"
}
```

--------------------------------

### Get Execution History

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Retrieve the execution history for a specific durable function using its ARN. Run from the repository root.

```bash
hatch run examples:history execution-arn
```

--------------------------------

### Valid Durable Function ARNs and Names

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Examples of valid identifiers for invoking durable functions, including full ARNs with versions or aliases, and function names with versions or aliases. Qualified identifiers are mandatory.

```bash
# Full ARN with version
arn:aws:lambda:us-east-1:123456789012:function:my-function:1
```

```bash
# Full ARN with alias
arn:aws:lambda:us-east-1:123456789012:function:my-function:prod
```

```bash
# Full ARN with $LATEST
arn:aws:lambda:us-east-1:123456789012:function:my-function:$LATEST
```

```bash
# Function name with version/alias
my-function:1
```

```bash
my-function:prod
```

--------------------------------

### Per-Package Development: Core SDK Tests

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Run tests specifically for the core SDK package. Use the `dev-*` environments from the repository root for focused development.

```bash
hatch run dev-core:test
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Execute all tests and generate a coverage report. Run from the repository root.

```bash
hatch run test:cov
```

--------------------------------

### Configure OtelPlugin with Custom Options

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Instantiate the OtelPlugin with custom configurations for trace provider, context extractor, instrumentation scope name, and logger enrichment.

```python
from aws_durable_execution_sdk_python_otel import (
    OtelPlugin,
    xray_context_extractor,
)

plugin = OtelPlugin(
    # Provide your own TracerProvider if you already have one configured.
    # Defaults to the globally configured tracer provider.
    trace_provider=None,
    # Use a custom context extractor (default: xray_context_extractor).
    context_extractor=xray_context_extractor,
    # Custom instrumentation scope name
    # (default: "aws-durable-execution-sdk-python").
    instrument_name="my-service",
    # Install a root-logger filter that stamps trace context onto every
    # log record (default: True).
    enrich_logger=True,
)
```

--------------------------------

### Per-Package Development: Core SDK Coverage

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Run tests with coverage for the core SDK package. This command is executed from the repository root.

```bash
hatch run dev-core:cov
```

--------------------------------

### Multi-Step Workflow in Python

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Implement a sequential multi-step workflow using `context.step` and `context.wait`.

```python
@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
    validated = context.step(validate_input(event), name="validate")
    processed = context.step(process_data(validated), name="process")
    context.wait(duration=Duration.from_seconds(30), name="cooldown")
    context.step(send_notification(processed), name="notify")
    return {"success": True, "data": processed}
```

--------------------------------

### Package-Level Command: Build Distribution

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Build the distribution artifacts for the core SDK package. This command must be run from within the package directory.

```bash
cd packages/aws-durable-execution-sdk-python

hatch build
```

--------------------------------

### Per-Package Development: OpenTelemetry Tests

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Run tests specifically for the OpenTelemetry instrumentation package. Use the `dev-*` environments from the repository root.

```bash
hatch run dev-otel:test
```

--------------------------------

### Bootstrap AWS Account for Durable Functions

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Set up the necessary IAM role and KMS key in your AWS account for durable functions. Replace 'your-account-id' with your actual AWS account ID. Run from the repository root.

```bash
# Set up IAM role and KMS key for durable functions
export AWS_ACCOUNT_ID=your-account-id
hatch run examples:bootstrap
```

--------------------------------

### Instantiate OtelPlugin

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Instantiates the OtelPlugin with optional trace provider, context extractor, instrument name, and logger enrichment settings.

```python
OtelPlugin(
    trace_provider=None,
    context_extractor=None,
    instrument_name="aws-durable-execution-sdk-python",
    enrich_logger=True,
)
```

--------------------------------

### Package-Level Command: Static Analysis with Auto-Fix

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Perform static analysis and automatically fix formatting issues within the core SDK package. This command must be run from within the package directory.

```bash
cd packages/aws-durable-execution-sdk-python

hatch fmt
```

--------------------------------

### OtelPlugin Constructor

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Initializes the OtelPlugin with optional trace provider, context extractor, instrument name, and logger enrichment settings.

```APIDOC
## OtelPlugin

### Description

The main plugin class for OpenTelemetry instrumentation. Implements `DurableInstrumentationPlugin` from `aws_durable_execution_sdk_python`.

### Parameters

- **trace_provider** (Optional[TraceProvider]) - The OpenTelemetry trace provider to use. Defaults to `None`.
- **context_extractor** (Optional[ContextExtractor]) - A function to extract context. Defaults to `None`.
- **instrument_name** (str) - The name of the instrument. Defaults to "aws-durable-execution-sdk-python".
- **enrich_logger** (bool) - Whether to enrich loggers with trace context. Defaults to `True`.

### Example

```python
from aws_durable_execution_sdk_python_otel import OtelPlugin

plugin = OtelPlugin(
    instrument_name="my-app-instrumentation",
    enrich_logger=True
)
```
```

--------------------------------

### PyPI Release Testing: OpenTelemetry

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Test the OpenTelemetry package against the published PyPI version of the core SDK. Run from the repository root.

```bash
hatch run test-pypi-otel:test
```

--------------------------------

### Run Tests by Pattern

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Execute a subset of tests that match a given pattern. The pattern matching is case-insensitive and can include filenames, class names, and function names. Run from the repository root.

```bash
hatch run test:all -k TEST_PATTERN
```

--------------------------------

### Per-Package Development: Core SDK Type Checking

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Perform type checking only for the core SDK package. Use the `dev-*` environments from the repository root.

```bash
hatch run dev-core:typecheck
```

--------------------------------

### Static Analysis (Ruff Format Check)

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Check code formatting using Ruff for each package individually. This loop iterates through packages and runs the check from within each package directory.

```bash
for pkg in packages/*/; do (cd "$pkg" && hatch fmt --check); done
```

--------------------------------

### Python Durable Function Test

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Example of testing a Python durable function using the durable_runner fixture. It runs a workflow and asserts its status and result.

```python
import pytest
from aws_durable_execution_sdk_python_testing import InvocationStatus
from my_module import handler

@pytest.mark.durable_execution(
    handler=handler,
    lambda_function_name="my_function",
)
def test_workflow(durable_runner):
    """Test durable function workflow."""
    with durable_runner:
        result = durable_runner.run(input={"user_id": "123"}, timeout=10)

    assert result.status is InvocationStatus.SUCCEEDED
    assert result.result == {"success": True}

    # Get step by name
    step_result = result.get_step("fetch-user")
    assert step_result.status is InvocationStatus.SUCCEEDED
```

--------------------------------

### TypeScript Durable Function Test

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Example of testing a TypeScript durable function using LocalDurableTestRunner. Sets up and tears down the test environment and runs a workflow.

```typescript
import {
  LocalDurableTestRunner,
  OperationType,
  OperationStatus,
} from "@aws/durable-execution-sdk-js-testing";

describe("My Durable Function", () => {
  beforeAll(() =>
    LocalDurableTestRunner.setupTestEnvironment({ skipTime: true }),
  );
  afterAll(() => LocalDurableTestRunner.teardownTestEnvironment());

  it("should execute workflow", async () => {
    const runner = new LocalDurableTestRunner({ handlerFunction: handler });
    const execution = await runner.run({ payload: { userId: "123" } });

    expect(execution.getStatus()).toBe("SUCCEEDED");
    expect(execution.getResult()).toEqual({ success: true });

    // Get operations BY NAME (not by index!)
    const fetchStep = runner.getOperation("fetch-user");
    expect(fetchStep.getType()).toBe(OperationType.STEP);
    expect(fetchStep.getStatus()).toBe(OperationStatus.SUCCEEDED);
  });
});
```

--------------------------------

### Per-Package Development: OpenTelemetry Coverage

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Run tests with coverage for the OpenTelemetry instrumentation package. This command is executed from the repository root.

```bash
hatch run dev-otel:cov
```

--------------------------------

### Run All Tests Across Packages

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Execute all tests for all packages in the monorepo. This command should be run from the repository root.

```bash
hatch run test:all
```

--------------------------------

### Define a Durable Function

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-testing/README.md

Example of a Python durable function using decorators like @durable_step and @durable_execution. This function defines several steps and orchestrates their execution.

```python
from aws_durable_execution_sdk_python.context import (
    DurableContext,
    durable_step,
    durable_with_child_context,
)
from aws_durable_execution_sdk_python.execution import durable_execution
from aws_durable_execution_sdk_python.config import Duration


@durable_step
def one(a: int, b: int) -> str:
    return f"{a} {b}"

@durable_step
def two_1(a: int, b: int) -> str:
    return f"{a} {b}"

@durable_step
def two_2(a: int, b: int) -> str:
    return f"{b} {a}"

@durable_with_child_context
def two(ctx: DurableContext, a: int, b: int) -> str:
    two_1_result: str = ctx.step(two_1(a, b))
    two_2_result: str = ctx.step(two_2(a, b))
    return f"{two_1_result} {two_2_result}"

@durable_step
def three(a: int, b: int) -> str:
    return f"{a} {b}"

@durable_execution
def function_under_test(event: Any, context: DurableContext) -> list[str]:
    results: list[str] = []

    result_one: str = context.step(one(1, 2))
    results.append(result_one)

    context.wait(Duration.from_seconds(1))

    result_two: str = context.run_in_child_context(two(3, 4))
    results.append(result_two)

    result_three: str = context.step(three(5, 6))
    results.append(result_three)

    return results

```

--------------------------------

### Explicit Type Declaration Example

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Always declare a type definition wherever a variable is declared, even within function scope and when implied. This improves clarity for type checkers and LLMs.

```python
def my_function() -> str:
  my_var: str = arb.call(1, 2, 3)
  return f"arb result: {my_var}"
```

--------------------------------

### Run Cloud Integration Tests with Hatch

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-examples/test/README.md

Execute integration tests in cloud mode using the `hatch` command-line tool, targeting a specific test case. This is an alternative to using pytest directly.

```bash
hatch run test:examples-integration -k test_hello_world
```

--------------------------------

### Invalid Durable Function ARNs and Names

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Examples of invalid identifiers for invoking durable functions, demonstrating that unqualified ARNs and function names are not permitted. Qualified identifiers (version or alias) are required.

```bash
# Unqualified ARN - NOT ALLOWED
arn:aws:lambda:us-east-1:123456789012:function:my-function
```

```bash
# Unqualified function name - NOT ALLOWED
my-function
```

--------------------------------

### Multi-Step Workflow in TypeScript

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Implement a sequential multi-step workflow using `context.step` and `context.wait`.

```typescript
export const handler = withDurableExecution(async (event, context) => {
  const validated = await context.step("validate", async () =>
    validateInput(event),
  );
  const processed = await context.step("process", async () =>
    processData(validated),
  );
  await context.wait("cooldown", { seconds: 30 });
  await context.step("notify", async () => sendNotification(processed));
  return { success: true, data: processed };
});
```

--------------------------------

### Run Single Test File

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Execute all tests within a specific Python test file. Provide the full path to the test file. Run from the repository root.

```bash
hatch run dev-core:test packages/aws-durable-execution-sdk-python/tests/path_to_test_module.py
```

--------------------------------

### Run Per-Package Coverage

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Execute coverage tests for a specific package. Replace 'dev-core' or 'dev-otel' with the target package name.

```bash
hatch run dev-core:cov
```

```bash
hatch run dev-otel:cov
```

--------------------------------

### Format Code with Auto-Fix

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Run the code formatter with auto-fixing enabled from within a package directory.

```bash
hatch fmt
```

--------------------------------

### Deploy Function for Cloud Testing

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-examples/test/README.md

Deploy a function to AWS Lambda before running cloud integration tests. This command is executed from the repository root.

```bash
hatch run examples:deploy "hello world" --function-name HelloWorld-Test
```

--------------------------------

### Enable X-Ray Active Tracing using AWS CLI

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Enable active tracing for your Lambda function using the AWS CLI to ensure the X-Ray trace header is populated.

```bash
aws lambda update-function-configuration \
  --function-name your-function-name \
  --tracing-config Mode=Active
```

--------------------------------

### Run Tests for Specific Package

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Execute tests for a single package within the repository. Replace 'dev-core' with the target package name. Run from the repository root.

```bash
hatch run dev-core:test
```

```bash
hatch run dev-otel:test
```

```bash
hatch run dev-examples:test
```

--------------------------------

### Conversion Methods for Data Structures

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Encapsulate conversion logic into `from_x` factory methods and `to_x` methods on a class. This promotes clear data transformation patterns.

```python
@dataclass(frozen=True)
class WaitOptions:
    wait_seconds: int = 0

    @classmethod
    def from_dict(cls, data: MutableMapping[str, Any]) -> WaitOptions:
        return cls(wait_seconds=data.get("WaitSeconds", 0))

    def to_dict(self) -> MutableMapping[str, Any]:
        return {"WaitSeconds": self.wait_seconds}
```

--------------------------------

### Configure OtelPlugin Context Extractors

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Configure the OtelPlugin to use different context extractors for tracing. The default is X-Ray trace header, but W3C Trace Context via clientContext is also supported.

```python
from aws_durable_execution_sdk_python_otel import (
    OtelPlugin,
    w3c_client_context_extractor,
    xray_context_extractor,
)

# Default: X-Ray trace header (recommended for most Lambda deployments)
OtelPlugin(context_extractor=xray_context_extractor)

# W3C Trace Context via clientContext (requires backend propagation support)
OtelPlugin(context_extractor=w3c_client_context_extractor)
```

--------------------------------

### Human-in-the-Loop Approval in Python

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Implement a workflow that requires human approval via email callback.

```python
@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
    plan = context.step(generate_plan(event), name="generate-plan")

    def submit_approval(callback_id: str):
        send_approval_email(event["approver_email"], plan, callback_id)

    answer = context.wait_for_callback(
        submitter=submit_approval,
        config=WaitForCallbackConfig(timeout=Duration.from_hours(24)),
        name="wait-for-approval"
    )

    if answer == "APPROVED":
        context.step(perform_action(plan), name="execute")
        return {"status": "completed"}
    return {"status": "rejected"}
```

--------------------------------

### Unit Test for Error Response Creation

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-testing/docs/error-responses.md

Unit test demonstrating how to create and assert an error response using the SDK's exception and HTTPResponse classes. Ensures correct status code and body structure.

```python
from aws_durable_execution_sdk_python_testing.exceptions import InvalidParameterValueException
from aws_durable_execution_sdk_python_testing.web.models import HTTPResponse

def test_error_response():
    exception = InvalidParameterValueException("Test error")
    response = HTTPResponse.create_error_from_exception(exception)
    
    assert response.status_code == 400
    assert response.body == {
        "Type": "InvalidParameterValueException",
        "message": "Test error"
    }
```

--------------------------------

### GenAI Agent Loop in Python

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Create a GenAI agent that loops, invoking an AI model and executing tools until a final response is generated.

```python
@durable_execution
def handler(event: dict, context: DurableContext) -> str:
    messages = [{"role": "user", "content": event["prompt"]}]

    while True:
        result = context.step(
            lambda _: invoke_ai_model(messages),
            name="invoke-model"
        )

        if result.get("tool") is None:
            return result["response"]

        tool = result["tool"]
        tool_result = context.step(
            lambda _: execute_tool(tool, result["response"]),
            name=f"tool-{tool['name']}"
        )
        messages.append({"role": "assistant", "content": tool_result})
```

--------------------------------

### Per-Package Development: OpenTelemetry Type Checking

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Perform type checking only for the OpenTelemetry instrumentation package. Use the `dev-*` environments from the repository root.

```bash
hatch run dev-otel:typecheck
```

--------------------------------

### Find Hatch Development Environment

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Use these commands to locate the path to the hatch virtual environment for specific packages. This is useful for configuring your IDE's Python interpreter.

```bash
# From the repo root — use the dev environment for the package you're working on
hatch env find dev-core
hatch env find dev-otel
hatch env find dev-examples
```

--------------------------------

### Enable X-Ray Active Tracing using CDK

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Enable active tracing for your Lambda function using AWS CDK.

```python
lambda_.Function(
    self,
    "MyFunction",
    tracing=lambda_.Tracing.ACTIVE,
)
```

--------------------------------

### Enable X-Ray Active Tracing using CloudFormation/SAM

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Configure active tracing for your Lambda function within a CloudFormation or SAM template.

```yaml
MyFunction:
  Type: AWS::Lambda::Function
  Properties:
    TracingConfig:
      Mode: Active
```

--------------------------------

### Deterministic Code Inside Steps (Python)

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Wrap non-deterministic operations such as UUID generation or time retrieval within context.step calls to ensure they are executed correctly during replays.

```python
id = context.step(lambda _: str(uuid.uuid4()), name="generate-id")
timestamp = context.step(lambda _: time.time(), name="get-time")
```

--------------------------------

### Create a Durable Lambda Handler

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python/README.md

Defines a durable Lambda handler using the SDK. It includes a durable step for order validation and a wait for confirmation before approving the order.

```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}
```

--------------------------------

### Executing Atomic Steps (TypeScript)

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Use `context.step` to execute atomic operations within a durable workflow. Named steps are recommended for better traceability and error handling. Retry configurations can be provided.

```typescript
// Basic step
const result = await context.step(async () => fetchData());

// Named step (recommended)
const result = await context.step("fetch-user", async () => fetchData());

// With retry configuration
const result = await context.step("api-call", async () => callAPI(), {
  retryStrategy: (error, attemptCount) => ({
    shouldRetry: attemptCount < 3,
    delay: { seconds: Math.pow(2, attemptCount) },
  }),
});
```

--------------------------------

### Configure Environment Variables for Cloud Testing

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-examples/test/README.md

Set necessary environment variables for cloud mode integration tests. These variables specify the AWS region, Lambda endpoint, and function details.

```bash
export AWS_REGION=us-west-2
export LAMBDA_ENDPOINT=https://lambda.us-west-2.amazonaws.com
export QUALIFIED_FUNCTION_NAME="HelloWorld-Test:\$LATEST"
export LAMBDA_FUNCTION_TEST_NAME="hello world"
```

--------------------------------

### Run Specific Test Method

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Execute a single test method within a Python test file. Specify the file path and the test method name. Run from the repository root.

```bash
hatch run dev-core:test packages/aws-durable-execution-sdk-python/tests/path_to_test_module.py::test_mytestmethod
```

--------------------------------

### Type Checking Across All Packages

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Perform type checking for all packages in the monorepo. This command is executed from the repository root.

```bash
hatch run types:check
```

--------------------------------

### Configure ADOT Lambda Layer using CDK

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Configure the ADOT Lambda Layer and the AWS_LAMBDA_EXEC_WRAPPER environment variable for your Lambda function using AWS CDK.

```python
from aws_cdk import aws_lambda as lambda_ 

adot_layer = lambda_.LayerVersion.from_layer_version_arn(
    self,
    "AdotLayer",
    f"arn:aws:lambda:<region>:<awsAccountId>:layer:aws-otel-python-amd64-ver-<version>",
)

fn = lambda_.Function(
    self,
    "MyFunction",
    runtime=lambda_.Runtime.PYTHON_3_12,
    handler="index.handler",
    code=lambda_.Code.from_asset("lambda"),
    layers=[adot_layer],
    environment={"AWS_LAMBDA_EXEC_WRAPPER": "/opt/otel-instrument"},
)
```

--------------------------------

### Symlink Hatch Environment for VS Code

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Create a symlink to the hatch development environment in the root of your repository. This helps VS Code correctly locate the Python interpreter, especially when paths contain spaces.

```bash
# From the repo root — symlink the dev environment you want to use
rm -rf .venv && ln -s "$(hatch env find dev-core)" .venv
```

--------------------------------

### Configure ADOT Lambda Layer using CloudFormation/SAM

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Define the ADOT Lambda Layer in your CloudFormation or SAM template for your Lambda function.

```yaml
MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    Layers:
      - !Sub arn:aws:lambda:${AWS::Region}:<awsAccountId>:layer:aws-otel-python-amd64-ver-<version>
    Environment:
      Variables:
        AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-instrument
```

--------------------------------

### Check Code Formatting

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Run the code formatter in check-only mode without auto-fixing.

```bash
hatch fmt --check
```

--------------------------------

### Wait for Condition - Polling Python

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Implement polling for job status using `context.wait_for_condition` in Python. Define a check function and configure `WaitForConditionConfig` with initial state, completion condition, and an exponential backoff wait strategy.

```python
from aws_durable_execution_sdk_python.waits import WaitForConditionConfig, ExponentialBackoff

def check_job(state: dict, check_ctx) -> dict:
    status = get_job_status(state["job_id"])
    return {"job_id": state["job_id"], "status": status}

result = context.wait_for_condition(
    check=check_job,
    config=WaitForConditionConfig(
        initial_state={"job_id": "job-123", "status": "pending"},
        condition=lambda state: state["status"] == "completed",
        wait_strategy=ExponentialBackoff(initial_wait=Duration.from_seconds(2))
    ),
    name="wait-for-job"
)

```

--------------------------------

### Preserving State with Step Return Values (Python)

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Variables mutated outside of steps are not retained across replays. Ensure state is preserved by returning values from steps and reassigning them.

```python
counter = context.step(lambda _: counter + 1, name="increment")
```

--------------------------------

### Non-Deterministic Code Outside Steps (Python)

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Do not use non-deterministic code like direct calls to uuid.uuid4() or time.time() outside of steps, as these will yield different results on each replay.

```python
# ❌ WRONG: Non-deterministic code outside steps
id = str(uuid.uuid4())           # Different on each replay!
timestamp = time.time()          # Different on each replay!
```

--------------------------------

### Run Cloud Integration Tests with Pytest

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-examples/test/README.md

Execute integration tests in cloud mode using pytest, targeting a specific test case. Ensure environment variables are set beforehand.

```bash
pytest --runner-mode=cloud -k test_hello_world packages/aws-durable-execution-sdk-python-examples/test/
```

--------------------------------

### Human-in-the-Loop Approval in TypeScript

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Implement a workflow that requires human approval via email callback.

```typescript
export const handler = withDurableExecution(async (event, context) => {
  const plan = await context.step("generate-plan", async () =>
    generatePlan(event),
  );

  const answer = await context.waitForCallback(
    "wait-for-approval",
    async (callbackId) =>
      sendApprovalEmail(event.approverEmail, plan, callbackId),
    { timeout: { hours: 24 } },
  );

  if (answer === "APPROVED") {
    await context.step("execute", async () => performAction(plan));
    return { status: "completed" };
  }
  return { status: "rejected" };
});
```

--------------------------------

### Factory Method for Initialization

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Use a @classmethod factory method to encapsulate advanced initialization logic, especially when the logic might fail. This keeps the constructor light.

```python
@dataclass(frozen=True)
class MyClass:
    id: str
    name: str
    timeout: int
    
    @classmethod
    def create(cls, name: str, timeout: int = 30) -> Config:
        """Factory contains """
        if timeout <= 0:
            raise ValueError("timeout must be positive")
        
        # Generate unique ID
        config_id: str = f"cfg_{uuid.uuid4().hex[:8]}"
        
        return cls(id=config_id, name=name, timeout=timeout)
```

--------------------------------

### Replay-Aware Logging (Python)

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Utilize context.logger for logging in durable functions, as it is designed to be replay-aware and handles log deduplication across multiple executions.

```python
context.logger.info("Starting")  # Deduplicated automatically
```

--------------------------------

### Configure ADOT Lambda Layer using AWS CLI

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Update your Lambda function configuration to include the ADOT Lambda Layer using the AWS CLI. Replace placeholders with your specific region, account ID, and layer version.

```bash
aws lambda update-function-configuration \
  --function-name your-function-name \
  --layers "arn:aws:lambda:<region>:<awsAccountId>:layer:aws-otel-python-amd64-ver-<version>"
```

--------------------------------

### Increase Test Timeout

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-examples/test/README.md

Demonstrates how to increase the timeout for a test execution. This is useful for troubleshooting `TimeoutError` exceptions.

```python
result = runner.run(input="test", timeout=120)  # Increase to 120s
```

--------------------------------

### Executing Atomic Steps (Python)

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Use `context.step` with the `@durable_step` decorator or a lambda to execute atomic operations in Python. Retry strategies can be configured using `StepConfig`.

```python
from aws_durable_execution_sdk_python import durable_step, StepContext
from aws_durable_execution_sdk_python.config import StepConfig
from aws_durable_execution_sdk_python.retries import RetryStrategyConfig, create_retry_strategy

# Define step function with decorator
@durable_step
def fetch_user(step_ctx: StepContext, user_id: str) -> dict:
    return {"id": user_id, "name": "Jane"}

# Execute step (uses function name automatically)
result = context.step(fetch_user(user_id))

# Named step with lambda
result = context.step(lambda _: fetch_data(), name="fetch-user")

# With retry configuration
retry_config = RetryStrategyConfig(
    max_attempts=3,
    initial_delay_seconds=1,
    backoff_rate=2.0,
)
result = context.step(
    fetch_user(user_id),
    config=StepConfig(retry_strategy=create_retry_strategy(retry_config))
)
```

--------------------------------

### AWS CDK (TypeScript) for Durable Functions

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Sets up a durable Lambda function, its version, and alias using AWS CDK in TypeScript. CDK automatically handles checkpoint permissions when `durableConfig` is specified.

```typescript
import * as cdk from "aws-cdk-lib";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as iam from "aws-cdk-lib/aws-iam";

const durableFunction = new lambda.Function(this, "DurableFunction", {
  runtime: lambda.Runtime.NODEJS_22_X, // or PYTHON_3_12
  handler: "index.handler",
  code: lambda.Code.fromAsset("lambda"),
  durableConfig: {
    executionTimeout: cdk.Duration.hours(1),
    retentionPeriod: cdk.Duration.days(7),
  },
});

// CDK automatically adds checkpoint permissions when durableConfig is set

// Create version and alias
const version = durableFunction.currentVersion;
const alias = new lambda.Alias(this, "ProdAlias", {
  aliasName: "prod",
  version: version,
});

```

--------------------------------

### Create a Durable Lambda Handler

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/README.md

Create the main durable Lambda handler function. Use the `@durable_execution` decorator to define the workflow's entry point. This handler orchestrates steps, waits, and returns the final workflow status.

```python
from aws_durable_execution_sdk_python import (
    DurableContext,
    StepContext,
    durable_execution,
    durable_step,
)
from aws_durable_execution_sdk_python.config import Duration

@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}
```

--------------------------------

### CI Checks Script

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/CONTRIBUTING.md

Execute a script that runs all CI checks, including tests, type checking, and linting, from the repository root. This script also validates commit messages.

```bash
.github/scripts/ci-checks.sh
```

--------------------------------

### GenAI Agent Loop in TypeScript

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Create a GenAI agent that loops, invoking an AI model and executing tools until a final response is generated.

```typescript
export const handler = withDurableExecution(async (event, context) => {
  const messages = [{ role: "user", content: event.prompt }];

  while (true) {
    const { response, tool } = await context.step("invoke-model", async () =>
      invokeAIModel(messages),
    );

    if (tool == null) return response;

    const toolResult = await context.step(`tool-${tool.name}`, async () =>
      executeTool(tool, response),
    );
    messages.push({ role: "assistant", content: toolResult });
  }
});
```

--------------------------------

### w3c_client_context_extractor

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

An alternative context extractor that reads W3C `traceparent` from `context.clientContext.custom.traceparent`. Requires backend `clientContext` propagation to be enabled.

```APIDOC
## w3c_client_context_extractor

### Description

An alternative context extractor that supports the W3C Trace Context standard. It specifically looks for the `traceparent` header within the `context.clientContext.custom.traceparent` structure. This extractor requires that your backend infrastructure is configured to propagate `clientContext` information.

### Usage

Use this extractor with `OtelPlugin` when your tracing context is propagated using W3C `traceparent` headers via client context.

```python
from aws_durable_execution_sdk_python_otel import OtelPlugin, w3c_client_context_extractor

plugin = OtelPlugin(context_extractor=w3c_client_context_extractor)
```
```

--------------------------------

### Deterministic Code Inside Steps (TypeScript)

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Use context.step to execute non-deterministic code like UUID generation or timestamp retrieval within steps to ensure correctness across replays.

```typescript
const id = await context.step("generate-id", async () => uuid.v4());
const timestamp = await context.step("get-time", async () => Date.now());
```

--------------------------------

### Wait for Callback - External Integration

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Wait for an external system to send a callback to your workflow. This is essential for integrating with external services or human approval processes, with configurable timeouts.

```APIDOC
## Wait for Callback - External Integration

**TypeScript:**

```typescript
const result = await context.waitForCallback(
  "wait-for-approval",
  async (callbackId, ctx) => {
    await sendApprovalEmail(callbackId);
  },
  { timeout: { hours: 24 } },
);
```

**Python:**

```python
from aws_durable_execution_sdk_python.waits import WaitForCallbackConfig

def submit_approval(callback_id: str):
    send_approval_email(callback_id)

result = context.wait_for_callback(
    submitter=submit_approval,
    config=WaitForCallbackConfig(timeout=Duration.from_hours(24)),
    name="wait-for-approval"
)
```
```

--------------------------------

### Configure AWS_LAMBDA_EXEC_WRAPPER Environment Variable using AWS CLI

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/packages/aws-durable-execution-sdk-python-otel/README.md

Set the AWS_LAMBDA_EXEC_WRAPPER environment variable for your Lambda function using the AWS CLI to enable the ADOT layer's instrumentation.

```bash
aws lambda update-function-configuration \
  --function-name your-function-name \
  --environment "Variables={AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument}"
```

--------------------------------

### Nested Durable Operations (Python)

Source: https://github.com/aws/aws-durable-execution-sdk-python/blob/main/AGENTS.md

Do not call durable operations like context.wait or context.step directly inside another step function, as this is disallowed and will result in errors.

```python
# ❌ WRONG: Nested durable operations
@durable_step
def process(step_ctx: StepContext):
    context.wait(duration=Duration.from_seconds(1))  # ERROR!
```