feat: add workflow orchestration pattern

Author: JerrettDavis

README.md

@@ -473,11 +473,11 @@ var cachedRemoteProxy = Proxy<int, string>.Create(id => remoteProxy.Execute(id))
 ---
 
 ## Patterns Table
-PatternKit currently tracks 111 production-readiness patterns. Each catalog pattern is represented in tests, documentation, real-world examples, IoC integration, and the BenchmarkDotNet coverage matrix.
+PatternKit currently tracks 112 production-readiness patterns. Each catalog pattern is represented in tests, documentation, real-world examples, IoC integration, and the BenchmarkDotNet coverage matrix.
 
 | Category | Count | Patterns |
 | --- | ---: | --- |
-| Application Architecture | 23 | Activity Tracker, Aggregate Root, Anti-Corruption Layer, Audit Log, Bounded Context, Context Map, CQRS, Data Mapper, Domain Event, Domain Service, Event Sourcing, Feature Toggle, Identity Map, Manual Task Gate, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, Timeout Manager, Transaction Script, Unit of Work, Value Object |
+| Application Architecture | 24 | Activity Tracker, Aggregate Root, Anti-Corruption Layer, Audit Log, Bounded Context, Context Map, CQRS, Data Mapper, Domain Event, Domain Service, Event Sourcing, Feature Toggle, Identity Map, Manual Task Gate, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, Timeout Manager, Transaction Script, Unit of Work, Value Object, Workflow Orchestration |
 | Behavioral | 11 | Chain of Responsibility, Command, Interpreter, Iterator, Mediator, Memento, Observer, State, Strategy, Template Method, Visitor |
 | Cloud Architecture | 20 | Ambassador, Backends for Frontends, Bulkhead, Cache-Aside, Cache Stampede Protection, Circuit Breaker, External Configuration Store, Gateway Aggregation, Gateway Routing, Health Endpoint Monitoring, Leader Election, Priority Queue, Queue-Based Load Leveling, Rate Limiting, Read-Through Cache, Retry, Scheduler Agent Supervisor, Sidecar, Strangler Fig, Write-Through Cache |
 | Creational | 5 | Abstract Factory, Builder, Factory Method, Prototype, Singleton |
