refactor(durable)!: relax handler signature validation

Author: j-d-ha

decisions/ADR-004-durable-handler-signature-and-diagnostics-contract.md

@@ -90,20 +90,20 @@ internal partial class DurableExampleJsonContext : JsonSerializerContext;
 
 ## Handler contract
 
-Durable handlers support two exact return forms:
+Durable handlers support two return forms:
 
-| Form            | Purpose                       | Required explicit serializer roots             |
-| --------------- | ----------------------------- | ---------------------------------------------- |
-| `Task`          | Workflow with no typed result | outer input, outer output, `TInput`            |
-| `Task<TOutput>` | Workflow with typed result    | outer input, outer output, `TInput`, `TOutput` |
+| Form            | Purpose                       |
+| --------------- | ----------------------------- |
+| `Task`          | Workflow with no typed result |
+| `Task<TOutput>` | Workflow with typed result    |
 
-Both forms require exactly one `[FromEvent] TInput` and exactly one exact AWS `IDurableContext`. Input is never inferred, and parameter order is unrestricted. Additional parameters may be `ILambdaContext`, `ILambdaInvocationContext`, ordinary DI, keyed DI, or optional DI. See [Dependency Injection](../guides/dependency-injection.md) for service lifetimes.
+`[FromEvent] TInput` and AWS `IDurableContext` are optional; a handler may use either, both, or neither. Parameter order is unrestricted. Other parameters use the normal handler binding rules. See [Dependency Injection](../guides/dependency-injection.md) for service lifetimes.
 
 Do not expose `DurableExecutionInvocationInput`, `DurableExecutionInvocationOutput`, streams, or AWS client in high-level handler. MinimalLambda directly deserializes and serializes hidden outer envelopes through its configured Lambda serializer; durable envelopes are not available through `IEventFeature` or `IResponseFeature`. It also owns raw-stream hosting, middleware, DI scope, and physical invocation context. AWS runtime owns workflow payloads, `IDurableContext`, checkpoints, replay, suspension, waits, and durable status/result mapping.
 
 ### Cancellation
 
-Never add root `CancellationToken` to durable handler. Generator reports `LH0009` because near-timeout root cancellation could turn retryable physical invocation into terminal `FAILED` workflow. AWS operation callbacks already receive SDK-linked cancellation tokens, while `WrapAsync` exposes no lifecycle-token hook. Automatically linking MinimalLambda physical-invocation cancellation would couple replay to Lambda timeout. Use AWS-supplied token inside step, callback, child workflow, map, parallel, and other operation callbacks, as sample does.
+AWS operation callbacks receive SDK-linked cancellation tokens. If a durable handler also reads `ILambdaInvocationContext.CancellationToken`, it owns the resulting physical-invocation failure and retry behavior.
 
 Reading `ILambdaInvocationContext.CancellationToken` explicitly means accepting root failure/retry consequences.
 
@@ -132,12 +132,12 @@ One registered `ILambdaSerializer` handles MinimalLambda outer envelopes and AWS
 - [ ] Register context with `AddLambdaSerializerWithContext<TContext>()`.
 - [ ] Add `DurableExecutionInvocationInput` root.
 - [ ] Add `DurableExecutionInvocationOutput` root.
-- [ ] Add workflow `TInput` root.
-- [ ] For `Task<TOutput>`, add `TOutput` root. `Task` handlers therefore need three signature roots; `Task<TOutput>` handlers need four.
+- [ ] Add the event type if the handler declares one.
+- [ ] For `Task<TOutput>`, add `TOutput` when required by the configured serializer.
 - [ ] Add every operation payload, result, and state root used by steps, callbacks, invokes, child workflows, waits, maps, or parallel branches.
 - [ ] Publish intended runtime and architecture with NativeAOT enabled; restore/build alone does not compile native code.
 
