feat: add cache stampede protection pattern

Adds Cache Stampede Protection fluent and source-generated paths with docs, examples, DI integration, benchmarks, and TinyBDD coverage. Closes #449.

Author: JerrettDavis

README.md

@@ -473,13 +473,13 @@ var cachedRemoteProxy = Proxy<int, string>.Create(id => remoteProxy.Execute(id))
 ---
 
 ## Patterns Table
-PatternKit currently tracks 108 production-readiness patterns. Each catalog pattern is represented in tests, documentation, real-world examples, IoC integration, and the BenchmarkDotNet coverage matrix.
+PatternKit currently tracks 109 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 |
 | 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 |
+| Cloud Architecture | 18 | 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, Retry, Scheduler Agent Supervisor, Sidecar, Strangler Fig |
 | Creational | 5 | Abstract Factory, Builder, Factory Method, Prototype, Singleton |
 | Enterprise Integration | 41 | Aggregator, Canonical Data Model, Channel Adapter, Channel Purger, Claim Check, Competing Consumers, Content Enricher, Content-Based Router, Control Bus, Correlation Identifier, Dead Letter Channel, Durable Subscriber, Dynamic Router, Event Notification, Event-Carried State Transfer, Event-Driven Consumer, Guaranteed Delivery, Invalid Message Channel, Mailbox, Message Bus, Message Channel, Message Envelope, Message Expiration, Message Filter, Message History, Message Store, Message Translator, Messaging Bridge, Messaging Gateway, Pipes and Filters, Polling Consumer, Publish-Subscribe, Recipient List, Request-Reply, Resequencer, Routing Slip, Saga / Process Manager, Scatter-Gather, Service Activator, Splitter, Wire Tap |
 | Messaging Reliability | 3 | Idempotent Receiver, Inbox, Outbox |
