feat: add timeout manager pattern

Adds Timeout Manager fluent and source-generated paths with docs, examples, DI integration, benchmarks, and TinyBDD coverage. Closes #447.

Author: JerrettDavis

README.md

@@ -473,11 +473,11 @@ var cachedRemoteProxy = Proxy<int, string>.Create(id => remoteProxy.Execute(id))
 ---
 
 ## Patterns Table
-PatternKit currently tracks 106 production-readiness patterns. Each catalog pattern is represented in tests, documentation, real-world examples, IoC integration, and the BenchmarkDotNet coverage matrix.
+PatternKit currently tracks 107 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 | 21 | 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, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, Transaction Script, Unit of Work, Value Object |
+| Application Architecture | 22 | 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, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, Timeout Manager, Transaction Script, Unit of Work, Value Object |
 | Behavioral | 11 | Chain of Responsibility, Command, Interpreter, Iterator, Mediator, Memento, Observer, State, Strategy, Template Method, Visitor |
 | Cloud Architecture | 17 | Ambassador, Backends for Frontends, Bulkhead, Cache-Aside, Circuit Breaker, External Configuration Store, Gateway Aggregation, Gateway Routing, Health Endpoint Monitoring, Leader Election, Priority Queue, Queue-Based Load Leveling, Rate Limiting, Retry, Scheduler Agent Supervisor, Sidecar, Strangler Fig |
 | Creational | 5 | Abstract Factory, Builder, Factory Method, Prototype, Singleton |