-Generator cannot discover operation types hidden inside method bodies or referenced libraries. `LH0011` checks only explicit outer input/output and handler input/output declarations. It does not inspect member graphs or hidden operation types, and warning absence does not prove serializer completeness. `LH0011` does not suppress generation, so missing runtime metadata can still fail later.
+The generator does not inspect serializer contexts. Ensure that the context registered for the Lambda serializer includes the outer envelopes and every payload, result, and state type your workflow uses.
 
 Local source-based `net10.0` NativeAOT publish passes. This proves local publishing only. Managed cloud integration remains unverified, and Durable Execution NativeAOT support remains experimental. Successful local publish is not evidence of deployment, IAM, replay, or managed-service behavior. See [AWS NativeAOT guidance](https://docs.aws.amazon.com/lambda/latest/dg/dotnet-native-aot.html) and project [support matrix](https://github.com/LayeredCraft/minimal-lambda/blob/main/decisions/durable-dependency-support-matrix.md).
 
@@ -171,11 +171,7 @@ Split tests by ownership:
 
 | Symptom                                                    | Fix                                                                                                                                                                                                     |
 | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `LH0007`                                                   | Declare exactly one `[FromEvent] TInput`; remove missing or duplicate event inputs.                                                                                                                     |
-| `LH0008`                                                   | Declare exactly one exact `Amazon.Lambda.DurableExecution.IDurableContext`.                                                                                                                             |
-| `LH0009`                                                   | Remove unsupported parameter. Common cases: root `CancellationToken`, stream/outer envelope, conflicting binding attribute, or `ref`/`in`/`out`. Use operation callback token or raw path where needed. |
-| `LH0010`                                                   | Return exact `Task` or `Task<TOutput>`. Sync, `ValueTask`, custom awaitable, stream, and envelope outputs are unsupported.                                                                              |
-| `LH0011`                                                   | Add explicit `[JsonSerializable(typeof(...))]` signature root. Then audit hidden operation roots manually; warning checks only signature roots and does not block emission.                             |
+| `LH0007`                                                   | Return `Task` or `Task<TOutput>`.                                                                                                                       |
 | Runtime `InvalidOperationException` at `MapDurableHandler` | Compile-time interceptor did not replace fallback stub. Keep direct `MinimalLambda` reference and project interceptor/source-generator configuration.                                                   |
 | AWS DE001-DE004 absent                                     | Add direct `Amazon.Lambda.DurableExecution` reference; analyzer assets are not transitive.                                                                                                              |
 | Duplicate logs, metrics, or DI work                        | Replay caused another physical invocation. Use AWS replay-aware logger for workflow logs and make invocation observation replay-safe.                                                                   |

docs/features/durable-execution.md

@@ -19,11 +19,10 @@ public static class MapDurableHandlerLambdaApplicationExtensions
         /// <remarks>
         ///     <para>
         ///         Source generation creates wiring code that resolves handler dependencies and adapts the
-        ///         handler to the AWS Lambda Durable Execution protocol. A supported handler declares exactly
-        ///         one <see cref="FromEventAttribute" /> workflow input and one exact AWS
-        ///         <c>IDurableContext</c>, and returns exactly <see cref="Task" /> or
-        ///         <see cref="Task{TResult}" />. Invocation contexts and dependency-injection services can be
-        ///         additional parameters; a root <see cref="CancellationToken" /> is not supported.
+        ///         handler to the AWS Lambda Durable Execution protocol. A handler can optionally declare a
+        ///         <see cref="FromEventAttribute" /> workflow input and an AWS <c>IDurableContext</c>.
+        ///         It returns <see cref="Task" /> or <see cref="Task{TResult}" />. Invocation contexts and
+        ///         dependency-injection services can be additional parameters.
         ///     </para>
         ///     <para>
         ///         Invocation contexts, dependency-injection scopes, and middleware belong to one physical

src/MinimalLambda.DurableExecution/MapDurableHandlerLambdaApplicationExtensions.cs

@@ -91,8 +91,8 @@ internal sealed class OrderService : IOrderService
 internal partial class DurableJsonContext : JsonSerializerContext;
 ```
 
-First four serializer roots are required for outer input/output envelopes and typed workflow
-input/output. Explicitly add every payload, result, or state type used by steps, callbacks, invokes,
+Register the serializer roots required by your configured serializer, including the outer input/output
+envelopes and every payload, result, or state type used by steps, callbacks, invokes,
 child workflows, waits, maps, and parallel branches; `ProcessOrderStepResult` is one representative
 step root. Generator cannot discover types hidden inside operation bodies or referenced libraries.
 Same registered `ILambdaSerializer` handles MinimalLambda outer envelopes and AWS inner values.
@@ -101,16 +101,14 @@ provide exactly-once execution.
 
 ## Handler, cancellation, and context contract
 
-Durable handler must declare exactly one `[FromEvent] TInput`, exactly one exact AWS
-`IDurableContext`, and return exact `Task` or `Task<TOutput>`. Parameter order is unrestricted.
-Optional additional parameters are `ILambdaContext`, `ILambdaInvocationContext`, ordinary DI, keyed
-DI, or optional DI. Input is never inferred. Synchronous, `ValueTask`, custom-awaitable, `Stream`,
-outer durable envelope, and root `CancellationToken` forms are rejected by generator diagnostics.
+Durable handlers return `Task` or `Task<TOutput>`. `[FromEvent] TInput` and AWS `IDurableContext`
+are optional; a handler may use either, both, or neither. Parameter order is unrestricted. Other
+parameters are resolved using the normal handler binding rules. The generator does not validate
+serializer roots or impose a durable-specific payload-shape policy.
 
-Do not put `CancellationToken` on root handler. Near-timeout cancellation could fault workflow into
-terminal `FAILED` state instead of letting physical invocation retry. AWS operation callbacks already
-receive SDK-linked cancellation tokens, and `WrapAsync` exposes no lifecycle-token hook. Reading
-`ILambdaInvocationContext.CancellationToken` explicitly means owning those failure/retry consequences.
+If a handler needs physical-invocation cancellation, read it through
+`ILambdaInvocationContext.CancellationToken` and own the resulting failure/retry consequences. AWS
+operation callbacks already receive SDK-linked cancellation tokens.
 
 Inject `ILambdaInvocationContext` as above, or recover exact physical invocation context carried by
 AWS durable context:

src/MinimalLambda.DurableExecution/README.md

@@ -3,7 +3,3 @@
 Rule ID | Category | Severity | Notes
 --------|----------|----------|------
 LH0007 | MinimalLambda.Usage | Error | Diagnostics
-LH0008 | MinimalLambda.Usage | Error | Diagnostics
-LH0009 | MinimalLambda.Usage | Error | Diagnostics
-LH0010 | MinimalLambda.Usage | Error | Diagnostics
-LH0011 | MinimalLambda.Configuration | Warning | Diagnostics

src/MinimalLambda.SourceGenerators/AnalyzerReleases.Unshipped.md

@@ -10,86 +10,12 @@ internal sealed record DiagnosticInfo(
     LocationInfo? LocationInfo = null,
     params object?[] MessageArgs)
 {
-    internal int TreeOrdinal { get; init; } = int.MaxValue;
-    internal int SubKey { get; init; }
+    public bool Equals(DiagnosticInfo? other) =>
+        other is not null
+        && Equals(DiagnosticDescriptor.Id, other.DiagnosticDescriptor.Id)
+        && Equals(LocationInfo, other.LocationInfo);
 
-    public bool Equals(DiagnosticInfo? other)
-    {
-        if (other is null
-            || !string.Equals(
-                DiagnosticDescriptor.Id,
-                other.DiagnosticDescriptor.Id,
-                StringComparison.Ordinal)
-            || !Equals(LocationInfo, other.LocationInfo)
-            || MessageArgs.Length != other.MessageArgs.Length)
-            return false;
-
-        for (var i = 0; i < MessageArgs.Length; i++)
-            if (!Equals(MessageArgs[i], other.MessageArgs[i]))
-                return false;
-
-        return true;
-    }
-
-    public override int GetHashCode()
-    {
-        var hash = HashCode.Combine(DiagnosticDescriptor.Id, LocationInfo);
-        foreach (var argument in MessageArgs)
-            hash = HashCode.Combine(hash, argument);
-        return hash;
-    }
-}
-
-internal sealed class DiagnosticInfoOrderComparer : IComparer<DiagnosticInfo>
-{
-    internal static readonly DiagnosticInfoOrderComparer Instance = new();
-
-    public int Compare(DiagnosticInfo? x, DiagnosticInfo? y)
-    {
-        if (ReferenceEquals(x, y))
-            return 0;
-        if (x is null)
-            return -1;
-        if (y is null)
-            return 1;
-
-        var result = x.TreeOrdinal.CompareTo(y.TreeOrdinal);
-        if (result != 0)
-            return result;
-        result = (x.LocationInfo?.TextSpan.Start ?? int.MaxValue).CompareTo(
-            y.LocationInfo?.TextSpan.Start ?? int.MaxValue);
-        if (result != 0)
-            return result;
-        result = string.CompareOrdinal(x.DiagnosticDescriptor.Id, y.DiagnosticDescriptor.Id);
-        if (result != 0)
-            return result;
-        result = x.SubKey.CompareTo(y.SubKey);
-        if (result != 0)
-            return result;
-
-        var count = Math.Min(x.MessageArgs.Length, y.MessageArgs.Length);
-        for (var i = 0; i < count; i++)
-        {
-            result = CompareArgument(x.MessageArgs[i], y.MessageArgs[i]);
-            if (result != 0)
-                return result;
-        }
-
-        return x.MessageArgs.Length.CompareTo(y.MessageArgs.Length);
-    }
-
-    private static int CompareArgument(object? left, object? right)
-    {
-        if (ReferenceEquals(left, right))
-            return 0;
-        if (left is null)
-            return -1;
-        if (right is null)
-            return 1;
-        if (left is int leftInt && right is int rightInt)
-            return leftInt.CompareTo(rightInt);
-        return string.CompareOrdinal(left.ToString(), right.ToString());
-    }
+    public override int GetHashCode() => HashCode.Combine(DiagnosticDescriptor, LocationInfo);
 }
 
 internal static class DiagnosticInfoExtensions

src/MinimalLambda.SourceGenerators/Diagnostics/DiagnosticInfo.cs

@@ -50,43 +50,11 @@ internal static class Diagnostics
         DiagnosticSeverity.Error,
         true);
 
-    internal static readonly DiagnosticDescriptor InvalidDurableInputCardinality = new(
-        "LH0007",
-        "Invalid durable workflow input cardinality",
-        "Durable handler must declare exactly one event input using '[FromEvent]'; found {0}.",
-        UsageCategory,
-        DiagnosticSeverity.Error,
-        true);
-
-    internal static readonly DiagnosticDescriptor InvalidDurableContextCardinality = new(
-        "LH0008",
-        "Invalid durable context cardinality",
-        "Durable handler must declare exactly one 'Amazon.Lambda.DurableExecution.IDurableContext' parameter; found {0}.",
-        UsageCategory,
-        DiagnosticSeverity.Error,
-        true);
-
-    internal static readonly DiagnosticDescriptor UnsupportedDurableParameter = new(
-        "LH0009",
-        "Unsupported durable handler parameter",
-        "Durable handler parameter '{0}' of type '{1}' is not supported: {2}.",
-        UsageCategory,
-        DiagnosticSeverity.Error,
-        true);
-
     internal static readonly DiagnosticDescriptor UnsupportedDurableReturnType = new(
-        "LH0010",
+        "LH0007",
         "Unsupported durable handler return type",
-        "Durable handler return type '{0}' is not supported; use 'Task' or 'Task<TOutput>' with a closed, nameable, accessible, non-transport output type.",
+        "Durable handler return type '{0}' is not supported; use 'Task' or 'Task<TOutput>'.",
         UsageCategory,
         DiagnosticSeverity.Error,
         true);
-
-    internal static readonly DiagnosticDescriptor MissingDurableSerializerRoot = new(
-        "LH0011",
-        "Durable serializer root is not explicitly declared",
-        "Source-generated serializer context '{0}' does not explicitly declare durable serialization root '{1}'. Add [JsonSerializable(typeof({1}))] to that context or a base context declaration.",
-        ConfigurationCategory,
-        DiagnosticSeverity.Warning,
-        true);
 }