@@ -519,6 +519,8 @@ BenchmarkDotNet guidance is documented in [docs/guides/benchmarks.md](docs/guide
 | Bridge | Execution | 91.848 ns | 664 B | 30.004 ns | 160 B | Generated bridge forwarding was faster and allocated less for notice rendering. |
 | Bulkhead | Construction | 20.56 ns | 216 B | 20.48 ns | 216 B | Effectively equivalent for this microbenchmark. |
 | Bulkhead | Execution | 102.70 ns | 592 B | 106.11 ns | 592 B | Same allocation; fluent was slightly faster for the shipping allocation workflow. |
+| Cache Stampede Protection | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Cache Stampede Protection | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Cache-Aside | Construction | 19.91 ns | 200 B | 19.85 ns | 200 B | Effectively equivalent for this microbenchmark. |
 | Cache-Aside | Execution | 216.50 ns | 1,048 B | 208.60 ns | 1,048 B | Same allocation; generated was slightly faster for the miss-then-hit workflow. |
 | Canonical Data Model | Construction | 75.482 ns | 632 B | 59.947 ns | 496 B | Generated reduced construction time and allocation in this microbenchmark. |

benchmarks/PatternKit.Benchmarks/Cloud/CacheStampedeProtectionBenchmarks.cs

@@ -0,0 +1,31 @@
+using BenchmarkDotNet.Attributes;
+using PatternKit.Cloud.CacheStampedeProtection;
+using PatternKit.Examples.CacheStampedeProtectionDemo;
+
+namespace PatternKit.Benchmarks.Cloud;
+
+[BenchmarkCategory("Cloud", "CacheStampedeProtection")]
+public class CacheStampedeProtectionBenchmarks
+{
+    private static readonly ProductAvailabilityRequest Request = new("SKU-100", "us");
+
+    [Benchmark(Baseline = true, Description = "Fluent: create cache stampede protection policy")]
+    [BenchmarkCategory("Fluent", "Construction")]
+    public CacheStampedeProtectionPolicy<ProductAvailabilitySnapshot> Fluent_CreatePolicy()
+        => ProductCatalogStampedeProtectionPolicies.CreateFluent();
+
+    [Benchmark(Description = "Generated: create cache stampede protection policy")]
+    [BenchmarkCategory("Generated", "Construction")]
+    public CacheStampedeProtectionPolicy<ProductAvailabilitySnapshot> Generated_CreatePolicy()
+        => GeneratedProductCatalogStampedeProtectionPolicy.CreateGenerated();
+
+    [Benchmark(Description = "Fluent: share product catalog load")]
+    [BenchmarkCategory("Fluent", "Execution")]
+    public IReadOnlyList<ProductAvailabilitySummary> Fluent_ShareProductCatalogLoad()
+        => ProductCatalogStampedeProtectionDemoRunner.RunFluentAsync(Request).AsTask().GetAwaiter().GetResult();
+
+    [Benchmark(Description = "Generated: share product catalog load")]
+    [BenchmarkCategory("Generated", "Execution")]
+    public IReadOnlyList<ProductAvailabilitySummary> Generated_ShareProductCatalogLoad()
+        => ProductCatalogStampedeProtectionDemoRunner.RunGeneratedStaticAsync(Request).AsTask().GetAwaiter().GetResult();
+}

docs/examples/product-catalog-cache-stampede-protection.md

@@ -0,0 +1,23 @@
+# Product Catalog Cache Stampede Protection
+
+This example protects product availability reads from duplicate origin loads when two requests miss the same catalog key at the same time.
+
+```csharp
+var request = new ProductAvailabilityRequest("SKU-100", "us");
+var results = await ProductCatalogStampedeProtectionDemoRunner.RunFluentAsync(request);
+```
+
+The generated route uses the same workflow through a generated policy factory:
+
+```csharp
+var policy = GeneratedProductCatalogStampedeProtectionPolicy.CreateGenerated();
+var service = new ProductCatalogStampedeProtectionService(policy, origin);
+```
+
+Import the demo into a host with:
+
+```csharp
+services.AddProductCatalogStampedeProtectionDemo();
+```
+
+The registration provides `CacheStampedeProtectionPolicy<ProductAvailabilitySnapshot>`, `ProductCatalogOrigin`, `ProductCatalogStampedeProtectionService`, and `ProductCatalogStampedeProtectionDemoRunner`.

docs/examples/toc.yml

@@ -280,6 +280,9 @@
 - name: Product Catalog Cache-Aside
   href: product-catalog-cache-aside.md
 
+- name: Product Catalog Cache Stampede Protection
+  href: product-catalog-cache-stampede-protection.md
+
 - name: Product Search Rate Limiting
   href: product-search-rate-limiting.md
 

docs/generators/cache-stampede-protection.md

@@ -0,0 +1,18 @@
+# Cache Stampede Protection Generator
+
+The Cache Stampede Protection generator creates a strongly typed factory for `CacheStampedeProtectionPolicy<TResult>` from a partial host type.
+
+```csharp
+using PatternKit.Generators.CacheStampedeProtection;
+
+[GenerateCacheStampedeProtection(typeof(ProductAvailabilitySnapshot), FactoryMethodName = "CreateGenerated", PolicyName = "product-catalog-single-flight")]
+public static partial class GeneratedProductCatalogStampedeProtectionPolicy;
+```
+
+Generated usage:
+
+```csharp
+var policy = GeneratedProductCatalogStampedeProtectionPolicy.CreateGenerated();
+```
+
+The host type must be partial. `FactoryMethodName` and `PolicyName` must be non-empty when provided.

docs/generators/index.md

@@ -132,6 +132,7 @@ PatternKit includes a Roslyn incremental generator package (`PatternKit.Generato
 | [**Health Endpoint Monitoring**](health-endpoint-monitoring.md) | Typed service health endpoint factories | `[GenerateHealthEndpoint]` |
 | [**Priority Queue**](priority-queue.md) | Business-priority queue factories | `[GeneratePriorityQueue]` |
 | [**Cache-Aside**](cache-aside.md) | Read-through cache policy factories with TTL and cache predicates | `[GenerateCacheAsidePolicy]` |
+| [**Cache Stampede Protection**](cache-stampede-protection.md) | Keyed single-flight policy factories for suppressing duplicate cache-miss loads | `[GenerateCacheStampedeProtection]` |
 | [**Rate Limiting**](rate-limiting.md) | Key-partitioned fixed-window rate limit policy factories | `[GenerateRateLimitPolicy]` |
 | [**External Configuration Store**](external-configuration-store.md) | Typed centralized configuration loaders | `[GenerateExternalConfigurationStore]` |
 | [**Gateway Aggregation**](gateway-aggregation.md) | API gateway response composition factories | `[GenerateGatewayAggregation]` |

docs/generators/toc.yml

@@ -31,6 +31,9 @@
 - name: Cache-Aside
   href: cache-aside.md
 
+- name: Cache Stampede Protection
+  href: cache-stampede-protection.md
+
 - name: Canonical Data Model
   href: canonical-data-model.md
 

docs/guides/benchmark-results.md

@@ -39,6 +39,8 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 | Bridge | Execution | 91.848 ns | 664 B | 30.004 ns | 160 B | Generated bridge forwarding was faster and allocated less for notice rendering. |
 | Bulkhead | Construction | 20.56 ns | 216 B | 20.48 ns | 216 B | Effectively equivalent for this microbenchmark. |
 | Bulkhead | Execution | 102.70 ns | 592 B | 106.11 ns | 592 B | Same allocation; fluent was slightly faster for the shipping allocation workflow. |
+| Cache Stampede Protection | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Cache Stampede Protection | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Cache-Aside | Construction | 19.91 ns | 200 B | 19.85 ns | 200 B | Effectively equivalent for this microbenchmark. |
 | Cache-Aside | Execution | 216.50 ns | 1,048 B | 208.60 ns | 1,048 B | Same allocation; generated was slightly faster for the miss-then-hit workflow. |
 | Canonical Data Model | Construction | 75.482 ns | 632 B | 59.947 ns | 496 B | Generated reduced construction time and allocation in this microbenchmark. |
@@ -234,19 +236,19 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 
 ## Coverage Matrix Summary
 
-The coverage matrix currently publishes 108 catalog patterns and 432 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 109 catalog patterns and 436 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 |
 | Behavioral | 11 | 44 |
-| Cloud Architecture | 17 | 68 |
+| Cloud Architecture | 18 | 72 |
 | Creational | 5 | 20 |
 | Enterprise Integration | 41 | 164 |
 | Messaging Reliability | 3 | 12 |
 | Structural | 7 | 28 |
 
-The generator matrix currently publishes 103 generator source route results.
+The generator matrix currently publishes 104 generator source route results.
 
 ## Hosting Integration Matrix Results
 
@@ -301,9 +303,10 @@ The generator matrix currently publishes 103 generator source route results.
 | Behavioral | Template Method | Covered | Covered | Covered | Covered |
 | Behavioral | Visitor | Covered | Covered | Covered | Covered |
 | Cloud Architecture | Ambassador | Covered | Covered | Covered | Covered |
-| Cloud Architecture | Backends for Frontends | Covered | Covered | Covered | Covered |
-| Cloud Architecture | Bulkhead | Covered | Covered | Covered | Covered |
-| Cloud Architecture | Cache-Aside | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Backends for Frontends | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Bulkhead | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Cache Stampede Protection | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Cache-Aside | Covered | Covered | Covered | Covered |
 | Cloud Architecture | Circuit Breaker | Covered | Covered | Covered | Covered |
 | Cloud Architecture | External Configuration Store | Covered | Covered | Covered | Covered |
 | Cloud Architecture | Gateway Aggregation | Covered | Covered | Covered | Covered |
@@ -389,8 +392,9 @@ The generator matrix currently publishes 103 generator source route results.
 | BackendsForFrontendsGenerator | `src/PatternKit.Generators/BackendsForFrontends/BackendsForFrontendsGenerator.cs` | Covered |
 | BridgeGenerator | `src/PatternKit.Generators/Bridge/BridgeGenerator.cs` | Covered |
 | BuilderGenerator | `src/PatternKit.Generators/Builders/BuilderGenerator.cs` | Covered |
-| BulkheadPolicyGenerator | `src/PatternKit.Generators/Bulkhead/BulkheadPolicyGenerator.cs` | Covered |
-| CacheAsidePolicyGenerator | `src/PatternKit.Generators/CacheAside/CacheAsidePolicyGenerator.cs` | Covered |
+| BulkheadPolicyGenerator | `src/PatternKit.Generators/Bulkhead/BulkheadPolicyGenerator.cs` | Covered |
+| CacheAsidePolicyGenerator | `src/PatternKit.Generators/CacheAside/CacheAsidePolicyGenerator.cs` | Covered |
+| CacheStampedeProtectionGenerator | `src/PatternKit.Generators/CacheStampedeProtection/CacheStampedeProtectionGenerator.cs` | Covered |
 | CanonicalDataModelGenerator | `src/PatternKit.Generators/CanonicalDataModel/CanonicalDataModelGenerator.cs` | Covered |
 | ChainGenerator | `src/PatternKit.Generators/Chain/ChainGenerator.cs` | Covered |
 | CircuitBreakerPolicyGenerator | `src/PatternKit.Generators/CircuitBreaker/CircuitBreakerPolicyGenerator.cs` | Covered |

docs/guides/benchmarks.md

@@ -56,6 +56,8 @@ The following numbers were captured on Windows 11, Intel Core i9-14900K, .NET SD
 | Bridge | Execution | 91.848 ns | 664 B | 30.004 ns | 160 B | Generated bridge forwarding was faster and allocated less for notice rendering. |
 | Bulkhead | Construction | 20.56 ns | 216 B | 20.48 ns | 216 B | Effectively equivalent for this microbenchmark. |
 | Bulkhead | Execution | 102.70 ns | 592 B | 106.11 ns | 592 B | Same allocation; fluent was slightly faster for the shipping allocation workflow. |
+| Cache Stampede Protection | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Cache Stampede Protection | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Cache-Aside | Construction | 19.91 ns | 200 B | 19.85 ns | 200 B | Effectively equivalent for this microbenchmark. |
 | Cache-Aside | Execution | 216.50 ns | 1,048 B | 208.60 ns | 1,048 B | Same allocation; generated was slightly faster for the miss-then-hit workflow. |
 | Canonical Data Model | Construction | 75.482 ns | 632 B | 59.947 ns | 496 B | Generated reduced construction time and allocation in this microbenchmark. |

docs/guides/pattern-coverage.md

@@ -90,6 +90,7 @@ The source of truth is `PatternKitPatternCatalog` in `src/PatternKit.Examples/Pr
 | Cloud Architecture | Retry | `RetryPolicy<T>` | Retry generator |
 | Cloud Architecture | Circuit Breaker | `CircuitBreakerPolicy<T>` | Circuit Breaker generator |
 | Cloud Architecture | Bulkhead | `BulkheadPolicy<T>` | Bulkhead generator |
+| Cloud Architecture | Cache Stampede Protection | `CacheStampedeProtectionPolicy<TResult>` | Cache Stampede Protection generator |
 | Cloud Architecture | Queue-Based Load Leveling | `QueueLoadLevelingPolicy<T>` | Queue Load Leveling generator |
 | Cloud Architecture | Health Endpoint Monitoring | `HealthEndpoint<TContext>` | Health Endpoint Monitoring generator |
 | Cloud Architecture | Priority Queue | `PriorityQueuePolicy<TItem, TPriority>` | Priority Queue generator |