@@ -499,6 +499,8 @@ BenchmarkDotNet guidance is documented in [docs/guides/benchmarks.md](docs/guide
 | Activity Tracker | Execution | 446.88 ns | 1,656 B | 452.36 ns | 1,656 B | Same allocation; fluent was slightly faster for dashboard loading gates. |
 | Manual Task Gate | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Manual Task Gate | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Workflow Orchestration | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Workflow Orchestration | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Timeout Manager | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Timeout Manager | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Aggregate Root | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |

benchmarks/PatternKit.Benchmarks/Application/WorkflowOrchestrationBenchmarks.cs

@@ -0,0 +1,31 @@
+using BenchmarkDotNet.Attributes;
+using PatternKit.Application.WorkflowOrchestration;
+using PatternKit.Examples.WorkflowOrchestrationDemo;
+
+namespace PatternKit.Benchmarks.Application;
+
+[BenchmarkCategory("ApplicationArchitecture", "WorkflowOrchestration")]
+public class WorkflowOrchestrationBenchmarks
+{
+    private static readonly FulfillmentRequest Request = new("ORDER-100", RequiresFraudReview: true, PaymentShouldFail: false);
+
+    [Benchmark(Baseline = true, Description = "Fluent: create workflow orchestration")]
+    [BenchmarkCategory("Fluent", "Construction")]
+    public WorkflowOrchestrator<FulfillmentWorkflowContext> Fluent_CreateWorkflowOrchestration()
+        => FulfillmentWorkflowOrchestrations.CreateFluent();
+
+    [Benchmark(Description = "Generated: create workflow orchestration")]
+    [BenchmarkCategory("Generated", "Construction")]
+    public WorkflowOrchestrator<FulfillmentWorkflowContext> Generated_CreateWorkflowOrchestration()
+        => GeneratedFulfillmentWorkflowOrchestration.CreateGenerated();
+
+    [Benchmark(Description = "Fluent: execute fulfillment workflow orchestration")]
+    [BenchmarkCategory("Fluent", "Execution")]
+    public FulfillmentSummary Fluent_ExecuteFulfillmentWorkflow()
+        => FulfillmentWorkflowOrchestrationDemoRunner.RunFluentAsync(Request).AsTask().GetAwaiter().GetResult();
+
+    [Benchmark(Description = "Generated: execute fulfillment workflow orchestration")]
+    [BenchmarkCategory("Generated", "Execution")]
+    public FulfillmentSummary Generated_ExecuteFulfillmentWorkflow()
+        => FulfillmentWorkflowOrchestrationDemoRunner.RunGeneratedStaticAsync(Request).AsTask().GetAwaiter().GetResult();
+}

docs/examples/fulfillment-workflow-orchestration.md

@@ -0,0 +1,23 @@
+# Fulfillment Workflow Orchestration
+
+This example models a production fulfillment workflow with inventory reservation, optional fraud review, payment capture, warehouse release, retry behavior, and compensation.
+
+The fluent path builds the workflow directly:
+
+```csharp
+var workflow = FulfillmentWorkflowOrchestrations.CreateFluent();
+```
+
+The generated path uses annotated workflow methods:
+
+```csharp
+var workflow = GeneratedFulfillmentWorkflowOrchestration.CreateGenerated();
+```
+
+The example is importable through standard dependency injection:
+
+```csharp
+services.AddFulfillmentWorkflowOrchestrationDemo();
+```
+
+`FulfillmentWorkflowOrchestrationDemoRunner` returns a summary containing the final status, domain events, and workflow history. Production applications can attach the history to audit logs, traces, or outbox messages while keeping the orchestration itself explicit and testable.

docs/examples/index.md

@@ -18,6 +18,7 @@ Welcome! This section collects small, focused demos that show **how to compose b
 * **Enterprise messaging workflows** for envelopes, routers, recipient lists, splitters, aggregators, routing slips, sagas, mailboxes, idempotent receivers, inboxes, and outboxes.
 * **Messaging backplane facade** for host-style setup, typed request/reply, and publish/subscribe over an application-owned transport boundary.
 * **Production-readiness catalog** for DI, generic host, and ASP.NET Core diagnostics that maps every documented example to its source, TinyBDD tests, docs page, integration surfaces, and production checks.
+* **Workflow orchestration** for explicit ordered fulfillment steps with retries, conditional gates, compensation, and execution history.
 
 ## Demos in this section
 
@@ -39,6 +40,9 @@ Welcome! This section collects small, focused demos that show **how to compose b
 * **Enterprise Feature Slices with .NET DI**
   A checkout feature slice registered with `Microsoft.Extensions.DependencyInjection`, exposing a typed `IEnterpriseCheckout` facade while the container owns Flyweight, Factory, Prototype, Chain, Strategy, Decorator, Abstract Factory, Proxy, TypeDispatcher, State Machine, Memento, Observer, and Flow artifacts. See [Enterprise Feature Slices with .NET DI](enterprise-feature-slices.md).
 
+* **Fulfillment Workflow Orchestration**
+  A Generic Host importable fulfillment workflow with fluent and source-generated routes for inventory reservation, fraud review, payment capture, retries, warehouse release, and compensation. See [Fulfillment Workflow Orchestration](fulfillment-workflow-orchestration.md).
+
 * **Minimal Web Request Router**
   A tiny "API gateway" that separates **first-match middleware** (side effects/logging/auth) from **first-match routes** and **content negotiation**. A crisp example of Strategy patterns in an HTTP-ish setting.
 

docs/examples/toc.yml

@@ -13,6 +13,9 @@
 - name: Order Reservation Timeout Manager
   href: order-reservation-timeout-manager.md
 
+- name: Fulfillment Workflow Orchestration
+  href: fulfillment-workflow-orchestration.md
+
 - name: Auth & Logging with `ActionChain<HttpRequest>`
   href: auth-logging-chain.md
 

docs/generators/index.md

@@ -63,6 +63,7 @@ PatternKit includes a Roslyn incremental generator package (`PatternKit.Generato
 | [**Anti-Corruption Layer**](anti-corruption-layer.md) | External-to-domain translation boundaries with validation | `[GenerateAntiCorruptionLayer]` |
 | [**Activity Tracker**](activity-tracker.md) | Active-work tracker gates for loading and readiness workflows | `[GenerateActivityTracker]` |
 | [**Manual Task Gate**](manual-task-gate.md) | Human approval gates for workflow pauses and manual decisions | `[GenerateManualTaskGate]` |
+| [**Workflow Orchestration**](workflow-orchestration.md) | Ordered workflow factories from annotated step methods | `[WorkflowOrchestration]` |
 | [**Timeout Manager**](timeout-manager.md) | Deadline registry for expiring pending workflow work | `[GenerateTimeoutManager]` |
 | [**Audit Log**](audit-log.md) | Append-only audit log factories from key selectors | `[GenerateAuditLog]` |
 | [**Unit of Work**](unit-of-work.md) | Ordered commit and rollback units | `[GenerateUnitOfWork]` |

docs/generators/toc.yml

@@ -106,6 +106,9 @@
 - name: Manual Task Gate
   href: manual-task-gate.md
 
+- name: Workflow Orchestration
+  href: workflow-orchestration.md
+
 - name: Iterator
   href: iterator.md
 

docs/generators/workflow-orchestration.md

@@ -0,0 +1,38 @@
+# Workflow Orchestration Generator
+
+The Workflow Orchestration generator creates a strongly typed factory from a partial host type and annotated workflow methods.
+
+```csharp
+using PatternKit.Generators.WorkflowOrchestration;
+
+[WorkflowOrchestration(FactoryMethodName = "CreateGenerated", WorkflowName = "fulfillment-orchestration")]
+public static partial class GeneratedFulfillmentWorkflow
+{
+    [WorkflowStep("reserve-inventory", 1, Compensation = nameof(ReleaseInventory))]
+    private static ValueTask ReserveInventory(FulfillmentContext context, CancellationToken cancellationToken)
+        => ValueTask.CompletedTask;
+
+    [WorkflowStep("capture-payment", 2, MaxAttempts = 2)]
+    private static ValueTask CapturePayment(FulfillmentContext context, CancellationToken cancellationToken)
+        => ValueTask.CompletedTask;
+
+    private static ValueTask ReleaseInventory(FulfillmentContext context, CancellationToken cancellationToken)
+        => ValueTask.CompletedTask;
+}
+```
+
+Generated output:
+
+```csharp
+WorkflowOrchestrator<FulfillmentContext> workflow = GeneratedFulfillmentWorkflow.CreateGenerated();
+```
+
+Step methods must accept `(TContext, CancellationToken)` and return `ValueTask`. Optional condition methods accept `TContext` and return `bool`. Optional compensation methods use the same signature as a step.
+
+## Diagnostics
+
+- `PKWO001`: the workflow host type must be partial.
+- `PKWO002`: the workflow must declare at least one `[WorkflowStep]` method.
+- `PKWO003`: step, condition, or compensation method signatures are invalid.
+- `PKWO004`: workflow step names or orders are duplicated.
+- `PKWO005`: `FactoryMethodName` and `WorkflowName` must be non-empty.

docs/guides/benchmark-results.md

@@ -19,6 +19,8 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 | Activity Tracker | Execution | 446.88 ns | 1,656 B | 452.36 ns | 1,656 B | Same allocation; fluent was slightly faster for dashboard loading gates. |
 | Manual Task Gate | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Manual Task Gate | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Workflow Orchestration | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Workflow Orchestration | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Timeout Manager | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Timeout Manager | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Aggregate Root | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
@@ -242,19 +244,19 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 
 ## Coverage Matrix Summary
 
-The coverage matrix currently publishes 111 catalog patterns and 444 pattern route results. Each pattern has four BenchmarkDotNet routes: fluent construction, fluent execution, source-generated construction, and source-generated execution. The reusable hosting integration matrix publishes 9 reusable hosting integration route results for package-level `IServiceCollection` registrations.
+The coverage matrix currently publishes 112 catalog patterns and 448 pattern route results. Each pattern has four BenchmarkDotNet routes: fluent construction, fluent execution, source-generated construction, and source-generated execution. The reusable hosting integration matrix publishes 9 reusable hosting integration route results for package-level `IServiceCollection` registrations.
 
 | Category | Patterns | Published route results |
 | --- | ---: | ---: |
-| Application Architecture | 23 | 92 |
+| Application Architecture | 24 | 96 |
 | Behavioral | 11 | 44 |
 | Cloud Architecture | 20 | 80 |
 | Creational | 5 | 20 |
 | Enterprise Integration | 41 | 164 |
 | Messaging Reliability | 3 | 12 |
 | Structural | 7 | 28 |
 
-The generator matrix currently publishes 105 generator source route results.
+The generator matrix currently publishes 106 generator source route results.
 
 ## Hosting Integration Matrix Results
 
@@ -276,6 +278,7 @@ The generator matrix currently publishes 105 generator source route results.
 | --- | --- | --- | --- | --- | --- |
 | Application Architecture | Activity Tracker | Covered | Covered | Covered | Covered |
 | Application Architecture | Manual Task Gate | Covered | Covered | Covered | Covered |
+| Application Architecture | Workflow Orchestration | Covered | Covered | Covered | Covered |
 | Application Architecture | Timeout Manager | Covered | Covered | Covered | Covered |
 | Application Architecture | Aggregate Root | Covered | Covered | Covered | Covered |
 | Application Architecture | Anti-Corruption Layer | Covered | Covered | Covered | Covered |
@@ -392,6 +395,7 @@ The generator matrix currently publishes 105 generator source route results.
 | ActivityTrackerGenerator | `src/PatternKit.Generators/ActivityTracking/ActivityTrackerGenerator.cs` | Covered |
 | TimeoutManagerGenerator | `src/PatternKit.Generators/Timeouts/TimeoutManagerGenerator.cs` | Covered |
 | ManualTaskGateGenerator | `src/PatternKit.Generators/ManualTaskGates/ManualTaskGateGenerator.cs` | Covered |
+| WorkflowOrchestrationGenerator | `src/PatternKit.Generators/WorkflowOrchestration/WorkflowOrchestrationGenerator.cs` | Covered |
 | AggregateCommandHandlerGenerator | `src/PatternKit.Generators/Aggregates/AggregateCommandHandlerGenerator.cs` | Covered |
 | AdapterGenerator | `src/PatternKit.Generators/Adapter/AdapterGenerator.cs` | Covered |
 | AmbassadorGenerator | `src/PatternKit.Generators/Ambassador/AmbassadorGenerator.cs` | Covered |

docs/guides/benchmarks.md

@@ -36,6 +36,8 @@ The following numbers were captured on Windows 11, Intel Core i9-14900K, .NET SD
 | Activity Tracker | Execution | 446.88 ns | 1,656 B | 452.36 ns | 1,656 B | Same allocation; fluent was slightly faster for dashboard loading gates. |
 | Manual Task Gate | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Manual Task Gate | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Workflow Orchestration | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Workflow Orchestration | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Timeout Manager | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Timeout Manager | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Aggregate Root | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |