feat: add Read-Through and Write-Through Cache patterns

README.md

@@ -473,13 +473,13 @@ var cachedRemoteProxy = Proxy<int, string>.Create(id => remoteProxy.Execute(id))
 ---
 
 ## Patterns Table
-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.
+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.
 
 | 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 | 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 |
+| 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 |
 | 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 |
@@ -523,6 +523,12 @@ BenchmarkDotNet guidance is documented in [docs/guides/benchmarks.md](docs/guide
 | 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. |
+| Read-Through / Write-Through Cache | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Read-Through / Write-Through Cache | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Read-Through Cache | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
+| Read-Through Cache | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
+| Write-Through Cache | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
+| Write-Through Cache | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
 | Canonical Data Model | Construction | 75.482 ns | 632 B | 59.947 ns | 496 B | Generated reduced construction time and allocation in this microbenchmark. |
 | Canonical Data Model | Execution | 116.680 ns | 832 B | 92.082 ns | 696 B | Generated reduced execution time and allocation for order normalization. |
 | Channel Adapter | Construction | 38.469 ns | 384 B | 38.681 ns | 384 B | Effectively equivalent for this microbenchmark. |

benchmarks/PatternKit.Benchmarks/Cloud/ReadWriteThroughCacheBenchmarks.cs

@@ -0,0 +1,39 @@
+using BenchmarkDotNet.Attributes;
+using PatternKit.Cloud.ReadWriteThroughCache;
+using PatternKit.Examples.ReadWriteThroughCacheDemo;
+
+namespace PatternKit.Benchmarks.Cloud;
+
+[BenchmarkCategory("Cloud", "ReadWriteThroughCache")]
+public class ReadWriteThroughCacheBenchmarks
+{
+    [Benchmark(Baseline = true, Description = "Fluent: create read/write-through cache policy")]
+    [BenchmarkCategory("Fluent", "Construction")]
+    public ReadWriteThroughCachePolicy<CatalogProduct> Fluent_CreatePolicy()
+        => ProductCatalogReadWriteThroughPolicies.CreateFluent();
+
+    [Benchmark(Description = "Generated: create read/write-through cache policy")]
+    [BenchmarkCategory("Generated", "Construction")]
+    public ReadWriteThroughCachePolicy<CatalogProduct> Generated_CreatePolicy()
+        => GeneratedProductCatalogReadWriteThroughPolicy.CreateGenerated();
+
+    [Benchmark(Description = "Fluent: read/write-through product catalog flow")]
+    [BenchmarkCategory("Fluent", "Execution")]
+    public IReadOnlyList<ProductCatalogReadWriteSummary> Fluent_RunCatalogFlow()
+    {
+        var service = new ProductCatalogReadWriteThroughCacheService(
+            new ProductCatalogReadWriteRepository(new CatalogProduct("SKU-42", "Trail Jacket", 129m)),
+            ProductCatalogReadWriteThroughPolicies.CreateFluent());
+        return new ProductCatalogReadWriteThroughDemoRunner(service).RunAsync().AsTask().GetAwaiter().GetResult();
+    }
+
+    [Benchmark(Description = "Generated: read/write-through product catalog flow")]
+    [BenchmarkCategory("Generated", "Execution")]
+    public IReadOnlyList<ProductCatalogReadWriteSummary> Generated_RunCatalogFlow()
+    {
+        var service = new ProductCatalogReadWriteThroughCacheService(
+            new ProductCatalogReadWriteRepository(new CatalogProduct("SKU-42", "Trail Jacket", 129m)),
+            GeneratedProductCatalogReadWriteThroughPolicy.CreateGenerated());
+        return new ProductCatalogReadWriteThroughDemoRunner(service).RunAsync().AsTask().GetAwaiter().GetResult();
+    }
+}

docs/examples/product-catalog-read-write-through-cache.md

@@ -0,0 +1,18 @@
+# Product Catalog Read-Through and Write-Through Cache
+
+This example models a product catalog repository where reads and writes are coordinated through one cache policy.
+
+- `ReadThroughAsync` loads missing products from the repository and caches them.
+- `WriteThroughAsync` saves the product to the repository before updating the cache.
+- `AddProductCatalogReadWriteThroughDemo()` registers the generated policy, repository, service, and runner with `IServiceCollection`.
+
+```csharp
+var services = new ServiceCollection();
+services.AddProductCatalogReadWriteThroughDemo();
+
+using var provider = services.BuildServiceProvider(validateScopes: true);
+var runner = provider.GetRequiredService<ProductCatalogReadWriteThroughDemoRunner>();
+var results = await runner.RunAsync();
+```
+
+The fluent and source-generated paths produce the same `ReadWriteThroughCachePolicy<CatalogProduct>` surface.

docs/examples/toc.yml

@@ -283,6 +283,9 @@
 - name: Product Catalog Cache Stampede Protection
   href: product-catalog-cache-stampede-protection.md
 
+- name: Product Catalog Read-Through and Write-Through Cache
+  href: product-catalog-read-write-through-cache.md
+
 - name: Product Search Rate Limiting
   href: product-search-rate-limiting.md
 

docs/generators/index.md

@@ -133,6 +133,7 @@ PatternKit includes a Roslyn incremental generator package (`PatternKit.Generato
 | [**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]` |
+| [**Read-Through / Write-Through Cache**](read-write-through-cache.md) | Cache-backed repository policy factories with coordinated read and write paths | `[GenerateReadWriteThroughCachePolicy]` |
 | [**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/read-write-through-cache.md

@@ -0,0 +1,14 @@
+# Read-Through and Write-Through Cache Generator
+
+The read/write-through cache generator creates a strongly typed `ReadWriteThroughCachePolicy<TResult>` factory from `[GenerateReadWriteThroughCachePolicy]`.
+
+```csharp
+[GenerateReadWriteThroughCachePolicy(
+    typeof(CatalogProduct),
+    FactoryMethodName = "CreateGenerated",
+    PolicyName = "product-catalog-read-write-through",
+    TimeToLiveMilliseconds = 300000)]
+public static partial class GeneratedProductCatalogReadWriteThroughPolicy;
+```
+
+The generated factory returns the same runtime policy as the fluent API and applies the configured TTL.

docs/generators/toc.yml

@@ -34,6 +34,9 @@
 - name: Cache Stampede Protection
   href: cache-stampede-protection.md
 
+- name: Read-Through / Write-Through Cache
+  href: read-write-through-cache.md
+
 - name: Canonical Data Model
   href: canonical-data-model.md
 

docs/guides/benchmark-results.md

@@ -43,6 +43,12 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 | 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. |
+| Read-Through / Write-Through Cache | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Read-Through / Write-Through Cache | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Read-Through Cache | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
+| Read-Through Cache | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
+| Write-Through Cache | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
+| Write-Through Cache | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
 | Canonical Data Model | Construction | 75.482 ns | 632 B | 59.947 ns | 496 B | Generated reduced construction time and allocation in this microbenchmark. |
 | Canonical Data Model | Execution | 116.680 ns | 832 B | 92.082 ns | 696 B | Generated reduced execution time and allocation for order normalization. |
 | Channel Adapter | Construction | 38.469 ns | 384 B | 38.681 ns | 384 B | Effectively equivalent for this microbenchmark. |
@@ -236,19 +242,19 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 
 ## Coverage Matrix Summary
 
-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.
+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.
 
 | Category | Patterns | Published route results |
 | --- | ---: | ---: |
 | Application Architecture | 23 | 92 |
 | Behavioral | 11 | 44 |
-| Cloud Architecture | 18 | 72 |
+| Cloud Architecture | 20 | 80 |
 | Creational | 5 | 20 |
 | Enterprise Integration | 41 | 164 |
 | Messaging Reliability | 3 | 12 |
 | Structural | 7 | 28 |
 
-The generator matrix currently publishes 104 generator source route results.
+The generator matrix currently publishes 105 generator source route results.
 
 ## Hosting Integration Matrix Results
 
@@ -314,12 +320,14 @@ The generator matrix currently publishes 104 generator source route results.
 | Cloud Architecture | Health Endpoint Monitoring | Covered | Covered | Covered | Covered |
 | Cloud Architecture | Leader Election | Covered | Covered | Covered | Covered |
 | Cloud Architecture | Priority Queue | Covered | Covered | Covered | Covered |
-| Cloud Architecture | Queue-Based Load Leveling | Covered | Covered | Covered | Covered |
-| Cloud Architecture | Rate Limiting | Covered | Covered | Covered | Covered |
-| Cloud Architecture | Retry | Covered | Covered | Covered | Covered |
-| Cloud Architecture | Scheduler Agent Supervisor | Covered | Covered | Covered | Covered |
-| Cloud Architecture | Sidecar | Covered | Covered | Covered | Covered |
-| Cloud Architecture | Strangler Fig | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Queue-Based Load Leveling | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Rate Limiting | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Read-Through Cache | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Retry | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Scheduler Agent Supervisor | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Sidecar | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Strangler Fig | Covered | Covered | Covered | Covered |
+| Cloud Architecture | Write-Through Cache | Covered | Covered | Covered | Covered |
 | Creational | Abstract Factory | Covered | Covered | Covered | Covered |
 | Creational | Builder | Covered | Covered | Covered | Covered |
 | Creational | Factory Method | Covered | Covered | Covered | Covered |
@@ -395,7 +403,8 @@ The generator matrix currently publishes 104 generator source route results.
 | 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 |
+| ReadWriteThroughCachePolicyGenerator | `src/PatternKit.Generators/ReadWriteThroughCache/ReadWriteThroughCachePolicyGenerator.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 |
 | ExternalConfigurationStoreGenerator | `src/PatternKit.Generators/Cloud/ExternalConfigurationStoreGenerator.cs` | Covered |

docs/guides/benchmarks.md

@@ -60,6 +60,12 @@ The following numbers were captured on Windows 11, Intel Core i9-14900K, .NET SD
 | 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. |
+| Read-Through / Write-Through Cache | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Read-Through / Write-Through Cache | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Read-Through Cache | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
+| Read-Through Cache | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
+| Write-Through Cache | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
+| Write-Through Cache | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix through the read/write-through cache route. |
 | Canonical Data Model | Construction | 75.482 ns | 632 B | 59.947 ns | 496 B | Generated reduced construction time and allocation in this microbenchmark. |
 | Canonical Data Model | Execution | 116.680 ns | 832 B | 92.082 ns | 696 B | Generated reduced execution time and allocation for order normalization. |
 | Channel Adapter | Construction | 38.469 ns | 384 B | 38.681 ns | 384 B | Effectively equivalent for this microbenchmark. |

docs/guides/pattern-coverage.md

@@ -95,6 +95,8 @@ The source of truth is `PatternKitPatternCatalog` in `src/PatternKit.Examples/Pr
 | Cloud Architecture | Health Endpoint Monitoring | `HealthEndpoint<TContext>` | Health Endpoint Monitoring generator |
 | Cloud Architecture | Priority Queue | `PriorityQueuePolicy<TItem, TPriority>` | Priority Queue generator |
 | Cloud Architecture | Cache-Aside | `CacheAsidePolicy<T>` | Cache-Aside generator |
+| Cloud Architecture | Read-Through Cache | `ReadWriteThroughCachePolicy<T>` | Read/write-through cache generator |
+| Cloud Architecture | Write-Through Cache | `ReadWriteThroughCachePolicy<T>` | Read/write-through cache generator |
 | Cloud Architecture | Rate Limiting | `RateLimitPolicy<T>` | Rate Limiting generator |
 | Cloud Architecture | External Configuration Store | `ExternalConfigurationStore<TSettings>` | External Configuration Store generator |
 | Cloud Architecture | Gateway Aggregation | `GatewayAggregation<TRequest,TResponse>` | Gateway Aggregation generator |