@@ -497,6 +497,8 @@ BenchmarkDotNet guidance is documented in [docs/guides/benchmarks.md](docs/guide
 | Adapter | Execution | 59.084 ns | 416 B | 20.479 ns | 80 B | Generated adapter execution was faster and allocated less for shipment adaptation. |
 | Activity Tracker | Construction | 13.09 ns | 152 B | 12.98 ns | 152 B | Same allocation; generated was slightly faster in this microbenchmark. |
 | 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. |
+| 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. |
 | Aggregate Root | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Aggregator | Construction | 14.562 ns | 168 B | 15.235 ns | 168 B | Same allocation; fluent was slightly faster in this microbenchmark. |

benchmarks/PatternKit.Benchmarks/Application/TimeoutManagerBenchmarks.cs

@@ -0,0 +1,36 @@
+using BenchmarkDotNet.Attributes;
+using PatternKit.Application.Timeouts;
+using PatternKit.Examples.TimeoutManagerDemo;
+
+namespace PatternKit.Benchmarks.Application;
+
+[BenchmarkCategory("ApplicationArchitecture", "TimeoutManager")]
+public class TimeoutManagerBenchmarks
+{
+    private static readonly OrderReservationRequest Request = new(
+        Guid.Parse("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"),
+        "REQ-100",
+        TimeSpan.FromMinutes(15));
+
+    private static readonly DateTimeOffset ExpiresAt = DateTimeOffset.UtcNow.AddMinutes(20);
+
+    [Benchmark(Baseline = true, Description = "Fluent: create timeout manager")]
+    [BenchmarkCategory("Fluent", "Construction")]
+    public TimeoutManager<Guid> Fluent_CreateTimeoutManager()
+        => OrderReservationTimeoutManagers.CreateFluent();
+
+    [Benchmark(Description = "Generated: create timeout manager")]
+    [BenchmarkCategory("Generated", "Construction")]
+    public TimeoutManager<Guid> Generated_CreateTimeoutManager()
+        => GeneratedOrderReservationTimeoutManager.CreateGenerated();
+
+    [Benchmark(Description = "Fluent: expire order reservation timeout")]
+    [BenchmarkCategory("Fluent", "Execution")]
+    public OrderReservationTimeoutSummary Fluent_ExpireOrderReservation()
+        => OrderReservationTimeoutDemoRunner.RunFluent(Request, ExpiresAt);
+
+    [Benchmark(Description = "Generated: expire order reservation timeout")]
+    [BenchmarkCategory("Generated", "Execution")]
+    public OrderReservationTimeoutSummary Generated_ExpireOrderReservation()
+        => OrderReservationTimeoutDemoRunner.RunGeneratedStatic(Request, ExpiresAt);
+}

docs/examples/order-reservation-timeout-manager.md

@@ -0,0 +1,23 @@
+# Order Reservation Timeout Manager
+
+This example models an order reservation hold that expires if the customer does not complete checkout before the deadline.
+
+The fluent path builds the manager directly:
+
+```csharp
+var manager = OrderReservationTimeoutManagers.CreateFluent();
+```
+
+The generated path uses a source-generated factory:
+
+```csharp
+var manager = GeneratedOrderReservationTimeoutManager.CreateGenerated();
+```
+
+The example is importable through standard dependency injection:
+
+```csharp
+services.AddOrderReservationTimeoutDemo();
+```
+
+`OrderReservationTimeoutDemoRunner` schedules a reservation timeout and expires due holds. Production applications can pair the expired order identifiers with a message channel, outbox, saga, or service layer operation to release inventory and notify customers.

docs/examples/toc.yml

@@ -7,6 +7,9 @@
 - name: Dashboard Activity Tracker
   href: dashboard-activity-tracker.md
 
+- name: Order Reservation Timeout Manager
+  href: order-reservation-timeout-manager.md
+
 - name: Auth & Logging with `ActionChain<HttpRequest>`
   href: auth-logging-chain.md
 

docs/generators/index.md

@@ -62,6 +62,7 @@ PatternKit includes a Roslyn incremental generator package (`PatternKit.Generato
 | [**Repository**](repository.md) | In-memory repository factories from key selectors | `[GenerateRepository]` |
 | [**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]` |
+| [**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]` |
 | [**Data Mapper**](data-mapper.md) | Domain/data model mapper factories | `[GenerateDataMapper]` |

docs/generators/timeout-manager.md

@@ -0,0 +1,23 @@
+# Timeout Manager Generator
+
+The Timeout Manager generator creates a strongly typed factory for `TimeoutManager<TKey>` from a partial host type.
+
+```csharp
+using PatternKit.Generators.Timeouts;
+
+[GenerateTimeoutManager(typeof(Guid), FactoryMethodName = "CreateGenerated", ManagerName = "order-reservation-timeouts")]
+public static partial class GeneratedOrderReservationTimeoutManager;
+```
+
+Generated output:
+
+```csharp
+TimeoutManager<Guid> manager = GeneratedOrderReservationTimeoutManager.CreateGenerated();
+```
+
+The generated path removes repeated factory boilerplate while keeping the runtime manager explicit and importable through normal `IServiceCollection` registration.
+
+## Diagnostics
+
+- `PKTM001`: the host type must be partial.
+- `PKTM002`: `FactoryMethodName` and `ManagerName` must be non-empty.

docs/generators/toc.yml

@@ -261,6 +261,9 @@
 - name: Table Data Gateway
   href: table-data-gateway.md
 
+- name: Timeout Manager
+  href: timeout-manager.md
+
 - name: Strategy
   href: strategy.md
 

docs/guides/benchmark-results.md

@@ -17,6 +17,8 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 | Adapter | Execution | 59.084 ns | 416 B | 20.479 ns | 80 B | Generated adapter execution was faster and allocated less for shipment adaptation. |
 | Activity Tracker | Construction | 13.09 ns | 152 B | 12.98 ns | 152 B | Same allocation; generated was slightly faster in this microbenchmark. |
 | 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. |
+| 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. |
 | Aggregate Root | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Aggregator | Construction | 14.562 ns | 168 B | 15.235 ns | 168 B | Same allocation; fluent was slightly faster in this microbenchmark. |
@@ -230,19 +232,19 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 
 ## Coverage Matrix Summary
 
-The coverage matrix currently publishes 106 catalog patterns and 424 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 107 catalog patterns and 428 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 | 21 | 84 |
+| Application Architecture | 22 | 88 |
 | Behavioral | 11 | 44 |
 | Cloud Architecture | 17 | 68 |
 | Creational | 5 | 20 |
 | Enterprise Integration | 41 | 164 |
 | Messaging Reliability | 3 | 12 |
 | Structural | 7 | 28 |
 
-The generator matrix currently publishes 101 generator source route results.
+The generator matrix currently publishes 102 generator source route results.
 
 ## Hosting Integration Matrix Results
 
@@ -263,6 +265,7 @@ The generator matrix currently publishes 101 generator source route results.
 | Category | Pattern | Fluent construction | Fluent execution | Generated construction | Generated execution |
 | --- | --- | --- | --- | --- | --- |
 | Application Architecture | Activity Tracker | 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 |
 | Application Architecture | Audit Log | Covered | Covered | Covered | Covered |
@@ -373,6 +376,7 @@ The generator matrix currently publishes 101 generator source route results.
 | Generator | Source | Matrix result |
 | --- | --- | --- |
 | ActivityTrackerGenerator | `src/PatternKit.Generators/ActivityTracking/ActivityTrackerGenerator.cs` | Covered |
+| TimeoutManagerGenerator | `src/PatternKit.Generators/Timeouts/TimeoutManagerGenerator.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

@@ -34,6 +34,8 @@ The following numbers were captured on Windows 11, Intel Core i9-14900K, .NET SD
 | Adapter | Execution | 59.084 ns | 416 B | 20.479 ns | 80 B | Generated adapter execution was faster and allocated less for shipment adaptation. |
 | Activity Tracker | Construction | 13.09 ns | 152 B | 12.98 ns | 152 B | Same allocation; generated was slightly faster in this microbenchmark. |
 | 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. |
+| 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. |
 | Aggregate Root | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Aggregator | Construction | 14.562 ns | 168 B | 15.235 ns | 168 B | Same allocation; fluent was slightly faster in this microbenchmark. |

docs/guides/pattern-coverage.md

@@ -125,6 +125,7 @@ The source of truth is `PatternKitPatternCatalog` in `src/PatternKit.Examples/Pr
 | Application Architecture | Materialized View | `IMaterializedView<TState,TEvent>` and `MaterializedView<TState,TEvent>` | Materialized View generator |
 | Application Architecture | Anti-Corruption Layer | `AntiCorruptionLayer<TExternal, TDomain>` | Anti-Corruption Layer generator |
 | Application Architecture | Activity Tracker | `ActivityTracker` | Activity Tracker generator |
+| Application Architecture | Timeout Manager | `TimeoutManager<TKey>` | Timeout Manager generator |
 
 ## Research Baselines