Add durable execution Step + Wait end-to-end

Implements the minimum viable slice of the Amazon.Lambda.DurableExecution
SDK: a workflow can run StepAsync and WaitAsync against a real Lambda,
with replay-aware checkpointing wired through to the AWS service.

Public API surface introduced:
- DurableFunction.WrapAsync — entry point that handles the durable
  execution envelope (input hydration, output construction, status mapping)
- IDurableContext.StepAsync / WaitAsync (4 Step overloads, 1 Wait)
- StepConfig with serializer hook (retry deferred to follow-up PR)
- ICheckpointSerializer interface
- [DurableExecution] attribute (recognized by future source generator)
- DurableExecutionException base + StepException

Internals:
- DurableExecutionHandler — Task.WhenAny race between user code and
  the suspension signal, returning Succeeded/Failed/Pending
- ExecutionState — replay-aware operation lookup and pending checkpoint
  buffer
- OperationIdGenerator — deterministic, replay-stable IDs
- TerminationManager — TaskCompletionSource-based suspension trigger
- LambdaDurableServiceClient — wraps AWSSDK.Lambda's checkpoint and
  state APIs

Tests:
- 86 unit tests covering enums, exceptions, models, configs,
  ID generation, termination, execution state, the handler race,
  the context (Step + Wait paths), and the WrapAsync entry point
- 8 end-to-end integration tests deploying real Lambdas via Docker on
  the provided.al2023 runtime: StepWaitStep, MultipleSteps, WaitOnly,
  LongerWait, ReplayDeterminism, RetrySucceeds, RetryExhausts, StepFails

Out of scope (follow-up PRs):
- IRetryStrategy, ExponentialRetryStrategy, retry decision factories
- DefaultJsonCheckpointSerializer
- DurableLogger replay-suppression (currently returns NullLogger)
- Callbacks, InvokeAsync, ParallelAsync, MapAsync, RunInChildContextAsync,
  WaitForConditionAsync — interface intentionally does not declare them
- Annotations source-generator integration
- DurableTestRunner / Amazon.Lambda.DurableExecution.Testing package
- dotnet new lambda.DurableFunction blueprint

stack-info: PR: #2360, branch: GarrettBeatty/stack/2

remove

Author: GarrettBeatty

Docs/durable-execution-design.md

@@ -250,6 +250,43 @@ private async Task MyWorkflow(OrderEvent input, IDurableContext context)
 }
 ```
 
+For **NativeAOT** deployments, pass a `JsonSerializerContext` so the SDK can serialize/deserialize your input and output types without reflection:
+
+```csharp
+[JsonSerializable(typeof(OrderEvent))]
+[JsonSerializable(typeof(OrderResult))]
+internal partial class MyJsonContext : JsonSerializerContext { }
+
+public class Function
+{
+    public Task<DurableExecutionInvocationOutput> FunctionHandler(
+        DurableExecutionInvocationInput invocationInput, ILambdaContext context)
+        => DurableFunction.WrapAsync<OrderEvent, OrderResult>(
+            MyWorkflow, invocationInput, context, MyJsonContext.Default);
+
+    private async Task<OrderResult> MyWorkflow(OrderEvent input, IDurableContext context)
+    {
+        // ...
+    }
+}
+```
+
+To inject a custom `IAmazonLambda` client (e.g., for VPC endpoints or unit testing), use the overload that accepts one:
+
+```csharp
+public class Function
+{
+    private readonly IAmazonLambda _lambdaClient;
+
+    public Function(IAmazonLambda lambdaClient) => _lambdaClient = lambdaClient;
+
+    public Task<DurableExecutionInvocationOutput> FunctionHandler(
+        DurableExecutionInvocationInput invocationInput, ILambdaContext context)
+        => DurableFunction.WrapAsync<OrderEvent, OrderResult>(
+            MyWorkflow, invocationInput, context, _lambdaClient);
+}
+```
+
 You'd also need to manually configure the CloudFormation template with `DurableConfig` and managed policies:
 
 ```json
@@ -877,14 +914,15 @@ When `RunAsync` starts, it kicks off two tasks in parallel: user code and a term
 
 The `TerminationManager` is a thin wrapper around `TaskCompletionSource<TerminationResult>`:
 - `TerminationTask` -- a Task that hangs forever until `Terminate()` is called
-- `Terminate(reason)` -- resolves the TCS, causing the race to pick termination
+- `Terminate(reason)` -- resolves the TCS and cancels `CancellationToken`, causing the race to pick termination
+- `CancellationToken` -- cancelled when `Terminate()` fires; exposed via `IDurableContext.CancellationToken` so user code can cooperatively stop after suspension
 
 When user code hits a pending wait or callback:
 1. It checkpoints the operation state
 2. Calls `terminationManager.Terminate(WaitScheduled)`
 3. Awaits a new never-completing `TaskCompletionSource` (blocks itself permanently)
 4. `Task.WhenAny` sees the termination task resolved and picks it as the winner
-5. `RunAsync` returns PENDING; Lambda terminates; the abandoned user task is GC'd
+5. `RunAsync` returns PENDING; the `CancellationToken` signals abandoned user code to stop; Lambda terminates
 
 ### Lifecycle and cleanup
 
@@ -906,21 +944,95 @@ Static helper for the non-Annotations handler path. Wraps a workflow function, h
 /// </summary>
 public static class DurableFunction
 {
+    // ── Reflection-based overloads (JIT only) ──────────────────────────
+
     /// <summary>
     /// Wrap a workflow that takes typed input and returns typed output.
+    /// Reflection-based JSON — not AOT-safe.
     /// </summary>
+    [RequiresUnreferencedCode("Uses reflection-based JSON. Use the JsonSerializerContext overload for AOT.")]
+    [RequiresDynamicCode("Uses reflection-based JSON. Use the JsonSerializerContext overload for AOT.")]
     public static Task<DurableExecutionInvocationOutput> WrapAsync<TInput, TOutput>(
         Func<TInput, IDurableContext, Task<TOutput>> workflow,
         DurableExecutionInvocationInput invocationInput,
         ILambdaContext lambdaContext);
 
     /// <summary>
-    /// Wrap a workflow that takes typed input and returns no value.
+    /// Wrap a workflow (typed input + output) with explicit Lambda client.
+    /// Reflection-based JSON — not AOT-safe.
+    /// </summary>
+    [RequiresUnreferencedCode("Uses reflection-based JSON. Use the JsonSerializerContext overload for AOT.")]
+    [RequiresDynamicCode("Uses reflection-based JSON. Use the JsonSerializerContext overload for AOT.")]
+    public static Task<DurableExecutionInvocationOutput> WrapAsync<TInput, TOutput>(
+        Func<TInput, IDurableContext, Task<TOutput>> workflow,
+        DurableExecutionInvocationInput invocationInput,
+        ILambdaContext lambdaContext,
+        IAmazonLambda lambdaClient);
+
+    /// <summary>
+    /// Wrap a void workflow (typed input, no output).
+    /// Reflection-based JSON — not AOT-safe.
     /// </summary>
+    [RequiresUnreferencedCode("Uses reflection-based JSON. Use the JsonSerializerContext overload for AOT.")]
+    [RequiresDynamicCode("Uses reflection-based JSON. Use the JsonSerializerContext overload for AOT.")]
     public static Task<DurableExecutionInvocationOutput> WrapAsync<TInput>(
         Func<TInput, IDurableContext, Task> workflow,
         DurableExecutionInvocationInput invocationInput,
         ILambdaContext lambdaContext);
+
+    /// <summary>
+    /// Wrap a void workflow with explicit Lambda client.
+    /// Reflection-based JSON — not AOT-safe.
+    /// </summary>
+    [RequiresUnreferencedCode("Uses reflection-based JSON. Use the JsonSerializerContext overload for AOT.")]
+    [RequiresDynamicCode("Uses reflection-based JSON. Use the JsonSerializerContext overload for AOT.")]
+    public static Task<DurableExecutionInvocationOutput> WrapAsync<TInput>(
+        Func<TInput, IDurableContext, Task> workflow,
+        DurableExecutionInvocationInput invocationInput,
+        ILambdaContext lambdaContext,
+        IAmazonLambda lambdaClient);
+
+    // ── AOT-safe overloads (caller supplies JsonSerializerContext) ──────
+
+    /// <summary>
+    /// Wrap a workflow (typed input + output). AOT-safe — requires
+    /// [JsonSerializable(typeof(TInput))] and [JsonSerializable(typeof(TOutput))]
+    /// on the supplied jsonContext.
+    /// </summary>
+    public static Task<DurableExecutionInvocationOutput> WrapAsync<TInput, TOutput>(
+        Func<TInput, IDurableContext, Task<TOutput>> workflow,
+        DurableExecutionInvocationInput invocationInput,
+        ILambdaContext lambdaContext,
+        JsonSerializerContext jsonContext);
+
+    /// <summary>
+    /// Wrap a workflow (typed input + output) with explicit Lambda client. AOT-safe.
+    /// </summary>
+    public static Task<DurableExecutionInvocationOutput> WrapAsync<TInput, TOutput>(
+        Func<TInput, IDurableContext, Task<TOutput>> workflow,
+        DurableExecutionInvocationInput invocationInput,
+        ILambdaContext lambdaContext,
+        IAmazonLambda lambdaClient,
+        JsonSerializerContext jsonContext);
+
+    /// <summary>
+    /// Wrap a void workflow (typed input, no output). AOT-safe.
+    /// </summary>
+    public static Task<DurableExecutionInvocationOutput> WrapAsync<TInput>(
+        Func<TInput, IDurableContext, Task> workflow,
+        DurableExecutionInvocationInput invocationInput,
+        ILambdaContext lambdaContext,
+        JsonSerializerContext jsonContext);
+
+    /// <summary>
+    /// Wrap a void workflow with explicit Lambda client. AOT-safe.
+    /// </summary>
+    public static Task<DurableExecutionInvocationOutput> WrapAsync<TInput>(
+        Func<TInput, IDurableContext, Task> workflow,
+        DurableExecutionInvocationInput invocationInput,
+        ILambdaContext lambdaContext,
+        IAmazonLambda lambdaClient,
+        JsonSerializerContext jsonContext);
 }
 ```
 
@@ -968,6 +1080,24 @@ public interface IDurableContext
         StepConfig? config = null,
         CancellationToken cancellationToken = default);
 
+    /// <summary>
+    /// Execute a step (simplified overload without IStepContext).
+    /// </summary>
+    Task<T> StepAsync<T>(
+        Func<Task<T>> func,
+        string? name = null,
+        StepConfig? config = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Execute a step that returns no value (simplified overload).
+    /// </summary>
+    Task StepAsync(
+        Func<Task> func,
+        string? name = null,
+        StepConfig? config = null,
+        CancellationToken cancellationToken = default);
+
     /// <summary>
     /// Suspend execution for the specified duration.
     /// Throws ArgumentOutOfRangeException if duration is less than 1 second.
@@ -1087,7 +1217,11 @@ public record DurableBranch<T>(string Name, Func<IDurableContext, Task<T>> Func)
 
 #### CancellationToken behavior
 
-All methods accept a `CancellationToken` that follows standard .NET semantics: cancellation throws `OperationCanceledException` and the execution fails. Cancellation does **not** trigger suspension — those are separate concepts. The durable execution service handles timeout scenarios automatically: if Lambda terminates mid-execution, the next invocation simply replays from the last checkpoint. For advanced users who want to suspend gracefully before timeout, check `context.LambdaContext.RemainingTime` and return early.
+All methods accept a `CancellationToken` that follows standard .NET semantics: cancellation throws `OperationCanceledException` and the execution fails. Cancellation does **not** trigger suspension — those are separate concepts.
+
+`IDurableContext.CancellationToken` is a context-level token that is automatically cancelled when the execution suspends (wait, retry, or callback). This allows in-flight user code to cooperatively stop after suspension rather than continuing to consume resources on the Lambda container until freeze. User code that performs long-running work (HTTP calls, file I/O) should pass this token to those operations.
+
+The durable execution service handles timeout scenarios automatically: if Lambda terminates mid-execution, the next invocation simply replays from the last checkpoint. For advanced users who want to suspend gracefully before timeout, check `context.LambdaContext.RemainingTime` and return early.
 
 ### Configuration Types
 
@@ -1579,13 +1713,29 @@ Both approaches produce a self-contained executable that the Lambda custom runti
 
 ### NativeAOT compatibility
 
-The SDK is AOT-friendly but does not require AOT. The default JSON serialization uses reflection (standard `System.Text.Json` behavior), which works in JIT mode. For NativeAOT deployments, provide a `JsonSerializerContext` via the `ICheckpointSerializer<T>` interface — this avoids all runtime reflection and is fully trim-safe. The SDK itself avoids `Activator.CreateInstance`, `Type.GetType()`, and other reflection patterns, and uses `[DynamicallyAccessedMembers]` trimming annotations where needed.
+The SDK is AOT-friendly but does not require AOT. The default JSON serialization uses reflection (standard `System.Text.Json` behavior), which works in JIT mode. For NativeAOT deployments, AOT safety is addressed at two levels:
+
+1. **Entry point (`DurableFunction.WrapAsync`)** — pass a `JsonSerializerContext` that includes type info for your `TInput` and `TOutput` types. The reflection-based overloads are annotated with `[RequiresUnreferencedCode]` / `[RequiresDynamicCode]` so the trimmer will warn if you use them in AOT builds.
+
+2. **Step checkpoints (`StepConfig.Serializer`)** — for custom or complex types checkpointed by `StepAsync`, provide an `ICheckpointSerializer` via `StepConfig` (e.g., `JsonCheckpointSerializer<T>` backed by a source-generated `JsonTypeInfo<T>`).
+
+The SDK itself avoids `Activator.CreateInstance`, `Type.GetType()`, and other reflection patterns, and uses `[DynamicallyAccessedMembers]` trimming annotations where needed.
 
 ```csharp
 // Default: works with reflection (JIT mode)
 var result = await context.StepAsync<Order>(async () => await GetOrder());
 
-// AOT mode: user provides serialization context
+// AOT mode — entry point: pass JsonSerializerContext to WrapAsync
+[JsonSerializable(typeof(OrderEvent))]
+[JsonSerializable(typeof(OrderResult))]
+internal partial class MyJsonContext : JsonSerializerContext { }
+
+public Task<DurableExecutionInvocationOutput> FunctionHandler(
+    DurableExecutionInvocationInput invocationInput, ILambdaContext context)
+    => DurableFunction.WrapAsync<OrderEvent, OrderResult>(
+        MyWorkflow, invocationInput, context, MyJsonContext.Default);
+
+// AOT mode — step checkpoint: provide a serializer via StepConfig
 var result = await context.StepAsync(
     async () => await GetOrder(),
     config: new StepConfig { Serializer = new JsonCheckpointSerializer<Order>(MyJsonContext.Default.Order) });
@@ -1701,7 +1851,7 @@ public class Functions
 }
 ```
 
-When no `LambdaClientFactory` is specified, the generated code creates a default `AmazonLambdaClient`. For the manual handler path, pass the client directly to `DurableExecutionHandler.RunAsync`.
+When no `LambdaClientFactory` is specified, the generated code creates a default `AmazonLambdaClient`. For the manual handler path (`DurableFunction.WrapAsync`), pass the client directly via the `IAmazonLambda lambdaClient` overload.
 
 > **Dependency boundaries:** `Amazon.Lambda.Annotations` has **no dependency** on the AWS SDK or on `Amazon.Lambda.DurableExecution`. The Annotations source generator references durable execution types by fully-qualified name strings only — it never takes a compile-time dependency on the durable package. The `[DurableExecution]` attribute is defined in `Amazon.Lambda.DurableExecution`, and the generated code resolves against the user's project references. There is only one source generator (Annotations) — no coordination between multiple generators is needed.
 

Libraries/src/Amazon.Lambda.DurableExecution/Amazon.Lambda.DurableExecution.csproj

@@ -14,6 +14,8 @@
     <EnableTrimAnalyzer>true</EnableTrimAnalyzer>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <WarningsAsErrors>IL2026,IL2067,IL2075,IL3050</WarningsAsErrors>
   </PropertyGroup>
 
   <ItemGroup>

Libraries/src/Amazon.Lambda.DurableExecution/AssemblyMarker.cs

@@ -0,0 +1,19 @@
+namespace Amazon.Lambda.DurableExecution;
+
+/// <summary>
+/// Configuration for step execution.
+/// </summary>
+public class StepConfig
+{
+    /// <summary>
+    /// Custom serializer for the step result. Default is System.Text.Json.
+    /// </summary>
+    public ICheckpointSerializer? Serializer { get; set; }
+
+    // TODO: Retry support is deferred to a follow-up PR. When added, this is
+    // where RetryStrategy and Semantics (AtLeastOncePerRetry / AtMostOncePerRetry)
+    // will live. The follow-up needs to use service-mediated retries (checkpoint
+    // a RETRY operation + suspend the Lambda) rather than an in-process Task.Delay
+    // loop, to match the Python and JS reference SDKs and to avoid billing Lambda
+    // compute time during retry backoff.
+}